F1

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that Anthropic probing requires BYO key and direct payment, plus output structure (score, confidence, signals, raw_response). 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?

Three sentences, front-loaded with main action. Could be slightly more concise, but no fluff and 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?

No output schema, but description mentions return fields (score, confidence, signals, raw_response, combined view). Covers multi-model probing, payment model, and use cases. Lacks detail on exact behavior of combined view, but sufficient for most agents.

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 noting default model, that _apiKey is optional and required only for Anthropic, and summarizes output fields. Helps agent understand parameter usage 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 uses specific verb 'probe' and clearly states it scores visibility (0-100) per model. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on brand/business visibility rather than competitor-specific scanning.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly state when not to use or name alternatives, but context is clear.

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 (readOnly, idempotent, non-destructive), the description discloses that it 'fills arguments', returns stable citation URIs, works on every tier, and makes one fast call. It also explains that it routes to live news for breaking-news queries, adding behavioral context not present in 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?

Although the description is long, it is front-loaded with the most important directive and every sentence adds actionable detail (use cases, examples, alternatives). There is no fluff or 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?

Given no output schema, the description compensates by stating it returns 'the structured answer with stable pipeworx:// citation URIs' and specifies the range of sources. It also covers escalation to grounded and deep_research, making the tool's role in the broader ecosystem clear.

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 required 'question' parameter and five aliases all described. The description reinforces natural-language usage but does not add new parameter meanings beyond examples like 'current US unemployment rate' and 'Apple's latest 10-K'.

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 'PREFER OVER WEB SEARCH' and clearly states it 'Routes the question to the right one of 5,529 tools across 1455 verified sources... returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming them as escalation paths.

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 this tool ('Use whenever the user asks...', 'START HERE for most questions') and when not to ('Step up only when needed: ... use ask_pipeworx_grounded; ... use deep_research'). Also mentions web search as an alternative to prefer over.

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, and idempotent. The description adds useful context: it is experimental, may have live candidate routing, currently matches stable, and results are compared against the stable router for merge decisions. This 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?

About 90 words, front-loaded with 'Beta version of ask_pipeworx'. Each sentence adds relevant information: current state, usage, and comparison behavior. Not overly verbose for the amount of context provided.

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 beta variant of a well-known tool with no output schema, the description adequately covers purpose, current status, usage, and evaluation behavior. It does not explain return values, but since it is identical to ask_pipeworx, that is acceptable.

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 6 parameters with descriptions, so the high coverage baseline is 3. The description only says 'same arguments', which adds no semantic detail beyond what the schema already provides.

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 it is a beta version of ask_pipeworx with identical functionality but experimental routing improvements. It distinguishes itself from the stable sibling tool ask_pipeworx by noting it is the experimental edge.

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 to use it exactly like ask_pipeworx when you want the newest routing, giving a clear condition for use. It does not explicitly list exclusions or name the stable alternative, but the contrast with the stable router is strongly implied.

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?

Goes well beyond the annotations (readOnly, openWorld, idempotent) by disclosing the extraction mechanism, refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the return payload (answer, evidence, confidence, source, fetched_at). This is rich behavioral context that annotations alone do not 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?

Dense but every sentence earns its place: purpose, routing behavior, return contract, refusal conditions, use cases, and cost comparison. The description is front-loaded with the core value proposition and structured for quick comprehension despite its length.

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 compensates by fully specifying the return format and all refusal modes. It also addresses the key tradeoff versus ask_pipeworx and provides sufficient context for an agent to decide and invoke correctly. Nothing critical 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 covers 100% of parameters, so baseline is 3. The description does not add any parameter-level detail beyond what the schema already states (natural language question with aliases). No additional semantics needed; the schema is sufficient.

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 this is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results, and it explicitly contrasts itself with ask_pipeworx. The verb+resource is specific (grounded question answering) and the return structure is defined, making it distinct from all 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?

Provides explicit when-to-use ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), plus a cost tradeoff (one extra LLM call). Names the alternative tool directly, making guidance actionable.

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 discloses extensive behavioral traits beyond the annotations: fan-out behavior, response shapes, resolver contract with confidence levels, parent event extraction, news fallback handling, safety mechanisms for low-confidence matches, closed market handling, illiquidity warnings, and resolution-rule risk. No contradictions with annotations (readOnly, idempotent, non-destructive).

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 lengthy but well-organized with clear section markers (e.g., RESPONSE SHAPES, RESOLVER CONTRACT, NEWS FIELDS). Each paragraph adds value. Minor redundancy could be trimmed, but the complexity of the tool justifies the length.

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 complexity (3 params, no output schema, rich annotations), the description is exceptionally complete. It covers all edge cases: low-confidence matches, closed markets, wide spreads, cancellation rules, fallback behaviors, and parent event extraction. The agent can safely invoke the tool without guessing.

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 has 100% parameter description coverage. The description adds significant meaning: explains market input formats (slug, URL, question text), depth enum with quick/thorough meaning, include_raw with default and rationale. This goes well beyond the schema's structured definitions.

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 input types (slug, URL, question text) and output structure (evidence packet + market-vs-model comparison). The purpose is distinct from sibling tools like polymarket_edges or polymarket_arbitrage, though not explicitly differentiated.

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 usage guidance: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It does not include when-not-to-use or alternative tools, but the context is clear enough for an agent to infer 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, and destructiveHint. The description adds valuable behavioral context: mentions specific data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years, returns sorted results and citation URIs. 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 somewhat long but front-loaded with clear query examples. Every sentence adds value; however, it could be slightly more concise 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?

Given the tool has two well-defined parameters and no output schema, the description covers all necessary aspects: input format, data sources, behavior (sorted results, citation URIs), and entity-specific details. It is complete for an agent to select and invoke 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%, but description adds meaning beyond schema: explains that 'company' pulls latest 10-K data (revenue, net income, etc.) and 'drug' pulls FAERS counts. Provides examples for values parameter (e.g., tickers for company, drug names).

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 does side-by-side comparison of 2-5 companies or drugs, specifying data sources (SEC EDGAR for companies, FAERS for drugs). It distinguishes itself from siblings like entity_profile by explicitly noting it replaces sequential single-entity 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?

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It gives example query patterns ('X vs Y', 'which is bigger') and specifies entity types with clear data points.

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 annotations, the description discloses decomposition and parallel routing, the findings packet structure (evidence, confidence, source, fetched_at, citation), gaps[] with a 'never invented' guarantee, contradictions[] for standard/thorough, resolvable citation_uri behavior, semantic excerpting, and latency ranges. This goes far beyond the minimal safety 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?

The description is long but well-structured and front-loaded with the most critical info (account requirement, alternative). Each sentence carries useful information: use cases, exclusions, depth semantics, citation behavior, latency. It could be tightened around the middle, but no sentence is wasted.

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?

Even without an output schema, the description fully explains what the agent will receive (findings packet with evidence, gaps[], contradictions[]) and how to handle edge cases (not signed in, breaking news, long documents). Latency expectations and depth behaviors are also covered, so an agent can confidently invoke and set user expectations.

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 both parameters, but the description adds significant semantic depth: it explains the paid 'thorough' tier, the gap-recovery behavior of 'standard', the lead-chasing of 'thorough', and which question types are appropriate. This substantially enhances what the schema already provides.

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 ('researches') and clearly scopes the resource ('1455 STRUCTURED data sources' across SEC, FRED, FDA, etc.). It explicitly distinguishes the tool from open-web search and from the sibling ask_pipeworx (single lookup, current news), making the 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?

The text explicitly states when to use deep_research ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also notes account requirements and the fallback for signed-out users, leaving no ambiguity.

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 explains it returns top-N relevant tools with full schemas and examples, ready to call directly. This adds value beyond readOnlyHint and idempotentHint annotations, and does not contradict 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 front-loaded with the core purpose, then lists domains, then describes output and usage advice—concise and well-structured without wasted 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?

Covers return format and usage context well, but does not explain how relevance ranking works or the exact default limit (though schema covers limit). Still sufficient for a discovery 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 baseline is 3. The description does not add significant parameter semantics beyond what the schema already provides (natural language query, aliases, limit).

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 finds tools by describing data or task, and lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools like deep_research or search_within.

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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use 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?

The description discloses that the patents endpoint relies on an API sunsetting May 2025 (soft-fail) and mentions a fallback chain (GDELT→GNews). Annotations already confirm read-only, idempotent, non-destructive behavior, and the description adds value with 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 fairly long but well-structured, starting with example queries, then stating usage preference, then listing output details and caveats. All sentences serve a purpose, though some minor tightening could improve conciseness.

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 the return fields (CIK, filings, fundamentals, patents, news, LEI) with details like URI formats and fallback behavior. It also covers edge cases like patent API sunset and name unsupported. Complete for effective 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%, so the schema already documents both parameters. The description repeats the value format (ticker/CIK) and adds the note about names not being supported, but this does not significantly enhance understanding beyond the schema. 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?

The description clearly states the tool returns a full cross-source profile of a US public company, listing specific data sources and fields. It distinguishes from sibling tools like resolve_entity by explicitly stating to use that tool first if only a name is available.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and mentions names are not supported, directing to resolve_entity as an alternative. This provides clear when-to-use and when-not-to-use 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?

The description's 'Delete' aligns with the annotations' destructiveHint=true and readOnlyHint=false. It adds context about clearing sensitive data, but the annotations already cover the destructive nature. No additional behavioral traits (e.g., side effects, required permissions) are disclosed beyond 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 extremely concise: two short sentences. The first sentence defines the action, and the second provides usage guidance. There is no redundant or irrelevant information; 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?

For a tool with one required parameter and no output schema, the description sufficiently covers the tool's purpose and when to use it. It does not need to explain return values, and the usage scenarios are adequate for an agent to decide when 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?

The schema has 100% coverage with one parameter 'key' described as 'Memory key to delete'. The description does not add any further meaning or usage details beyond the schema, so 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 clearly states the verb 'Delete', the resource 'previously stored memory', and the method 'by key'. It also distinguishes from sibling tools 'remember' and 'recall' by naming them, making it easy for an agent to understand its purpose.

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 provides three scenarios for using the tool: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with 'remember' and 'recall'. While it does not specify when not to use, the guidance is clear and actionable.

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 behavior. The description adds value by detailing the process: fetching the page, extracting title/description/key links, and emitting standard markdown format. This goes beyond annotations without 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 concise, with three sentences: purpose, process, use cases. Each sentence adds value, and the key information is front-loaded. No redundancy or 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 2 parameters with full schema coverage and safety annotations, the description is fairly complete. It explains the output (a text blob) and the main steps. However, it could briefly note potential errors or limitations, but not critical.

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 description doesn't need to add much. It does not explain the 'url' parameter beyond what's in the schema, and for 'max_links' it repeats the schema's default and max. No extra semantic value is provided.

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 generates an llms.txt file for a URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes itself from siblings by focusing on a specific output format for AI crawlers, with no overlapping sibling tool for the same purpose.

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 three explicit use cases (client indexing, own project, competitor auditing), providing clear context for when to use. However, it does not mention when not to use or explicitly differentiate from related sibling tools like 'scan_competitor_ai_presence', missing some exclusion criteria.

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 value by specifying the exact output fields (position, points, wins, driver name, constructor) and confirms it returns all drivers, which aligns with openWorldHint.

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, direct sentence that conveys the purpose and output without any unnecessary words 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 no parameters, presence of an output schema, and clear annotations, the description fully covers what the tool does and what it returns. No missing information for an agent to 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?

The tool has zero parameters, so the description cannot add value beyond the schema, which already has 100% coverage. Baseline 4 is appropriate for a parameterless tool.

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 checks the current F1 driver championship standings and lists the returned fields (position, points, wins, driver name, constructor). This distinguishes it from sibling tools like get_driver (single driver) and get_race_results (race-level data).

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?

No guidance on when to use this tool vs alternatives such as get_driver or get_race_results. The description does not mention exclusions or context, leaving the agent to infer usage.

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, idempotentHint, openWorldHint, and destructiveHint. The description adds the return fields, but since an output schema exists, this information is likely redundant. No additional behavioral context 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 a single sentence of 12 words, directly stating the purpose and return fields. It is highly concise and front-loaded with the 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 the simplicity of the tool (1 required parameter, no enums, output schema present), the description adequately covers the tool's purpose and output. It slightly lacks mention of prerequisites (e.g., valid driver ID) but examples in schema compensate.

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 description coverage is 100% for the driverId parameter, with clear examples. The description does not add any semantic information beyond what the schema already provides, so 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 clearly states the action ('Look up'), the resource ('F1 driver profile by ID'), and the specific fields returned. This distinguishes it from sibling tools like get_race_results or get_current_standings.

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 when to use the tool (to look up a driver by ID) but does not provide explicit guidance on when not to use it or mention alternatives. No exclusions or contrasts with 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds value by listing returned fields (finishing position, driver, constructor, status, points). 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 concise sentences, front-loaded with purpose, and no wasted words. Perfect structure for a simple tool.

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 simplicity (2 params, output schema exists, rich annotations), the description covers purpose, usage, and return fields adequately. Missing only guidance on filter scope or edge cases, but sufficient overall.

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 both parameters. Description reinforces the parameters with examples but adds no new semantic depth beyond the schema. 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?

Clearly states it gets race results for a specific F1 grand prix with season year and round number. However, it does not explicitly differentiate from sibling tools like get_current_standings or get_schedule, so a strong 4.

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 usage context by specifying required parameters (season year and round number) with examples. Does not mention when to avoid this tool or suggest alternatives, so it lacks exclusion 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 indicate read-only, idempotent, and non-destructive behavior. The description adds detail about the return contents (race name, circuit, etc.), enhancing transparency.

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 action, no wasted words. Efficiently conveys all necessary 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?

Output schema exists, so return values are covered. The description mentions key output fields, making it complete for a simple calendar lookup 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 a clear description. The description reinforces the parameter with example values, adding practical guidance 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 action ('Get') and the specific resource ('F1 season race calendar'). It distinguishes from sibling tools, which are unrelated to F1 schedules.

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 example year usage and implies when to use this tool. Lacks explicit when-not-to-use or alternative tools, but context makes it clear.

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 cover readOnly, openWorld, idempotent, non-destructive. Description adds return fields and mentions active/inactive via parameter context. Does not add significant behavioral details 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?

Two sentences, no wasted words. First sentence states purpose and fields, second provides usage guidance. Efficiently conveys necessary 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?

Given single parameter, high schema coverage, and annotations, description covers purpose, fields, and usage guidance. Minor gap: implicitly restricts to caller's subscriptions but doesn't explicitly state that. Otherwise complete for a simple list 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%; parameter 'include_inactive' is fully described in schema. Description does not add additional details about parameter format or behavior beyond what schema 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 verb (list), resource (subscriptions), and scope (caller's active). Specifies returned fields. No explicit differentiation from siblings like subscribe/unsubscribe, but context of subscription management is implied.

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 use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' Lacks exclusions or when-not-to-use, but the guidance is clear and actionable.

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 only provide hints (all false), but the description adds substantial behavioral context: rate-limiting ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), the claim_token flow for follow-up, and the fact that the team reads digests daily. This goes far beyond what annotations convey, with 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 but dense—every sentence earns its place. It front-loads the core purpose and then adds necessary operational details. The prose is somewhat monolithic and could benefit from list formatting, but there is no redundancy or filler.

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 4 parameters with a nested object and no output schema, the description covers all essential aspects: when to use, exclusions, how to identify relevant tools, the claim_token lifecycle, rate limits, and cost. It even explains what happens on return when passing a token later, making it complete for an agent to invoke 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%, but the description adds critical semantics: it explains how claim_token is used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), clarifies that passing only the token reads a prior report, and outlines the meaning of type values. This enriches the schema descriptions with usage patterns.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the action (providing feedback), and distinguishes it from sibling tools like ask_pipeworx and deep_research by focusing on reporting issues rather than querying or researching.

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 is provided for when to use this tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusion criteria—'if the tool came from a different MCP server... file it with that server instead'—and offers a heuristic for identifying Pipeworx 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: self-aggregating from CF analytics-engine, no PII, cached 5min-1h, which goes 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?

Description is concise (three sentences), front-loaded with the core purpose, followed by usage cases and a note on derivation. No wasted 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?

For a simple tool with one parameter, no output schema, and rich annotations, the description provides sufficient behavioral context (source, no PII, caching) to enable correct 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 covers the sole parameter 'window' with enum and description. Description reinforces the options (24h,7d,30d) and adds guidance on when to use each, but does not add significant new semantics 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?

Description clearly states the verb 'Returns' and the resource: top tools, top packs, and total call volume over a recent window. It distinguishes itself from sibling tools like discover_tools by focusing on agent usage trends rather than general search.

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 lists three concrete use cases (discovering hot data sources, confirming canonical choices, checking alignment). Does not provide when-not-to-use scenarios, but the guidance is clear and actionable.

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 true, and destructiveHint false. Description adds context about side effects: it performs scans, computes checks, returns signals, and details the fill check behavior (theoretical vs realizable edge) and when to avoid trading. 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 lengthy but well-organized with sections for different modes, semantic anchor, partition filter, and fill check. Every sentence adds value, though some detail could be streamlined without losing clarity.

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 fully explains the response structure including opportunities[] fields and partition_check{} fields. It also references a sibling tool for additional functionality, making it complete for a complex 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% (both parameters documented in input schema). Description adds significant meaning: explains the purpose and behavior of event and topic, provides example values, and describes semantic anchor and partition filter logic that are not 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 clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) with specific examples, and differentiates from sibling tools like polymarket_fill_risk.

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 instructions for when to use each argument: no args for trending scan, event for a specific market, topic for cross-event scanning. Also provides when-not-to-trade guidance based on fill check results and recommends polymarket_fill_risk for custom sizing.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with description. The description adds extensive behavioral details including caching (1h at KV level), diagnostics, tradeable-edge knobs, and detailed model explanations, far exceeding minimal requirements.

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 very long and dense, covering extensive technical details. While all content is relevant, it lacks conciseness and could be better structured with sections or bullet points for clarity.

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 and nested objects, the description provides a comprehensive overview of the response structure, diagnostics, caching, and all knobs. It equips an AI agent with sufficient information to use the tool effectively.

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 100% schema description coverage, baseline is 3. The description adds valuable context beyond the schema, such as explaining tradeable-edge filters and slippage assumptions, justifying a higher score.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly positions it as built for 'what should I bet on today' discovery and distinguishes it from sibling tools by detailing unique model families and response segments.

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 clear usage context: 'agents discover opportunities without paging hundreds of markets' and explains various knobs like min_liquidity, max_spread_pp, etc. It lacks explicit when-not-to-use or alternatives but offers sufficient implicit guidance given the tool's specialized role.

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, and destructiveHint. The description adds substantial behavioral context: output structure (tracked, expired, snapshot_dates), field meanings, trend analysis, decay computation, and limitations like snapshot TTL and data gaps.

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 relatively long but well-structured with labeled sections (RESPONSE, LIMITS) and front-loaded with the main purpose. Every sentence adds value, though some minor trimming could improve conciseness.

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 compensates by detailing the output structure, including all fields and their meanings. Parameters are thoroughly explained, and limitations are addressed. This makes the tool's behavior fully understandable.

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 provides 100% coverage with descriptions for both parameters. The description adds defaults, allowed ranges, and valid values for 'window', enhancing clarity 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?

Description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age and shrinkage. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis.

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?

Description implies usage for analyzing edge longevity but does not explicitly state when to use this tool versus alternatives like polymarket_edges or polymarket_arbitrage. No exclusions or alternative suggestions are provided.

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 goes well beyond annotations (readOnlyHint, idempotentHint, etc.) by detailing behavioral traits: walks the ladder, returns specific outputs (top_of_book, vwap_fill_price, slippage_pp, etc.), and crucially warns of forced directional risk from partial basket fills—the dominant loss mode. 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 comprehensive and structured with clear sections (SINGLE-MARKET, BASKET, warnings), but it is quite lengthy. While every sentence adds value, a slightly more condensed version could improve scanability. Still, it earns a 4 for being well-organized 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 the lack of an output schema, the description fully details return values for both modes (top_of_book, vwap_fill_price, slippage_pp, etc., plus per-leg detail and risk indicators). It also explains the risk of partial fills and forced directional risk. The description leaves no gaps about what the tool returns or when to use 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?

With 100% schema coverage, the description still adds significant value: explains side default logic for basket mode ('auto from partition sum'), clarifies size_usd interpretation for basket ('settlement notional S—shares per leg'), and defines modes. The description makes all parameters' semantics crystal clear 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly contrasts with sibling tools polymarket_arbitrage and polymarket_edges, telling the agent to use this tool before those. The verb 'check' and resource 'fill risk' are specific and non-tautological.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable, partial basket fills convert arb into directional position). It also mandates parameter selection: 'REQUIRES one of market or event.' This fully informs the agent on context and 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 already indicate readOnly, idempotent, open-world. The description adds extensive behavioral context: it explains the two modes, the response structure (leg-by-leg prices, spread, safety fields), and details the compatibility_warning cases (non-equivalent bet shapes, semantically unrelated events) and temporal_alignment significance. 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-structured with sections for modes, response, and safety fields. However, it is verbose, especially listing all topic shortcuts and repeating some explanatory text. Front-loading of purpose is good, but some sentences could be trimmed without losing 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?

Given no output schema, the description fully explains the response structure, safety fields, and their interpretations. It covers edge cases (compatibility_warning causes, temporal alignment, skipped cross types), making the tool's behavior completely transparent to an agent.

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 the description adds meaning beyond the schema by explaining the interaction between parameters (topic mode vs explicit overrides) and listing all topic shortcuts explicitly. It clarifies that explicit tickers override the mapped side, which is not obvious from 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 identifies the tool as calculating the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by focusing on cross-venue arbitrage, unlike polymarket_arbitrage (internal) or other analysis tools. The two modes (topic shortcuts and explicit tickers) are explicitly named and described.

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 clear context for when to use each mode, including a list of topic shortcuts and explicit ticker overrides. It warns that most pre-mapped topics return compatibility warnings ('pre-mapped ≠ tradeable'), guiding agents to verify output. However, it does not explicitly suggest alternative tools when spreads are not meaningful, leaving some ambiguity.

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, non-destructive. Description adds scoping detail (by identifier). 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?

Three sentences, front-loaded with main action. No fluff; 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?

For a single-parameter tool with good annotations and clear description, it fully informs the agent about behavior and return expectations.

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%. Description adds meaning: explains 'key' and behavior when omitted (list all keys).

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 tool retrieves a value saved via 'remember' or lists all keys if omitted. It distinguishes from sibling tools like 'remember' 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?

Explicitly says to use for looking up previously stored context without re-deriving. Implies alternatives (remember, forget) but no explicit when-not-to-use.

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 discloses the mark_read behavior (flagging events as read) and mentions the return fields (source, citation_uri, raw payload). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds functional context beyond those annotations without 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 concise with no wasted words; every sentence serves a purpose—stating the action, return values, filtering options, a behavioral toggle, and practical usage tips (polling, alternative URL). Information is front-loaded effectively.

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 no output schema, but the description covers return fields, all parameters with usage guidance, behavioral option (mark_read), and external access. Given the tool's read-only, non-destructive nature with five optional parameters, the description is fully adequate.

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 description adds meaningful context: gives example for type (sec_8k), clarifies since format (ISO timestamp), explains mark_read effect, and implies default limit. This adds value beyond the schema definitions.

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 verb 'Pull' and the resource 'fired events from your subscription feed', specifying the returned alerts with source, citation_uri, and raw payload. It distinguishes from related sibling tools like list_subscriptions by focusing on events from the persisted feed.

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 that polling works fine and provides an alternative URL for scripts/dashboards, offering usage context. However, it lacks explicit comparisons to sibling tools or when-not-to-use guidance, which would elevate the score.

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 and idempotent hints, but the description adds crucial behavioral context: fan-out to three sources, fallback from GDELT to GNews, USPTO soft-fail, and return format (changes grouped by source, total_changes, citation URIs). 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 a single paragraph, front-loaded with query examples, then succinctly covers all key behaviors. Every sentence adds necessary detail without redundancy.

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 complexity (multiple sources, fallback, edge cases), the description is remarkably complete: it covers sources, fallback, date formats, return structure, and sibling alternative. No output schema needed as description covers return format.

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 100% schema coverage, the description still adds value: examples for `since` (ISO and relative), recommendation for '30d' or '1m', explains `value` accepts ticker or CIK, and confirms `type` only supports 'company'.

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 fetches a change feed for a company, covering SEC filings, news, and patents, with specific query examples. It distinguishes from sibling `entity_profile` by noting the static vs. change feed difference.

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 guidance to use `entity_profile` for static profiles, and details the scope and sources. However, it lacks explicit when-not-to-use scenarios beyond that.

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 idempotentHint=true and not destructive. The description adds behavioral context: scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. 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 three sentences, front-loading the main purpose, and includes no extraneous information. 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 key-value store with two parameters and no output schema, the description covers purpose, usage, behavior, and parameters fully. It also mentions related tools (recall, forget) for 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 already provides good descriptions for key and value (100% coverage). The description adds naming conventions (e.g., 'subject_property', 'target_ticker') and clarifies the value is any text, enhancing 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 action ('Save data'), the resource ('data the agent will need to reuse later'), and its scope ('across this conversation or across sessions'). It distinguishes from sibling tools by naming recall and forget as complementary 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 tells when to use ('when you discover something worth carrying forward') and provides context on persistence (authenticated vs anonymous sessions). It doesn't explicitly state when not to use, but the context is clear.

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 reveals internal cascading behavior ('Each call cascades through several lookup endpoints internally'), graceful degradation ('LEI/FIGI enrichment degrades gracefully'), and output details like the `unresolved` field and source labeling. This goes beyond the annotations by describing partial resolution and fallback behavior.

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 runs several sentences with technical details (LEI from GLEIF, FIGI from OpenFIGI, pipeworx citations). While well-structured with 'SUPPORTED TYPES,' it could be trimmed to front-load the core purpose more tightly.

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 accounts for return values by listing resolved identifiers (CIK, ticker, LEI, FIGI, RxCUI) and mentioning unresolved handling. It also explains the `pipeworx://rxnorm/...` citation, though the exact output structure is not specified.

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 described in the schema, and the description adds concrete examples for `value` (e.g., 'AAPL', '0000320193') and explains type-specific outputs. It also clarifies that company accepts ticker, CIK, or name, and drug accepts brand/generic, enriching the enum semantics.

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 queries ('What's the ticker for…') and states the action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes itself from siblings by focusing on ID resolution, supported types (company/drug), and the note that it replaces 2-3 manual 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?

It explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' which establishes the primary use case. It also includes example queries like 'who owns X' and lists supported input types, but does not mention alternative tools or explicit when-not conditions.

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, openWorld, idempotent, not destructive. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density. This goes beyond the annotations without contradicting 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?

Two sentences with zero wasted words. The first sentence states purpose and action, the second provides context and output details. Well-structured 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?

Although there is no output schema, the description specifies the return format (ranked list with score, confidence, signal density). Parameter count is 4, all documented in schema. The description covers the essential behavioral aspects for an agent to use 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 detailed parameter descriptions. The tool description adds no new semantics beyond summarizing the overall behavior. Baseline for high coverage is 3, and the description does not improve it.

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, ranks them, and identifies most/least recognized. It uses specific verbs and nouns (compare, AI visibility, entities) and distinguishes itself from sibling tools like ai_visibility_check (single probe) and compare_entities (generic 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?

The description provides explicit use cases: competitive AI-marketing audits and gives an example. It implies when to use (multi-entity comparison) but does not explicitly state when not to use or list alternatives beyond mentioning ai_visibility_check. Still, context is clear.

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 adds behavioral context beyond annotations: explains partial failures, graceful degradation, and that bundlephobia's first measurement can take 5-30 seconds. Annotations already indicate readOnly, idempotent, and non-destructive, and the description aligns with these.

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 and front-loaded with a clear summary, but it is somewhat lengthy. Every sentence adds value, but minor trimming could improve conciseness 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 fully explains return values (summary block with specific fields, per-advisory detail, links, alternative versions) and handles edge cases like partial failures and sources_failed. Complete for a composite tool with multiple data sources.

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 descriptive parameter descriptions. The tool description does not add additional meaning beyond what the schema already provides for package and version. 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 clearly states the tool is a composite check for npm packages using deps.dev and bundlephobia, with a specific verb-resource combination. It distinguishes from sibling tools like validate_claim or deep_research by focusing on dependency scanning.

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 when to use it (questions about safety/popularity/size) and when not to use it (other ecosystems like PyPI, Maven, Cargo, Go, which fall under different tools). It also provides context on partial failures and timing.

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), the description reveals technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and the fact that each passage includes character offsets.

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 focused, front-loaded paragraph that efficiently conveys purpose, usage, and technical details without redundant or irrelevant sentences.

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 complexity and lack of output schema, the description adequately covers what is returned (passages with offsets and scores), how it works (embedding model, windowing), and constraints (200K cap, truncation flag). 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%, and the description adds value by providing query examples and clarifying the text limit. However, it does not fully explain the impact of the limit parameter beyond what the schema states, keeping this from a perfect score.

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 semantic search inside a fetched record, using specific verbs and resources. It distinguishes itself from siblings like ask_pipeworx_grounded by explaining that it searches inside already-fetched text, not on external data.

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 when to use: when the record is too big to fit in the prompt. It also provides guidance on pairing with ask_pipeworx_grounded, and implies when not to use (i.e., when the full document can be included directly).

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?

Annotation indicates idempotentHint=true, but description implies each call creates a new subscription (non-idempotent). This contradiction reduces transparency. Otherwise, description discloses many behavioral traits 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?

Comprehensive but slightly verbose. Front-loaded with purpose, uses examples well. Could be trimmed, but acceptable given complexity.

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, but description explains return value (subscription id). Covers all parameters, types, authentication, delivery, and constraints. Complete for the tool's purpose.

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 100% of parameters, but description adds significant detail: type-specific examples, delivery constraints (SMS cap, webhook signing). Exceeds 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?

Description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from siblings 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?

Provides extensive usage guidance: requires Pipeworx OAuth account, explains supported types with examples, delivery channels with constraints (email, SMS with verification, webhook with HMAC). Does not explicitly state when not to use, but context is clear.

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, and destructiveHint=false, fully covering the safety and idempotency profile. The description adds the context of being an onboarding entry point and return structure, but no new behavioral traits beyond what annotations imply.

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 with useful information in a single paragraph, using dashes to list categories. It is front-loaded with purpose and usage. While every sentence is valuable, it could be slightly more concise by separating the listing into a clearer structure.

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 one optional parameter, no required fields, and no output schema, the description covers the tool's purpose, usage context, parameter guidance, and expected return content (category-bucketed examples). It is nearly complete, but lacks explicit description of the return JSON structure, which would be helpful since there is no output schema.

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. The description adds significant meaning by explaining the $topic parameter's purpose (focus on a category) and listing the exact focus areas (finance, pharma, etc.), which goes beyond the schema's minimal description. This helps the agent use the parameter more 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 states it's the onboarding entry point for a newly connected agent, explaining it returns category-bucketed example questions with specific tool+argument shapes. It also explicitly distinguishes from sibling tools like ask_pipeworx and entity_profile, covering what it does and who it's for.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains the optional $topic argument for focusing. However, it does not provide explicit when-not-to-use guidance or alternatives, though the context is clear.

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 adds behavioral context beyond annotations: it clarifies that the row is deactivated (not deleted), so historical events remain, and enforces ownership. This aligns with destructiveHint=false and readOnlyHint=false, with 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 two efficient sentences, front-loaded with the core verb and resource. Every sentence adds necessary detail without redundancy.

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 single parameter, no output schema, and presence of annotations, the description is complete: it covers purpose, ownership, and data effect. 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 coverage is 100% with a description for the 'id' parameter. The description adds value by specifying that the id is returned by 'subscribe', providing origin context not 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 'Cancel a subscription by id.' It uses a specific verb (cancel) and resource (subscription), clearly distinguishing it from sibling tools 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?

The description explains when to use (to cancel a subscription) and includes ownership enforcement, implying when not to use (cannot cancel others' subscriptions). It does not explicitly list alternatives, but the context is clear.

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, openWorld, idempotent, non-destructive), the description discloses detailed behavioral traits: return verdict types, the meaning of could_not_verify (check did not happen, includes verification_error, not evidence), unsupported (no source), and the tolerance_pct override with default cap. This is rich context not available in 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 lengthy but every sentence contributes: query examples, pipeline routing, verdict semantics, error handling, and performance benefits. It is front-loaded with the trigger phrases and clear opening, making it easy to scan despite the length.

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 extremely complete for a complex tool with no output schema. It covers return values (verdict, actual value, citation, reasoning), error semantics (could_not_verify vs unsupported), pipeline routing, and performance characteristics. The annotation coverage (readOnly, openWorld, idempotent) plus this rich description leaves minimal ambiguity.

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 value by providing example claims and explaining tolerance_pct usage (set 1–2 for hallucination detection, default implied by wording capped at 5), which goes beyond the schema's syntax-level description.

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 performs natural-language claim verification against authoritative sources, with specific verb 'verify' and resource 'claim'. It distinguishes itself from siblings by mentioning the SEC EDGAR/XBRL structured path for company financials and a grounded pipeline for 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?

Provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes company-financial claims from other factual claims, explaining the routing logic. It doesn't name specific alternatives or say when NOT to use it, but the 'use whenever' is a strong contextual signal.

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