Usda Fdc

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by explaining the scoring mechanism, API key dependency, and direct payment model for Anthropic. No contradictions.

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

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

The description is a single paragraph that begins with the core purpose and then adds necessary details. It is dense but not verbose, covering all essential aspects efficiently.

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 is provided, but the description explains the return structure (per-model score, confidence, signals, raw_response + combined view). This is sufficient for a tool with 4 parameters and clear semantics.

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

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

Schema description coverage is 100%, so the schema itself documents parameters. The description adds extra context (e.g., default model is free, API key format) that aids 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 uses a specific verb ('probe') and resource ('LLMs') and states the outcome ('score visibility 0-100 per model'). It clearly distinguishes from sibling tools by its focus on multi-model visibility scoring.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains API key requirement for Anthropic. Lacks explicit when-not-to-use guidance, but the use cases are 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 mark it read-only, idempotent, and open-world, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it routes to internal sources, fills arguments automatically, returns structured output with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. There is no contradiction with the annotations.

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

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

The description is long but every sentence earns its place: usage priority, scope, examples, alternatives, and escalation path are all packed in without redundancy. The most important directive ('PREFER OVER WEB SEARCH') is front-loaded, and the examples concretely illustrate the expected input style.

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 central routing tool with no output schema, the description is complete: it states what the tool does, when to use it, how it behaves, what it returns, and how it compares to siblings. An agent has enough context to select and invoke ask_pipeworx correctly without hunting for more information.

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

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

Schema description coverage is 100%, so the schema already documents the single meaningful parameter and its aliases. The description reinforces that the input is a natural-language question but adds no additional parameter-level semantics beyond what the schema provides. This matches the baseline for high schema coverage.

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

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

The description names a specific verb and resource: it routes questions to one of 5,743 tools across 1,500 sources and returns structured answers with citation URIs. It sharply distinguishes itself from ask_pipeworx_grounded and deep_research by naming them as alternatives. This is far beyond a vague or tautological statement.

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

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

The description gives explicit when-to-use guidance: prefer over web search, use for factual/real-world questions, and start here as the default entry point. It also explains when to step up to ask_pipeworx_grounded or deep_research, providing concrete conditions and examples. No ambiguity remains about when this tool is appropriate.

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 convey read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: live candidate routing is possible, none is active right now, it is a fully working router with no fallback, and results are compared against the stable router. This goes beyond what annotations alone provide.

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

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

The description is well-structured and front-loaded with the essential identity and purpose. It is a bit dense and contains a few phrases that reinforce the same point, but every sentence contributes useful context about current behavior and experimental nature.

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 that this is a single-parameter router with rich annotations, the description provides enough context about its relationship to ask_pipeworx, its current active status, and how it should be used. The lack of an output schema is partially mitigated by the statement that it shares the same response shape as ask_pipeworx.

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

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

The schema already documents the required question parameter and all its aliases with full 100% coverage. The description only says 'same arguments' as ask_pipeworx, adding no extra semantic meaning beyond the schema.

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

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

The description clearly identifies the tool as a beta counterpart to ask_pipeworx and specifies its role as a universal router with the same 5,743 tools, arguments, and response shape. It distinguishes itself from the stable sibling by calling out its experimental status and current behavior.

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 this tool like ask_pipeworx when the newest routing behavior is desired, and notes that with no candidate currently active it matches ask_pipeworx exactly. It stops short of explicitly stating when not to use it, but the beta-vs-stable contrast 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, the description discloses the exact success return shape, the refusal shape, the specific refusal_reason enum values, the constraint that answers are extracted only from tool results, and the extra LLM call cost. This is substantial behavioral context that is not present in the annotations or schema.

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 four dense sentences with no filler. It front-loads the core purpose and differentiator, then efficiently covers routing behavior, return/refusal formats, use cases, and cost-based preference. 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?

With no output schema present, the description compensates by specifying both success and refusal response structures, including refusal_reason values. Given the tool's complex routing behavior and simple parameter schema, the description provides all context an agent needs to select and invoke it correctly.

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

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

Schema coverage is 100%: all six parameters are documented as aliases for a natural-language question. The description adds no parameter-specific detail, but the schema already fully explains what to pass, so the baseline 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 uses a specific verb-resource pairing: it is a 'hallucination-resistant answer mode' that routes through tools and returns grounded answers. It explicitly contrasts with ask_pipeworx by highlighting the grounded extraction and refusal behavior, so an agent can distinguish it from its closest sibling without inspecting schemas.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also gives an exclusion and alternative: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff of one extra LLM call.

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 far beyond annotations by detailing low-confidence resolution short-circuiting, closed market handling, wide spread tradeability warnings, resolution-rule risk (cancellation_rule), parent event extractor, and news fallback mechanisms. Annotations only indicate readOnly, idempotent, and non-destructive; the description adds essential behavioral context.

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 (~1500 words) and dense with examples and edge cases. While well-structured with clear headings and logical flow, it could be more concise. Some details (e.g., specific FRED series codes, resolution-rule examples) are valuable but make the description verbose.

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, the description covers all critical aspects: input formats, classification categories, fan-out patterns, response shapes, resolver confidence handling, parent event extraction, news fallback, safety mechanisms, and cancellation rules. Without an output schema, the description adequately explains return values and edge cases.

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?

Despite 100% schema coverage, the description adds significant value: explains 'depth' default and behavior ('quick' vs 'thorough'), clarifies 'include_raw' default and when to set true, and elaborates on 'market' input flexibility (slug, URL, question text). This provides actionable 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 tool's purpose: researching Polymarket bets by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on research rather than edge detection or arbitrage.

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

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

The description explicitly defines use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides specific examples of fan-outs for different bet types. However, it does not explicitly state when not to use this tool or mention alternative tools, slightly reducing 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: data sources (SEC EDGAR, FAERS), handling of fiscal year differences, metrics pulled, sorting, and return format with citation URIs. 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 a single well-structured paragraph with front-loaded key information. Every sentence adds value, covering usage patterns, data sources, sorting, and efficiency. No redundant phrasing.

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, the description covers essential aspects: usage, input parameters, data sources, sorting, and output hints. The annotations provide additional safety context. No gaps that would hinder correct invocation.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. It explains the 'type' parameter's specific data sources and the 'values' parameter with concrete examples and constraints. This helps the agent understand the expected input.

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 starts with explicit verb phrases like 'Compare X and Y' and 'side-by-side comparison', clearly stating the tool's purpose. It differentiates from sibling tools like entity_profile by explicitly stating preference over 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?

Provides explicit query patterns, specifies the tool should be used for comparing 2-5 companies or drugs, and instructs to prefer it over sequential single-pack lookups. The description gives clear context on when 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 goes far beyond the annotations: it discloses account/plan requirements, parallel routing across 5,743 tools, the findings-packet format, explicit gaps[] instead of invented answers, contradictions[] for standard/thorough, citation fetchability guarantees, semantic excerpting, and expected latency. This is rich behavioral context that annotations alone would not convey.

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

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

The description is long but every sentence carries substantive guidance: auth, routing, mechanics, output contract, edge cases, and latency. It is somewhat dense and run-on, and the account warning is front-loaded before the core purpose, but the information density justifies the length for a tool of this 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?

With no output schema, the description fully covers what the agent receives: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, hop field, gaps[], and contradictions[]. It also covers tool selection boundaries, auth prerequisites, latency expectations, and second-hop behavior, so an agent has everything needed to invoke and interpret this 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?

The schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds meaningful depth semantics beyond the schema: depth:'thorough' is paid, 'standard' adds gap recovery, 'thorough' adds lead-chasing, and both add contradiction scanning. It also clarifies that broad natural-language questions are appropriate, which helps an agent choose values confidently.

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 names a concrete operation ('Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources') and explicitly differentiates it from open-web search and from ask_pipeworx. It also states the tool decomposes questions and returns a findings packet, so an agent understands what this tool uniquely produces.

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

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

It gives explicit routing guidance: use for broad/multi-part questions over structured data, use ask_pipeworx for single lookups, and prefer ask_pipeworx for breaking or colloquial current-news topics. It also specifies account requirements and directs unsigned-in users to ask_pipeworx, leaving no ambiguity about when this tool should be selected.

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

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

Adds value beyond annotations by describing return format (top-N tools with schemas, ready to call) and behavior (no side effects, read-only). 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?

Efficiently front-loaded with purpose, use cases, and call to action. Every sentence adds value with no 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?

Thorough given complexity: explains purpose, when to use, what results contain, and tool relationships. No output schema but return content is described.

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

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

Schema coverage is 100%, so baseline 3. Description mentions query aliases and natural language, but schema already provides examples and descriptions, so no significant added meaning.

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

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

Clearly states the tool finds tools by describing data or task, lists many use cases, and distinguishes from sibling tools that perform specific actions.

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

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 signal readOnly/open world/idempotent/non-destructive behavior, and the description adds rich behavioral detail: it fans out across many sources, soft-fails on expired patent APIs, treats empty FDA sections as expected, and resolves private companies to a resolved:false result with an explicit notes line. This goes well beyond the annotations and prepares the agent for realistic failure modes.

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

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

The description is long but information-dense and front-loaded with trigger examples and the core purpose. It is not a model of concise structure, but every clause carries important operational detail, especially around source-specific behavior and expected empty results.

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 high-complexity, fan-out tool with no output schema, the description is unusually complete. It enumerates the major returned sections, explains source failure semantics, documents fallback behavior, distinguishes private vs public companies, and defines valid input forms. An agent has enough context to select and invoke the tool correctly.

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

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

The schema already covers both parameters with clear descriptions, so the baseline is 3. The description adds value by providing concrete examples (AAPL, 0000320193, Moderna), explaining that type values are interchangeable, and describing how names resolve via SEC EDGAR. This is helpful but not a dramatic expansion 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 states a specific verb and resource: it produces a 'full cross-source profile of a US public company in ONE parallel call.' It also gives concrete trigger phrases and contrasts itself with single-pack SEC/XBRL/news lookups, so an agent can distinguish it from similar research/entity 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?

It clearly says to use this tool 'when the user asks for a holistic view' and to ALWAYS PREFER it over chaining single-pack lookups. It does not name specific sibling tools or provide explicit 'do not use when' exclusions, but the intended usage context is strongly and directly conveyed.

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 destructiveHint=true so deletion is expected. The description adds context on why to delete (stale context, task done, sensitive data) but does not contradict annotations. No additional behavioral traits are disclosed 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?

Two sentences, front-loaded with the primary action. Every sentence adds value, no 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?

For a simple deletion tool with one parameter, no output schema, and sufficient annotations, the description provides complete context: purpose, usage scenarios, and relation to sibling tools.

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 for the 'key' parameter. The tool description does not add additional meaning beyond the schema, meeting the baseline expectation.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'). This distinguishes it from sibling tools like 'remember' (store) and 'recall' (retrieve).

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 the tool: when context is stale, task is done, or to clear sensitive data. Also instructs to pair with 'remember' and 'recall', guiding the agent on inter-tool 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?

Annotations already declare readOnly, idempotent, non-destructive. Description adds value by explaining the process (fetch, extract, emit format) and the output nature, providing helpful 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?

Three sentences, front-loaded with purpose, then process, then use cases. Every sentence earns its place with no fluff.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers all necessary context: purpose, process, output format, and use cases. Annotations handle behavioral traits.

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 both parameters (url, max_links) with descriptions. The tool description does not add additional parameter-specific meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool generates a llms.txt file for any URL, extracting title/description/key links and emitting standard markdown format. It distinguishes from sibling tools by specifying its unique purpose in AI crawler indexing.

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 use cases are provided: getting a client's site indexed, drafting for own project, auditing competitor. While it doesn't explicitly state when not to use or name alternatives, 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 readOnlyHint and idempotentHint, so the description adds limited value. It mentions 'full food record', implying a complete response, but does not elaborate on return format or pagination.

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 without wasted words. However, it is almost too brief; a bit more context could improve clarity without losing 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 the presence of an output schema and comprehensive annotations, the description provides enough context. It indicates the tool retrieves a single food record by ID, which is sufficient for a straightforward read operation.

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 does not need to add parameter details. The description mentions 'FDC id' which aligns with the required parameter, but adds no new meaning beyond the schema.

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

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

The description clearly states the action (get) and resource (full food record by FDC id). It is succinct and unambiguous, but does not distinguish from sibling tools like 'list_foods' or 'search_foods', which also deal with food 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 is provided on when to use this tool versus alternatives such as 'search_foods' or 'nutrients_for_food'. The description lacks context about prerequisites or preferred 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, covering safety and behavior. The description adds no additional behavioral context, but does not contradict annotations.

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

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

Extremely short, which is concise, but it is a noun phrase rather than a complete sentence. Could be structured better with a verb and clearer object.

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 and existence of output schema, the description is minimally adequate. It does not elaborate on what the reference contains or how to use it, but annotations fill some gaps.

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

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

No parameters exist, so schema coverage is 100%. Baseline score of 4 applies as description does not need to add parameter meaning.

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

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

The name 'list_food_groups' clearly implies listing, and description adds 'USDA food group reference (categories)', which specifies the resource. It is clear but lacks an explicit verb in the description, and does not differentiate from siblings like list_foods.

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 provided on when to use this tool versus alternatives such as list_foods or search_foods. The description gives no context for selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds 'paginated' but no further behavioral details (e.g., rate limits, data freshness). Value added is minimal.

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, front-loaded with the core purpose. No unnecessary words or 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 simplicity (optional parameters, no required fields, output schema present), the description is mostly complete. However, it lacks clarification on sorting parameters and data type filtering options, which are present in the schema but not summarized.

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 60%, with descriptions for 'data_type', 'page_size', and 'page_number' provided in schema. The description does not add any parameter semantics beyond what is already in the schema, 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 tool's action ('browse') and resource ('FDC foods'), with a distinctive feature ('paginated'). It is specific and distinguishes from sibling tools like 'search_foods' and 'get_food'.

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 usage guidance is provided. The description does not indicate when to use this tool versus alternatives such as 'search_foods' for filtered queries or 'get_food' for single item retrieval.

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, non-destructive behavior. The description adds value by specifying the exact return fields and the ability to include inactive subscriptions. No contradictions.

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

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

Two sentences, front-loaded with the core purpose, no redundant words. Efficient and well-structured.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage guidance completely.

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 single parameter 'include_inactive' is fully documented in the schema (100% coverage). The description adds no extra semantic detail beyond noting 'active subscriptions' as default. 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 lists the caller's active subscriptions and enumerates return fields (id, type, params, etc.), distinguishing it from sibling tools like subscribe 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?

Explicitly advises using this tool to review subscriptions before adding more or to find an ID to cancel, providing clear context for when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description's claim of being convenience-oriented aligns. However, it does not add further behavioral details beyond what annotations provide, such as error handling or response format.

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, which is concise but too brief to cover necessary details. It is not verbose, but it sacrifices clarity and completeness for brevity.

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 presence of an output schema the description could be minimal, but it fails to explain that fdc_id is a food code and that nutrient_numbers filters results. The description is incomplete for a tool with two parameters and a specific output.

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 50% schema description coverage (only nutrient_numbers has a description), the tool description adds no parameter explanations. The fdc_id parameter lacks any meaning in both schema and description, which is insufficient for an agent to understand its role without prior knowledge.

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 'nutrient values only for a food' clearly states the tool retrieves nutrient data for a specific food. It distinguishes it from sibling tools like 'get_food' which likely returns full food details. However, it could be more explicit about the scope.

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 no guidance on when to use this tool versus alternatives like 'get_food' or 'search_foods'. It does not specify prerequisites or when not to use it, leaving the agent to infer usage solely from the name.

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 all-false annotations, the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow for later status checks, and the fact it's free and doesn't count against quota. It also explains the team's daily digest cadence. 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 longer than average but information-dense—each sentence contributes (purpose, scope, workflow, limits). It is well-structured and front-loaded with the main action, though slightly verbose compared to simpler tools.

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 covers the key return value (claim_token) and its subsequent use. It also explains the scope, rate limits, and team response cadence, making it sufficient for an agent to invoke correctly and set 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% (baseline 3), but the description adds crucial context: how claim_token is used to read replies, that it can be passed with no other arguments, and the purpose of context fields (pack, tool, vertical). It enriches the schema by describing real-world usage.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling research/discovery tools by focusing on feedback for Pipeworx tools, not on data retrieval or 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?

Explicitly lists when to use: '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 states an exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users elsewhere for other MCP servers, offering alternatives. This is textbook usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destruction. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). This goes beyond 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?

The description is a single paragraph with a clear lead sentence followed by enumerated use cases and supporting details. It is well-structured and avoids redundancy, though it could be slightly more terse.

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 (one optional parameter, no output schema), the description fully covers the return value structure (top tools, top packs, total call volume) and data freshness. No gaps remain for an agent to infer.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds semantic meaning by explaining the trade-off between short and long windows ('what's hot right now' vs 'steady-state demand'), which helps agents choose correctly.

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 explicitly states the tool's verb ('returns') and resource ('top tools, top packs, and total call volume'). It distinguishes its purpose from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on trending data. The three use cases further clarify its role.

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 three concrete scenarios for when to use the tool (discovering hot data sources, confirming canonical tools, checking use-case alignment). It does not explicitly mention when not to use or name alternatives, but the guidance is clear and practical.

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

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

Annotations indicate readOnlyHint, idempotentHint, and no destructive hint. The description reinforces this by explaining it is a computation tool that does not execute trades. It details behavioral traits like partition filter (placeholder fraction check), semantic anchor (Jaccard similarity), and fill check against live CLOB depth, providing full 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?

The description is well-structured with clear sections for each mode and key concepts. It is informative but somewhat verbose, with unnecessary details like the placeholder filter mechanism. Still, it is efficient and front-loaded with the most important information.

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

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

Despite no output schema, the description thoroughly explains the response structure: opportunities[] with fields, partition_check with sum_yes_prices, and fill_check with theoretical vs realizable edge. It also covers edge cases and references a sibling tool for further customization, making it complete for the tool's complexity.

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 covers both parameters with descriptions (100% schema coverage). The description adds significant context beyond the schema: examples of slugs for event, seed questions for topic, and how each mode operates. This elevates from baseline 3 to 4.

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 via monotonicity violations and partition-sum checks. It distinguishes three modes: no-args trending scan, event mode for specific markets, and topic mode for cross-event scanning. This specificity differentiates it from sibling tools like polymarket_edges.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market slug, topic for cross-event scanning. It also includes when-not-to-use instructions, such as not trading when fill check shows realizable_edge_pp ≤ 0, and references sibling tool 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 already declare readOnlyHint, idempotentHint, no destructiveness. The description adds extensive behavioral context: caching strategy (1h KV-level keyed on knobs), detailed edge calculation (e.g., 'edge_pp_net after slippage', Kelly fraction caps), 24h-move warning, and output structure including diagnostics. 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 dense paragraph but front-loads purpose and uses numbered list for segments. Some information could be more scannable (e.g., bullet points for knobs). Given the tool's complexity, it is reasonably concise but slightly overwhelming.

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 (by_segment, fed_candidates, _diagnostics), the meaning of key fields like edge_pp_net and kelly_fraction, and the caching behavior. It covers why Fed bets are excluded and how diagnostics help debug empty segments. No gaps 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% with descriptions, but the description adds narrative meaning beyond individual parameter docs. For example, it groups knobs as 'TRADEABLE-EDGE KNOBS' and explains how min_liquidity/max_spread_pp drop non-realizable edges, and how min_partition_leg_kelly filters per-leg Kelly. This provides holistic understanding.

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 starts with a specific verb 'Scan' and resource 'Polymarket markets', clearly stating it finds opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools like polymarket_arbitrage by detailing its three model families and focus on 'what should I bet on today'.

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 targets 'what should I bet on today' and explains segments, knobs, and caching. However, it lacks explicit when-not-to-use or direct comparisons to alternatives like polymarket_arbitrage. The note about Fed bets being excluded provides some limitation context.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are supported and extended by the description. The description details the response structure (tracked, expired, snapshot_dates) and explains edge cases like gaps in data and the 60-day TTL. 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 comprehensive but slightly verbose. It is well-structured with a lead sentence explaining the core purpose, followed by parameter explanations and response details. It earns its length by providing necessary context, though some redundancy could be trimmed.

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 only two optional parameters and no output schema, yet the description covers the return format (tracked, expired, snapshot_dates), data sources, limits (60-day TTL), and computational details (daily closes, not intraday). It is fully self-contained for an agent to use 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%, so the schema already documents the parameters. The description adds value by explaining the default values (14 days, '1wk' window), the clamping behavior (2-30), and the meaning of the window parameter. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: analyzing edge persistence and decay over time from daily polymarket_edges snapshots. It provides a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from related tools by focusing on temporal behavior rather than current edges.

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

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

The description gives implicit guidance by contrasting a fresh wide edge with a 3-week-old wide edge, indicating when this tool is relevant. It does not explicitly mention when not to use it or suggest alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds detailed behavioral context: walks order books, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, etc. 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-structured with capitalized mode labels and bullet-like return lists. Every sentence adds value, but some redundancy could be trimmed. For a complex tool this is acceptable.

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

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

No output schema exists, but the description fully enumerates return fields for both modes, explains edge cases (thin_legs, forced_directional_risk), and gives usage context. Covers all necessary information for safe tool invocation.

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

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

Schema coverage is 100% with parameter descriptions. Description adds extra meaning: clarifies that exactly one of 'market' or 'event' is required, explains default side behavior for basket mode (auto from partition sum), and distinguishes size_usd interpretation for basket mode as settlement notional.

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 a realizable-vs-theoretical edge check against live CLOB book depth. It specifies two modes (single-market and basket) and distinguishes itself from siblings like polymarket_arbitrage by explicitly recommending usage before acting on arb signals.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns against relying on theoretical overround on thin books and explains the risk of partial basket fills converting arb into directional positions.

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/idempotent annotations, the description discloses critical behavior: the fee schedule is not modeled so spreads are gross not net, unknown legs are never paired, temporal_alignment null has specific meaning, and both compatibility fields can be non-empty even on returned pairs. This is substantial and directly useful context, with no contradiction to annotations.

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

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

The description is front-loaded with purpose and modes, and labeled sections (RESPONSE, SAFETY FIELDS, Codes) make it scannable. It is long, and some points are repeated, such as temporal null meaning and the same-disclosures-appear-in-both-modes note, so it is not maximally concise, but the density is justified by the tool's 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?

With no output schema, the description shoulders the full burden of explaining return fields: top_spreads_pp, compatibility_codes, skipped counters, fee note, and temporal_alignment. It also covers edge cases like unclassified legs and low-confidence pairs, so an agent can invoke the tool and interpret results 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%, so each parameter is already described by the schema. The description adds value by listing the full pre-mapped topic enum, giving concrete examples, and explaining that explicit parameters override the topic-mapped side. This exceeds the baseline 3 without being exhaustive about ticker/slug formats.

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 opening sentence states the exact function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. The two-mode breakdown (topic shortcuts vs explicit ticker/slug) further clarifies scope and distinguishes it from single-venue sibling tools like polymarket_edges.

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

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

The description provides clear mode-selection guidance: use pre-mapped topics for common macro questions, or explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning, setting expectations. It does not explicitly name alternative tools or say when not to use this one, so it misses the top 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 (readOnlyHint=true, destructiveHint=false) are consistent with retrieval. The description adds scoping ('Scoped to your identifier') and behavior when key is omitted ('list all saved keys'), which adds value 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 composed of four efficient sentences, each adding value. The first sentence immediately states the action and variation, followed by usage context, scoping, and pairing with siblings. No redundant 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 retrieval tool with no output schema, the description adequately covers return behavior (value or list of keys), scoping, and integration with siblings. Missing error handling (e.g., key not found) but not critical for basic usage.

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

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

The input schema has 100% coverage with a description for the key parameter. The description adds behavioral semantics: 'omit the key argument to list all keys', which clarifies usage beyond the schema's property 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?

The description specifies the verb 'retrieve' and resource 'value previously saved via remember', and distinguishes from sibling tools (remember, forget). It also provides concrete examples like 'user's target ticker, an address, prior research notes'.

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

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

The description explicitly states when to use: 'to look up context the agent stored earlier… without re-deriving it from scratch'. It also mentions pairing with remember and forget, though it does not explicitly list alternatives or 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 a key behavioral trait: setting mark_read=true will flag events as read, affecting subsequent calls. This adds context beyond the annotations (which include readOnlyHint=true). The description also mentions that the feed is persisted. No contradictions with annotations, though the idempotentHint may be nuanced when mark_read is used.

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 and well-structured: it starts with the core purpose, then details return fields, filtering, side effects, and an alternative access method. Every sentence adds value 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 absence of an output schema, the description explains return fields (source, citation_uri, payload) and filtering options. It also covers polling suitability. A minor gap is the unread_only parameter is not explained, but overall it is complete for typical use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing example filters ('sec_8k') and explaining mark_read behavior. However, it does not mention the unread_only parameter, which is only 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's purpose: pulling fired events from a subscription feed. It specifies the resource ('subscription feed'), the action ('pull fired events'), and the return fields. This is distinct from sibling tools like 'subscribe' or 'list_subscriptions', and it even notes an alternative access method for scripts/dashboards.

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

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

The description implies usage through filtering and mark_read, but it does not explicitly state when to use this tool vs. alternative tools. It mentions polling works fine and provides a REST endpoint as an alternative, but lacks direct comparison to sibling tools like 'recent_changes'.

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 details parallel fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail until reactivated, and the return format (changes grouped by source, total_changes count, citation URIs). All this adds significant context beyond the annotations (readOnly, openWorld, idempotent).

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 query examples. Each sentence adds relevant information; no wasted words. Could be slightly more compact but is well-organized.

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 covers the return format and behavior (sources, grouping, fallbacks). Annotations cover safety/hints. This is complete for a moderately 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 coverage is 100%, but the description adds value with examples (e.g., '7d', '30d', '1y'), notes that type only supports 'company', and specifies typical monitoring window ('30d' or '1m'). This goes beyond the schema descriptions.

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

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

The description explicitly states the tool's purpose: providing a change feed for a company across multiple sources (SEC EDGAR, GDELT/GNews, USPTO) in one parallel call. It distinguishes itself from sibling tool entity_profile by contrasting static vs. temporal 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?

The description gives explicit when-to-use guidance with example queries, notes fallback behavior (GDELT→GNews), and tells the user to use entity_profile instead for static profile regardless of time window.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, but do not cover persistence. The description adds behavioral context: memory is scoped by identifier, persistent for authenticated users, and 24-hour TTL for anonymous sessions. This 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 four sentences, front-loaded with primary purpose, and efficiently covers scope, usage, and persistence. No wasted words; 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 two-parameter tool with no output schema, the description covers purpose, usage, storage semantics, and links to related tools (recall, forget). It is fully self-contained and adequate for correct invocation.

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

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

Schema coverage is 100% with descriptions for both key and value. The description reiterates that value stores 'any text' and gives examples for keys, but does not add meaning beyond the schema. 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's purpose: 'Save data the agent will need to reuse later' with specific verb 'save' and resource 'data'. It distinguishes from sibling tools by naming recall and forget, and provides examples of what to store (ticker, address, preference, research subject).

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 'Use when you discover something worth carrying forward' and lists use cases. It also differentiates between authenticated and anonymous sessions, and instructs to pair with recall and forget. No explicit when-not-to-use is given, but the guidance is clear and context-specific.

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 cover readOnly/idempotent/non-destructive, but the description goes far beyond: it discloses the cascading internal lookups, graceful degradation when upstream services are unavailable, explicit output structure (unresolved identifiers, figi_candidates on ambiguity), and source labelling. There is no contradiction with annotations — readOnlyHint is consistent with a pure resolution tool.

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 every sentence adds information — it is front-loaded with the primary instruction and example queries, then systematically covers supported types, edge cases, and fallbacks. Structure mirrors the hierarchy of entity types, making it scannable 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 the tool's complexity (two entity types, multiple identifier sources, ambiguous matches, service degradation, no output schema), the description is exceptionally complete. It explains return value semantics (source-labelled identifiers, explicit `unresolved` list, `figi_candidates`), covers non-equity instruments, and addresses international issuers via ISIN-to-LEI mapping. Nothing material is missing for an agent to call 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?

Although schema coverage is 100%, the description adds substantial value: for `type` it elaborates on the two enum values and their associated identifier systems; for `value` it explains the exact string formats for companies vs drugs, and specifically how to format bond issuer names (exclude trailing security-class words). This goes well beyond the schema's one-liner descriptions.

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

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

The description states a specific action — resolve user-spoken names to canonical/official identifiers — and enumerates the exact identifier types (CIK, ticker, LEI, FIGI, RxCUI) and sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm). It also explicitly contrasts itself with sibling tools by stating 'Use FIRST whenever you have a name but need an ID', which differentiates it from tools that operate on existing IDs (e.g., entity_profile, compare_entities).

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

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

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID'), includes example user phrasings, and provides detailed input-format instructions (e.g., pass the entity name only, not the noun phrase for bonds). It explains graceful degradation and fallback behavior, and notes that it replaces multiple manual lookups — all contextual usage guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that it internally calls 'ai_visibility_check' and returns ranking data, but omits details like rate limits or network dependency. With annotations covering safety, the description adds moderate value but not extensive behavioral context.

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 impressively concise: two sentences plus a usage example and output summary. Every sentence serves a purpose, and the key action is front-loaded. 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?

Given the tool has 4 well-documented parameters and no output schema, the description adequately covers the tool's function, internal workflow, and output format. It lacks details on ranking algorithm or edge cases, but overall is sufficiently complete for an agent to select and use the 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 adds a small nuance about the 'entities' array (first entry as subject) but does not significantly enhance understanding beyond the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, using specific verbs like 'Compare', 'Probes', 'ranks', and 'surfaces'. It distinguishes from sibling tools like 'ai_visibility_check' by indicating it handles multiple entities and from 'compare_entities' by specifying it focuses on AI recognition.

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 provides a clear use case ('competitive AI-marketing audits') and an example question, but does not explicitly mention when not to use it or alternatives (e.g., using 'ai_visibility_check' for a single entity). The context is strong but 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 provide safe read-only, idempotent hints. Description adds key behaviors: bundlephobia first measurement can take 5-30s, sources_failed will list on timeout, graceful degradation.

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?

Well-structured and informative, but slightly verbose with multiple clauses. Purpose is front-loaded, but some details could be tightened.

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 provided, but description thoroughly explains return format (summary block, per-advisory detail, links, alternative versions). Also covers NPM limitation and partial failures, making it complete.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds context: package accepts scoped packages, version defaults to latest, enhancing 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?

Clearly states it's a composite check for adding an npm package, combining deps.dev and bundlephobia. Distinguishes from siblings by noting NPM ecosystem only in v1 and mentioning deps.dev:version for others.

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 an agent asks about safety, popularity, or size. Also mentions alternatives for other ecosystems and partial failure handling.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that results include FDC id, description, data type, and publication date. It does not mention pagination behavior or rate limits, but the schema covers page_size and page_number. 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 two sentences long, front-loads the action and resource, and includes key filtering options and return fields. Every word adds value with no 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 the tool has 7 parameters and an output schema, the description covers the core search capability, filtering, and return fields. It does not detail sorting or pagination, but the schema provides that. Overall, it is sufficiently complete for an agent to understand the tool.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters with descriptions. The description only restates that filtering by data type and brand owner is supported, adding no new semantic value 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 uses the specific verb 'search' and identifies the resource as 'USDA Food Data Central'. It clearly states the tool searches for food items by name, brand, or ingredient, with filtering capabilities. This distinguishes it from siblings like 'list_foods' and 'get_food'.

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 filtering by data type and brand owner, which implies usage context but does not explicitly state when to use this tool over alternatives like 'list_foods' (which likely retrieves all) or 'get_food' (single item). No when-not or exclusion criteria 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?

Discloses embedding model (BGE-base-en), windowing strategy (500-char overlapping), character cap (200K with truncation flag), and return format (offsets, scores). Annotations already indicate safe, idempotent, read-only behavior; description adds technical depth 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?

Single paragraph that efficiently covers purpose, use cases, usage advice, pairing, and technical details. No redundant sentences; every sentence adds new 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, description fully explains return values (passages with offsets and scores) and limitations (200K char cap, truncation). For a 3-parameter tool, this is highly complete.

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

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

Schema coverage is 100%, but description adds value by providing natural-language query examples and clarifying that limit controls top-N passages (default 5). Slightly above baseline because of the extra illustrative context.

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

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

Clearly states it performs semantic search inside a fetched record, with concrete use cases like SEC 10-K or article. Differentiates from sibling tools by emphasizing its role as a pre-retrieval step paired with ask_pipeworx_grounded.

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 using when the record is too large for the prompt, and describes the output (passages with offsets) that enables verification. Mentions pairing with ask_pipeworx_grounded for grounded answers.

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 (readOnlyHint false, openWorldHint true, idempotentHint true, destructiveHint false), the description adds critical behavioral details: requires OAuth account, delivery channels with specifics (feed always on, optional email/SMS/webhook), SMS cap, webhook HMAC signing, and automatic disabling after 10 webhook failures. This far exceeds the annotation burden.

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 dense paragraph that front-loads the main action and return value, then systematically covers types and delivery. Every sentence adds value, though it is somewhat lengthy. Could benefit from bullet points for readability, but remains efficient and well-organized.

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 3 parameters with nested objects and no output schema. The description explains the return value (new subscription id) and covers types and delivery in depth. However, it does not address error scenarios (e.g., invalid parameters, authentication failures) or what happens if the subscription already exists. Given complexity, this is a minor gap.

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 greatly enriches each parameter. For the 'type' enum, it explains each option's purpose and sub-parameters. For 'params', it gives concrete syntax for all five types. For 'delivery', it details format requirements, verification steps, and webhook HMAC details. This added meaning is substantial.

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 'Create a proactive monitoring subscription to a live-data event stream' and mentions the return value 'Returns the new subscription id.' This distinguishes it from sibling tools like list_subscriptions (listing), unsubscribe (removing), and recent_alerts (pulling existing alerts).

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 extensive context on when to use the tool, including prerequisites (requires Pipeworx OAuth account), supported event types with examples, and delivery channel options. It also includes limitations (e.g., 10 SMS/day). However, it does not explicitly state when not to use this tool versus alternatives like recent_alerts or list_subscriptions, but the context is sufficiently 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, idempotent, non-destructive), the description reveals that it returns example questions with tool+argument shapes, and that it's meant as an initial discovery step. 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 efficiently structured: starts with example queries, states the purpose, lists output categories, and ends with usage guidance. Every sentence adds value 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 no output schema, the description fully explains the return type (category-bucketed questions with tool calls) and the context of the tool (first contact, meta-tool learning). Complete for the tool's role.

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 (one optional parameter 'topic'). The description adds meaning by explaining the default behavior (no args gives full spread) and listing example topic values, enriching the schema's brief 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?

The description clearly states the tool is an onboarding entry point, returning categorized example questions with exact tool calls. It distinguishes itself as the first tool to use when unfamiliar with Pipeworx's capabilities.

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

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

Explicitly instructs to use this tool first when you don't know what Pipeworx can do. Also explains the optional topic parameter for focus, providing clear guidance on when and how to invoke.

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 set destructiveHint=false and idempotentHint=true. Description adds valuable context: row is deactivated (not deleted) and historical events remain queryable via recent_alerts, which complements the annotation safely.

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 with no redundancy. First sentence provides action and constraint, second adds behavioral nuance. Every word contributes 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 tool with one parameter, low complexity, and no output schema, the description fully covers the lifecycle behavior (deactivation) and side effects (history preservation), making it complete.

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

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

Schema covers the single parameter 'id' with 100% description and references subscribe. Tool description does not add further semantic detail beyond the schema, so 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 verb 'Cancel' and resource 'subscription by id'. It distinguishes from siblings like subscribe and list_subscriptions by specifying cancellation and ownership enforcement.

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 ownership enforcement ('only your own subscriptions'), which guides when to use. Lacks explicit alternatives but provides sufficient context for correct invocation.

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 non-destructive. The description adds meaningful behavioral context beyond these: it explains the veredict taxonomy, explicitly warns that could_not_verify means the check did NOT happen and must not be treated as evidence, and distinguishes it from unsupported. It also discloses the routing behavior and the percent-delta math for financial claims. This is rich, safety-relevant disclosure that goes well 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 long but every sentence earns its place: it packs trigger phrases, two routing paths, veredict taxonomy, evidence/citation behavior, two critical meaning nuances (could_not_verify vs unsupported), and a value proposition ('Replaces 4–6 sequential calls') into a dense but readable paragraph. It is front-loaded with the most important usage signal (natural-language triggers) and ends with the efficiency note.

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 no output schema, the description very thoroughly covers return values (verdict + actual value + reasoning), edge cases (could_not_verify, unsupported), and routing behavior. It also explains how the two parameters interact (tolerance_pct's default and override semantics). Given the complexity of this tool, the description is remarkably complete.

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

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

Schema description coverage is 100% (both claim and tolerance_pct are documented in the schema). The description adds extra meaning: it explains that tolerance_pct overrides the tolerance implied by the claim wording, gives concrete guidance for hallucination detection (set 1–2), and notes the default cap of 5. The claim parameter is also enriched by showing the natural-language trigger phrases. This goes above the schema baseline of 3.

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 explicit natural-language triggers and a clear verb: 'natural-language claim verification against authoritative sources.' It specifically states what the tool does—check whether a user's factual claim is true—and distinguishes its two execution paths (SEC EDGAR/XBRL fast path for company-financial claims; grounded pipeline for everything else). This clearly differentiates it from sibling tools like compare_entities, resolve_entity, 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?

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing behavior for company-financial versus any other factual claim, and states what it replaces ('4–6 sequential calls'). It does not explicitly name alternative tools, but the scope of when to use this tool versus doing multi-step lookups is clearly defined.

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