Data Iledefrance

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: it probes and scores, requires BYO key for Anthropic with direct payment, and returns per-model results. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise paragraph that front-loads the purpose. It provides all essential information in 3-4 sentences without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 4 parameters fully described in schema and the description covering output shape (per-model fields + combined view), the tool is fully specified for correct invocation. No output schema needed given the description's clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all 4 parameters with descriptions. The description adds context: default model is free, _apiKey enables Anthropic probing with direct payment. This amplifies the meaning beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility. It specifies the default model and optional Anthropic probing, distinguishing it from sibling tools like ask_pipeworx or entity_profile.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to provide _apiKey for Anthropic. It lacks explicit when-not-to-use guidance but provides sufficient context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses non-obvious behavior: the tool is a router that selects from 5,798 tools across 1,517 verified sources, fills arguments automatically, and returns stable pipeworx:// citation URIs. This gives the agent an accurate mental model of what happens when the tool is invoked and what to expect in the response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core content is useful, but the description is heavily repetitive: the 'PREFER OVER WEB SEARCH' rule, the example list, and the 'START HERE' message are repeated multiple times. This makes the description substantially longer than needed and buries the most informative sentences under duplication.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-required-parameter, read-only routing tool, the description is largely complete: it covers when to use it, what to pass, target domains, and the expected result shape (structured answer with citations). The lack of an output schema is partially mitigated by the citation-URI statement, though it does not explicitly address how results are returned or formatted in detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage by documenting the 'question' parameter and its aliases, so the baseline is 3. The description adds value by listing trigger phrases and domain examples that clarify what kind of natural-language question should be passed, even though it does not add syntax or formatting constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific operation: it routes a natural-language question to one of many verified downstream tools, fills arguments, and returns a structured answer with pipeworx:// citations. It also enumerates covered domains and trigger phrases, making the resource easy to identify. However, it does not distinguish this tool from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data' and 'Use whenever the user asks "what is", "look up", "find", "get the latest"...' It even says 'START HERE for most questions' and includes concrete examples. It lacks explicit when-not-to-use guidance and does not mention alternative sibling tools, so it is strong but not fully comprehensive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond those annotations: it is a beta with candidate routing improvements enabled live when under test, no candidate is currently active, it currently matches ask_pipeworx exactly, and it has no fallback but is still a full working router. This clearly sets expectations about experimental behavior while reassuring that it is functional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured, front-loaded with the core identity, and each sentence adds essential information: what it is, current state, when to use it, and behavior regarding fallback. It is appropriately detailed without unnecessary repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a freeform question-routing tool, the description covers purpose, usage, current experimental status, and safety-relevant behavior through annotations. It relies on ask_pipeworx for the exact response shape, which is acceptable because the sibling is present, but it could have briefly described the routing result format if the tool were considered in isolation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with all six parameters documented as aliases for the same question string. The description only references 'same arguments' as ask_pipeworx and does not add meaningful semantics beyond what the schema already provides. Therefore, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states this is a beta version of ask_pipeworx and an identical universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge, so an agent can clearly identify what it does and how it differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use it exactly like ask_pipeworx when the agent wants the newest routing, which gives clear guidance. It also notes that results are compared against the stable router. However, it does not explicitly list when to avoid using it or mention the ask_pipeworx_grounded alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (read-only, idempotent), the description discloses the exact success shape with evidence, the refusal shape with all possible refusal_reason values, and the grounding behavior of using only the tool result. It also discloses the extra LLM call cost. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: purpose, mechanism, success contract, refusal contract, use cases, and cost alternative. It front-loads the key differentiator and avoids redundant boilerplate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since there is no output schema, the description carries the burden of explaining return values, and it does so in full detail including an exhaustive refusal_reason enum. The cost comparison and high-stakes use cases complete the picture for an agent deciding whether and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already documents the single required question parameter plus all aliases. The description adds context about routing and filling arguments but doesn't add parameter-level meaning, so it matches the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific value proposition ('Hallucination-resistant answer mode for high-stakes reads') and explains exactly what the tool does: route a question, fetch data, and extract an answer only from the tool result. It distinguishes itself from the sibling ask_pipeworx by the grounding guarantee and cost, so an agent can tell them apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on...') and an explicit exclusion ('prefer ask_pipeworx for casual lookups'). It also names the alternative ask_pipeworx and the cost tradeoff, leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description is extremely detailed about behavior: resolution, classification, fan-out, response shapes, resolver contract, parent event extractor, news fields, safety checks, closed markets, wide spreads, and resolution-rule risk. Annotations (readOnlyHint=true, destructiveHint=false) are consistent and the description adds significant context beyond them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprehensive but lengthy (multiple dense paragraphs). Information is well-organized and front-loaded with purpose and usage, but could be more concise with bullet points or sections. Some sentences are overly detailed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is exceptionally complete, covering input, process, output, edge cases, safety, and resolution-rule risk. Even without an output schema, it details the response shape. Given the tool's complexity, this is thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra semantics beyond the schema's parameter descriptions (e.g., input formats, depth defaults). No significant new meaning added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research), and lists input formats. However, it does not explicitly distinguish from sibling tools like polymarket_edges or polymarket_arbitrage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-outs for different bet types. However, it lacks explicit when-not-to-use or alternative tool mentions, though sibling list implies context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate safe read-only, idempotent operation. Description adds specific behavioral details: pulls from SEC EDGAR/XBRL for companies, FAERS for drugs, handles off-calendar fiscal years, returns sorted results with citation URIs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with usage examples. Covers essential points like data sources and return format. Slightly verbose but efficient for the information conveyed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, description explains return format (paired data + citation URIs). Addresses edge cases (off-calendar fiscal years). Completes the picture for a complex comparison tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds value by explaining type enum and providing concrete examples for values parameter (tickers/CIKs for company, drug names). The maxItems/minItems are mentioned explicitly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with examples of triggering phrases. It distinguishes from siblings like entity_profile (single entity) and sequential lookups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends preferring this tool over sequential single-pack lookups. Specifies when to use company vs drug type and explains the data sources and sorting behavior.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, covering safety and idempotency. The description adds value by specifying the concrete metadata returned (fields/schema, themes, record count), which is beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with a dash for clarity, front-loaded with the core purpose, then details and usage hint. Every part is essential and concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (one parameter, rich annotations, no output schema), the description fully covers what an agent needs: what it does, what it returns, and when to use it. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the only parameter (dataset_id), so baseline is 3. The description doesn't add new information about the parameter beyond the schema, but it implicitly ties the parameter to the tool's purpose, which is minimal added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get metadata'), the resource ('one Île-de-France Open Data dataset'), and the contents (fields/schema, themes, record count). It distinguishes from sibling tools like search_datasets and query by specifying that this is for metadata before querying.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance: 'call before query to learn the column names' tells the agent exactly when to use this tool. It implies a sequential dependency with the query tool, establishing a clear usage pattern.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context beyond them: auth tier constraints, parallel decomposition to 5,798 tools, explicit gaps[] honesty guarantee ('never invented'), contradictions[] for standard/thorough, semantic excerpting of large records, fetchable citation_uri rule, and 15-90s latency expectations. These traits are disclosed with no contradiction against the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but efficiently front-loaded: account gate and fallback tool first, then execution model, then use cases, then depth semantics, then timing. Nearly every clause earns its place, but the depth-tier behavior partially duplicates the input schema's depth parameter description, which costs a small amount of efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the full burden of documenting return values: the findings packet contents (verbatim evidence, confidence, source, fetched_at), gaps[] and contradictions[] arrays, the hop field, and citation_uri fetchability. For a high-complexity tool with an enum and multi-tier behavior, this description leaves nothing an agent needs to invoke and interpret results missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters. The description adds genuinely useful increments: the paid-plan constraint on depth:'thorough', example question phrasings, the 'single lookup' guidance that implies the question parameter shape, and latency expectations per tier. This exceeds the schema baseline of 3 without fully carrying the parameter documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call' and explicitly contrasts with 'NOT open-web search.' It also distinguishes from the sibling ask_pipeworx by naming it as the alternative for single lookups, so an agent can select correctly without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with two concrete example questions. Provides two explicit exclusions with alternatives: 'If you are not signed in, use ask_pipeworx instead — it works on every tier' and 'For a single lookup use ask_pipeworx instead.' Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it returns 'top-N most relevant tools' with 'full input schemas (with curated examples)' and notes results are 'ready to call directly, no second schema lookup needed'. This transparency about output behavior goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear purpose, followed by use cases, return value, and usage advice. It is concise but packs useful information. Slightly longer than strictly necessary due to listing domains, but well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description thoroughly explains what is returned (names, descriptions, schemas, examples) and the tool's role as a discovery entry point. It covers scope, behavior, and usage context completely for this type of tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description provides examples of queries and mentions aliases, but the schema already documents each parameter's meaning. No new semantic depth is added beyond what the input schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA drugs, etc.). It distinguishes from siblings by advising 'Call this FIRST when you have many tools available', making the tool's purpose unambiguous and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for' followed by domain examples, and suggests using this tool first. While it does not list exclusions, the guidance is clear and actionable, earning a 4.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower — yet the description adds substantial behavior beyond them: the parallel fan-out across eight source types, the 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated' caveat, expected-empty semantics ('a company with only small-molecule/generic drugs will show none here, that is expected, not a failure'), and the sources_used/sources_failed contract ('an empty section is a real "no data", not a bug'). It even covers the private-company resolved:false edge case. These are behavioral facts no annotation could convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well front-loaded: trigger phrases and core purpose in the first clause, the preference rule second, followed by sources and return semantics. Nearly every sentence earns its place — the patent sunset, expected-empty sections, and failure semantics are all high-value. It loses a point for being a single wall of text with heavy parenthetical asides and for the final type/value sentence, which is redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry return-value explanation — and it does thoroughly: cik/company_name with resolved_from/resolved_to, recent_filings with pipeworx URIs, fundamentals scoped to 'LATEST 10-K', patents, federal_contracts, fda_products, hiring, news via 'GDELT→GNews fallback', LEI, and sources_used/sources_failed. Input variants, expected-empty behavior, and failure modes are all covered. Nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: both `type` and `value` are already fully documented in the schema, including the enum interchangeability and the ticker/CIK/name forms. The description's tail ('Pass a ticker..., zero-padded CIK..., OR a company name' and 'type accepts company or ticker interchangeably') mostly restates schema content rather than adding new meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource+scope: 'full cross-source profile of a US public company in ONE parallel call.' It opens with concrete trigger phrases ('Tell me about X', 'research Acme', 'brief me on Tesla') that let an agent pattern-match user intent, and it distinguishes itself from the alternative of 'chaining single-pack SEC/XBRL/news lookups,' making it easy to tell apart from siblings like resolve_entity or compare_entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use signals: the trigger-phrase list and the directive 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' The private-company note clarifies the boundary of what this tool can handle. However, it never explicitly states when NOT to use it (e.g., when a single specific filing or a person/place is requested) or names specific sibling tools as alternatives, leaving the exclusion mostly implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide destructiveHint=true and idempotentHint=true, so the description carries less burden. It adds behavioral context about when to use but does not elaborate on the deletion behavior beyond what annotations imply. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action, no redundant information. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter destructive tool with annotations, the description is complete. It explains the operation, when to use it, and how it relates to sibling tools, leaving no obvious gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover 100% of the single parameter 'key', so the description adds no additional semantic value beyond stating 'delete by key'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete) and resource (memory by key). It distinguishes from siblings by mentioning pairing with 'remember' and 'recall', which are listed as sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage contexts: stale context, task completed, clearing sensitive data. Also notes pairing with related tools, offering guidance on when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It confirms the output format and readiness for deployment, going beyond annotation states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loads the core purpose, and every clause adds value. It avoids redundancy and is immediately scannable for an AI agent. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only 2 parameters, no output schema, and annotations cover safety, the description fully equips the agent. It explains the output format ('single text blob ready to drop at site-root/llms.txt') and the process. No missing information for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description mentions that max_links has default 25 and max 50, which is already in the schema's description. It does not add new semantic meaning beyond what the schema provides. The tool name and description imply the URL parameter's role without additional depth.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'generate' and resource 'llms.txt file for any URL'. It clearly states what the tool does: fetches a page, extracts title/description/key links, and emits standard llms.txt markdown. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' or 'deep_research' which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It implies appropriate contexts but does not explicitly list when not to use or alternatives among the 35 sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only and idempotent behavior. The description adds value by specifying return fields (id, type, params, created_at, etc.) and stating that it returns active subscriptions by default, which is useful context beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero waste. It front-loads the purpose and return values, then provides usage guidance. Every sentence is necessary and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with one optional parameter and no output schema, the description is complete. It covers purpose, return fields, and usage context. It does not mention pagination or limits, but that is acceptable for this straightforward tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the parameter 'include_inactive' already described. The description does not add extra meaning about the parameter beyond what the schema provides, so it meets the baseline for a well-covered schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists the caller's active subscriptions, specifying the exact verb and resource. It also differentiates from sibling tools like subscribe and unsubscribe by mentioning use cases for reviewing before adding or finding an id to cancel.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases: review subscriptions before adding more or find an id to cancel. It gives clear context for when to use the tool relative to siblings, though it does not explicitly state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), the claim_token flow for tracking submissions without an account, and that feedback is read daily and affects roadmap. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense; every sentence adds useful context (scope boundaries, claim_token reuse, rate limit, quota). It is slightly verbose, and the 'Free; doesn't count against your tool-call quota' sentence is helpful but could be considered extraneous. Overall, well-structured with front-loaded purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description explains return behavior: filing without an account returns a claim_token, and passing that token later returns status and resolution details. It covers routing constraints, payload expectations, rate limits, and data usage, giving an agent everything needed to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the claim_token workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising users to describe issues in terms of Pipeworx tools/packs rather than pasting the end-user prompt. This is helpful, but most parameter meanings are already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates the feedback categories (bug, feature, data_gap, praise). It clearly distinguishes this tool from sibling tools like query or ask_pipeworx, which are for data retrieval rather than reporting issues.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance for each feedback type ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog...'). It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to 'file it with that server instead' for tools from other MCP servers.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds significant behavioral context beyond annotations: mentions aggregated from CF analytics engine, no PII, caching delays (5min-1h), and that it's a self-aggregating signal. Complements readOnly and idempotent hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with primary output, followed by bulleted use cases. Every sentence provides useful information. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simple tool with 1 optional parameter and no output schema, description fully covers purpose, use cases, data source, privacy, and caching. No gaps for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes the 'window' parameter with full enum and explanation. Description repeats the same information ('Shorter windows surface what's hot right now...'). No additional semantic value added beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it returns 'top tools, top packs, and total call volume' over a recent window. Verb 'returns' is specific. Distinct from siblings like 'discover_tools' or 'query' by focusing on aggregated call popularity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Lists three explicit use cases (discovering hot data, confirming canonical tool, checking alignment). No explicit when-not-to-use or direct sibling comparisons, but context is clear enough for agent to understand appropriate scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: monotonicity violation checks, partition sum checks, Jaccard similarity threshold (0.30), placeholder filtering, fill check logic against CLOB depth, and realizable edge computation. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and modes. It then dives into technical details (similarity, partition filter, fill check). While informative, it is somewhat long (9 sentences) and could be tightened, but the structure is logical with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so the description must cover return values. It adequately describes the response structure: opportunities array with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context), partition_check object in event mode, and fill check details. However, it could be clearer about the exact format of response objects and potential edge cases. Overall, sufficient for an agent to understand what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (both parameters documented). The description adds valuable meaning beyond schema: provides example values for event slug and topic, explains how topic triggers cross-event search, and clarifies the partition check behavior. Slightly verbose but adds context for both parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It explicitly distinguishes three modes (no args, event, topic), each with clear behavior and context. This clearly differentiates it from sibling tools like polymarket_edges.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: no args for trending scan of top 200 markets; event for specific market with partition check; topic for cross-event scanning. Recommends event mode for specific markets and explains cross-event mode catches patterns single-event misses. Explicitly mentions when not to use (e.g., 'do not trade it' when fill check shows zero realizable edge). Alternatives like polymarket_fill_risk are referenced.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds extensive behavioral context: caching behavior (1h KV), three model families with mathematical details, response structure including edge_pp_net, Kelly fractions, liquidity, spread, volume, 24h move warning, and diagnostics. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer but well-structured: front-loaded with main purpose, then organized by model families, tradeable-edge knobs, and response fields. Every sentence adds value, though some details (e.g., exact historical parameters) could be streamlined. Minor room for improvement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must explain the response. It thoroughly covers response structure (by_segment with three segments, fed_candidates, diagnostics), edge calculation, Kelly fractions, and warning signals. All 9 parameters are addressed in the schema, and the description provides sufficient context for each.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

100% schema coverage already documents parameters. The description adds significant value by explaining the purpose of tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) and providing usage guidance like 'Bump for very thin partitions; drop to 0 if you have a smarter fill model.' This enhances understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by detailing three unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the use case ('what should I bet on today'), explains tradeable-edge knobs (min_liquidity, max_spread_pp) with when to apply them, warns about Fed bets being unreliable, and provides diagnostics so callers can see why a segment is empty. This gives clear guidance on when and how to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly, idempotent, non-destructive. The description adds rich behavioral context: output fields (tracked, expired, snapshot_dates), trend computation details (new, widening, stable, decaying), and decay interpretation. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized: purpose, output format, limits. It is dense but each sentence adds value. Slightly verbose in the output description but still effective. The front-loaded question makes intent clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and key details. It also mentions limits (60-day TTL, snapshot start). Missing error handling or edge cases, but adequate for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters are fully described in the schema (100% coverage). The description adds value by specifying defaults and ranges (days default 14, max 30; window default '1wk' and families) beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides 'Edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the likely sibling 'polymarket_edges' by focusing on temporal dynamics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a compelling rationale for when to use this tool ('a fresh wide edge and a 3-week-old wide edge are different trades') and mentions limits (60-day TTL). It implicitly tells the agent to use this for historical edge behavior, but does not explicitly exclude alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, which are consistent. The description adds behavioral details: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), warns about thin legs and forced directional risk. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long (4 paragraphs) but well-structured with sections for single-market and basket modes. It is front-loaded with the core purpose, but some details could be abbreviated. Given the tool's complexity, the length is justified, so a slight deduction for not being more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description fully explains return values for both modes, including edge cases (thin legs, partial fills, forced directional risk). It covers all aspects needed for an agent to understand and use the tool correctly, given the high parameter coverage and annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds significant extra meaning: explains the difference between single-market and basket modes, auto-detection for side in basket, interpretation of size_usd as 'settlement notional' for basket, and clamp range. Goes well beyond repeating schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific and avoids tautology, differentiating from sibling tools like polymarket_arbitrage and polymarket_edges.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' and explains the consequences of not using it (theoretical overround not capturable, partial fills cause directional risk). Provides clear when-to-use and why.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even with readOnlyHint and idempotentHint already set, the description goes far beyond by disclosing matching limitations (pairing_unverified, compatibility codes), the null meaning of temporal_alignment, unclassified leg exclusion, fee treatment, and that returned spreads are gross. No statement contradicts the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but densely organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, top_spreads, fees_note, counters) and the central purpose is front-loaded. Every substantive block addresses a caveat an agent would otherwise only discover at runtime.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully documents return shape (leg prices, top_spreads_pp, flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note) and edge-case semantics. It leaves no important call-time behavior unexplained for a complex two-venue matching tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it enumerates the topic aliases, explains that explicit parameters override the topic-mapped side, and states that both modes run the same token-overlap matcher. This exceeds the schema's one-line parameter descriptions without over-specifying.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clarifies the 2-25pp pricing divergence and distinguishes this tool from sibling Polymarket tools by naming both venues and the matching requirement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly defines two modes (topic shortcuts vs explicit ticker/slug) and explains when each is appropriate, including that pre-mapped topics are not necessarily tradeable. It does not explicitly name sibling alternatives such as polymarket_arbitrage, so exclusion guidance is slightly weaker than a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating safe, read-only, idempotent behavior. The description adds behavioral details such as the use of ODSQL and the 'where' parameter overriding 'query'. Since annotations are rich, the description provides moderate additional context but no contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that immediately conveys the purpose and key capabilities. It is front-loaded with essential information—action, resource, language, and operations—without extraneous detail. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 8 parameters, no output schema, and rich annotations. The description covers the core idea and main operations, but does not mention return format, error handling, or pagination behavior beyond mentioning limit/offset. Given the complexity, it is adequate but could be slightly more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description groups parameters by operation (filter, aggregate, etc.) and introduces ODSQL context, but does not add significant meaning beyond the schema's parameter descriptions. The schema already documents each parameter well (e.g., limit range, where syntax).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Query records from a Île-de-France Open Data dataset with ODSQL.' It specifies the resource (records from a dataset), the query language (ODSQL), and lists key operations (filter, aggregate, sort, paginate). This is specific and distinguishes from sibling tools, none of which appear to perform similar querying.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists the operations available (filter, aggregate, sort, paginate), which implies when to use the tool—when you need to query data with ODSQL. However, it does not explicitly state when not to use it or suggest alternative tools. Sibling tools like 'search_datasets' and 'validate_claim' are different, but no comparison is made.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare read-only, idempotent, non-destructive. Description adds valuable context about scoping and listing behavior, though return format is implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three efficient sentences: purpose, usage, and scoping. No redundancy, front-loaded with key action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given annotations and schema, the description sufficiently explains behavior. No output schema, but return type is inferable from context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers the only parameter (key) with description. Description reinforces the 'omit to list' behavior, adding clarity beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves a saved value or lists all keys, with explicit reference to companion tools 'remember' and 'forget', effectively distinguishing from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (to look up stored context) and when not (avoid re-deriving), and explains pairing with remember/forget, plus scoping details.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states that setting mark_read:true 'flag[s] returned events read' which implies a side effect, contradicting the readOnlyHint:true annotation. This is a critical inconsistency that undermines transparency. No other behavioral disclosure beyond the contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the core purpose, and every sentence adds unique information. There is no redundancy or fluff. It efficiently conveys purpose, return structure, parameters, and alternative access.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers return fields (source, citation_uri, raw payload), filtering options, mark_read behavior, and alternative access. Given the tool's simplicity (all optional params, no output schema), this is sufficient. Missing details like ordering or error handling are minor given the openWorldHint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (all 5 parameters are described in the schema). The tool description adds value by providing examples (e.g., 'sec_8k' for type) and explaining the effect of mark_read on future calls ('next call only shows newer ones'). This goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Pull fired events') and the resource ('subscription feed'), and distinguishes itself from siblings like 'list_subscriptions' by focusing on events rather than subscriptions. The verb-noun pairing is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage context (filtering, mark_read, polling) and mentions an alternative HTTP endpoint, but does not explicitly compare with sibling tools or state when not to use this tool. No explicit exclusion criteria or comparisons are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses internal behavior: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail. Annotations already indicate read-only and idempotent, but description adds crucial context about fallbacks, return structure (changes[] grouped by source, total_changes, citation URIs), and edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is fairly dense but well-structured: starts with example queries, then explains sources, parameters, return format, and alternative tool. Could be slightly more concise (e.g., some redundancy in fallback explanation) but overall efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers return structure (changes[], total_changes, citation URIs). It also addresses edge cases like soft-fail for patents and fallback mechanism. Contextually complete for a multi-source aggregation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant meaning: explains `since` accepted formats (ISO date or relative like '7d'), `value` can be ticker or CIK, `type` currently only 'company'. Provides concrete examples that help an agent construct correct calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it's a change feed for a company across multiple sources (SEC, news, patents) and distinguishes from the sibling tool entity_profile for static profiles. The verb 'change feed' with examples like 'what's new with X' makes purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains when to use (e.g., 'what's new', 'latest on Y') and when not (use entity_profile for static profile). Provides detailed parameter guidance with examples for `since` (ISO date or relative shorthands) and `value` (ticker or CIK).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds significant context beyond annotations: key-value scope by identifier, persistence for authenticated vs. anonymous sessions (24 hours). No contradiction with annotations (idempotent, not destructive, not read-only).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four well-structured sentences with front-loaded purpose. No wasted words; each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with 2 required params and no output schema. Description adequately covers purpose, usage, persistence, scope, and sibling pairing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds no new parameter details beyond schema, but provides usage context for key-value pairs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool saves data for reuse across conversations/sessions. It specifies the verb 'save' and resource 'data as key-value pairs', and distinguishes from siblings like recall and forget.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use: 'when you discover something worth carrying forward'. It mentions pairing with recall/forget but lacks explicitly when-not to use or alternatives beyond siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite strong annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint false), the description adds substantial behavioral detail: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns figi_candidates when matches are ambiguous, and explicitly lists unresolved identifiers rather than omitting them. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is thorough but overlong and dense, especially the long parenthetical about the company identity spine. It is front-loaded with useful examples and 'Use FIRST', and it is organized under SUPPORTED TYPES, but many details could be trimmed or bulleted for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return behavior, and it does so well: it names the returned identifiers (CIK, ticker, company_name, LEI, FIGI, RxCUI), explains unresolved fields and figi_candidates, and covers failure/degradation modes. An agent has enough context to invoke the tool and interpret its results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers both parameters, so the baseline is 3, but the description adds far more: concrete examples (AAPL, CIK, ISIN, 'ozempic', 'metformin'), the distinction between issuer and security name for bonds, and the explicit warning to pass only the entity name. This materially improves the agent's chance of passing the correct value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with concrete user-phrase examples and a clear verb+resource statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes the tool's scope from siblings by explaining it produces IDs for other tools, not profiles or comparisons.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also elaborates on supported types and edge cases, but it does not explicitly name alternatives like entity_profile or compare_entities or state when to prefer them, so it stops short of full when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density, plus first-entity-as-subject treatment. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. First sentence states core purpose, second adds detail and use case. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, description adequately describes return values (score, confidence, signal density per entity). Covers model selection, required/optional params. Could mention error handling or limits but sufficient for use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions. Description adds value by explaining first entity as subject, contextual use of context parameter, and model/API key roles. Provides nuance beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool compares AI visibility across multiple entities, lists the output (ranked list with scores), and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (different comparison).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly positions the tool for competitive AI-marketing audits ('does Claude know about us as well as our competitors?'), providing clear use context. Lacks explicit when-not-to-use but implies alternatives (single probe vs. comparison).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/ idempotent/ non-destructive; description adds critical behavioral details: composite call fan-out, bundlephobia's 5-30s timeout, partial failures with sources_failed, and graceful degradation. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single paragraph that front-loads the core purpose. Every sentence adds value, though slightly verbose. Could be tightened without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description thoroughly explains return structure (summary block, advisories, links, alternative versions) and edge cases (partial failures, ecosystem limitations). Sufficient for agent understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for both parameters. The description adds minor context (scoped packages, default to latest) but does not significantly enhance meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs a composite check for npm packages, covering license, advisories, version history, and bundle size. It uses specific language like 'safety, popularity, size' and contrasts with alternatives, distinguishing it from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and mentions ecosystem constraints (NPM only, partial failures, timeout). Does not list sibling tools by name but provides contextual guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds that results include dataset_ids, titles, themes, and record counts, which is useful but not critical. No behavioral traits beyond annotations are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is a single front-loaded sentence with a parenthetical listing scope and a follow-up detailing return values. Every word serves a purpose; no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description adequately covers return values (dataset_ids, titles, themes, record counts) and hints at the downstream usage. Parameter coverage is complete. A search tool with this level of detail is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters. The description adds minor context (e.g., 'pass to query/dataset_info') but does not enhance parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (search), resource (Île-de-France Open Data datasets), and what is returned (dataset_ids, titles, themes, record counts). It distinguishes itself from siblings like dataset_info and query by indicating that the returned IDs can be passed to those tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (searching a specific dataset catalog) and hints at a workflow (pass dataset_ids to query/dataset_info), but lacks explicit when-to-use vs. when-not or clear exclusions. It is clear enough for most cases but misses explicit alternative differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnly, idempotent), describes embedding model (BGE-base-en), similarity (cosine), windowing (500-char overlapping), and cap (200K chars with truncation flag). Rich behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single focused paragraph, no wasted words. Action verb 'pass' front-loaded, every sentence adds distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all aspects: purpose, parameters, usage, behavior, limitations, and return structure (offsets, scores). No output schema but adequately described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% but description adds value by explaining 'text' as document content, 'query' with examples, and default for 'limit'. Elevates baseline 3 due to extra context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article). Distinct from siblings like 'search_datasets' or 'ask_pipeworx' by focusing on within-document retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and pairs with 'ask_pipeworx_grounded'. Clearly explains context-saving benefit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral details: it's a create operation, requires authentication, returns an id, and explains rate limits (10 SMS/day). It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise yet comprehensive, with no wasted sentences. It is well-structured: purpose, return, requirements, type examples, delivery channels. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (3 params, nested objects, no output schema), the description covers everything: return value, auth requirements, type-specific filters, delivery channels, and limitations. It is fully self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema coverage at 100%, the description still adds significant value by providing concrete examples for each parameter, explaining the semantics of the type and params fields, and detailing delivery options beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses specific verbs and resource, and distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit context on when to use the tool, including requirements (OAuth account) and supported types. It doesn't explicitly state when not to use alternatives, but the purpose is clear enough. The delivery channels and limitations (e.g., SMS cap) are well explained.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable context: it returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog. No contradictions with annotations. It enhances transparency about the tool's behavior and output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is somewhat lengthy but well-structured. It begins with example queries to quickly convey intent, then explains the output and usage instructions. Every sentence adds value, but it could be slightly more concise. However, the front-loading of examples makes it effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simple role as an onboarding guide, the description is fully complete. It explains what the tool does, how to use it (no arguments vs topic), what the output contains (categorized questions with tool shapes), and why it should be used first. No output schema is needed, and the description covers all essential aspects for an agent to understand and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single optional parameter 'topic', with a description. The description enriches this by listing example topic values and explaining what happens when omitted (full spread). This adds practical meaning beyond the schema, helping the agent understand how to use the parameter effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as the onboarding entry point that returns categorized example questions with tool+argument shapes. It lists explicit user intents like 'what can I ask?' and distinguishes its role from siblings by emphasizing it is for initial exploration when the agent doesn't know Pipeworx's capabilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It provides clear usage instructions: call with no arguments for full spread or pass a topic for focus. It also mentions it teaches how to call meta-tools. While it does not explicitly state when not to use it, the guidance is sufficient for proper selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the row is deactivated (not deleted) and that historical events remain via recent_alerts, adding context beyond annotations. Annotations already indicate non-destructive mutation, and the description elaborates meaningfully.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no unnecessary words, front-loaded with the action verb. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description covers all needed behavioral context: ownership, soft delete, and link to related tool. Annotations complement well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully covers the single parameter with a clear description. The tool description only repeats 'by id' without adding new semantic meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Cancel a subscription by id.' The verb 'Cancel' and resource 'subscription' are specific, and the tool is distinct from siblings like 'subscribe' and 'list_subscriptions'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing a clear condition for use. However, it does not explicitly state when not to use or mention alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, and non-destructive, but the description adds crucial behavioral details: the exact verdict enum, the critical distinction between could_not_verify and unsupported (with the warning that could_not_verify carries verification_error and must not be shown as evidence), and the internal pipeline routing. This exceeds annotation coverage significantly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: trigger phrases, usage directive, routing logic, return format, and a critical error-handling warning. It is front-loaded with the most important identification cues and remains structured for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by listing the full verdict vocabulary and describing the return structure (value, citation, reasoning). It also covers the two claim categories and the error semantics, making it fully sufficient for an agent to understand expected behavior and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both claim and tolerance_pct fully described including defaults and examples. The description adds minimal beyond the schema—only re-emphasizing 'exact percent-delta math' and the default cap—so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's function as natural-language claim verification, listing multiple trigger phrases ('fact check', 'verify the claim that…'). It distinguishes itself from siblings by explaining the two routing paths (SEC EDGAR fast path for company financials vs. grounded pipeline for all other claims) and explicitly notes it replaces 4–6 sequential calls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and outlines the two claim categories with their respective handling. However, it does not name alternative tools or exclusion cases (e.g., when to use deep_research instead), so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.