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 indicate readOnly, idempotent, and non-destructive behavior. The description adds context about internal routing to 5,529 tools, stable pipeworx:// citation URIs, and performance claims (one fast call, every tier). 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 long but information-dense, covering scope, alternatives, examples, and behavior. It is front-loaded with the key preference directive and organized into readable sentences. Slightly verbose, but each sentence earns its place given the tool's broad scope.

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 complex routing tool with no output schema, the description is remarkably complete: it explains what it does, how it responds (structured answers with citations), when to use it, and which alternatives to choose. It also notes the default-entry-point positioning, giving full operational context.

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

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

Schema covers 100% of parameters with clear descriptions, so baseline is 3. The description does not add parameter-level detail beyond the schema, though it does include examples that clarify usage. This meets the minimum but does not elevate the semantics further.

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 question-routing engine that selects from 5,529 tools and returns structured answers with citations, using specific verb+resource language. It explicitly differentiates from siblings ask_pipeworx_grounded and deep_research, making its unique role obvious.

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

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

Provides explicit guidance: prefer over web search, start here for factual questions, and step up to grounded or deep_research only when needed. Names concrete alternatives and gives multiple example queries, fully covering when-to-use and 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: the beta testing lifecycle, candidate routing improvements, the current inactive state, and the reassurance that it is a fully working router with no fallback. No contradictions exist.

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 of four sentences, each serving a distinct purpose: identifying the tool, stating its equivalence, explaining the current beta state, and offering usage guidance. It is somewhat lengthy but not wasteful, and it front-loads the essential 'Beta version' label.

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 lacking an output schema, the description specifies the identical response shape to ask_pipeworx, which is sufficient for an agent familiar with the sibling tool. It also covers the beta testing context, current behavior, and practical usage, making it fully self-contained 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?

The input schema already covers all six parameters with 100% description coverage, including the primary 'question' field and five aliases. The description only mentions 'same arguments' without adding parameter-specific details, so it neither enhances nor detracts from the schema's clarity. A 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 explicitly states it is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It clearly distinguishes itself from the stable sibling by emphasizing the experimental routing edge, making its purpose unambiguous.

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

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

It provides explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that no candidate is currently active so it matches ask_pipeworx exactly. It does not explicitly state when not to use it, but the beta label strongly implies a preference for stable routing in critical 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?

The description discloses key behavioral traits beyond the annotations: it returns a structured object with evidence and refusal reasons, enumerates all refusal_reason values, and highlights the extra LLM call cost. This is significant context not captured by the annotations, providing transparency into failure modes and operational cost.

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

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

The description is concise yet information-dense, front-loading the core purpose, then detailing output shape, refusal reasons, and usage trade-offs. Each sentence earns its place without redundancy, and the structure flows logically from purpose to behavior to usage.

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

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

Given the tool's complexity and lack of an output schema, the description compensates by fully describing the return shape, all possible refusal reasons, and cost implications. It also covers the routing context and alternative tool trade-offs, making it complete for an agent to confidently select and invoke this 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?

The input schema already provides 100% coverage of the single required parameter 'question' and its aliases, so the baseline is 3. The description does not add any additional parameter-level semantics beyond what the schema already states, but it does not need to.

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

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

The description clearly states this is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the grounded extraction process. It distinguishes itself from the sibling 'ask_pipeworx' by noting the same routing but with strict evidence-only answering, making the purpose unmistakable.

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 usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This directly contrasts with the alternative tool, giving clear when-to-use and when-not-to-use direction.

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 discloses many behavioral traits beyond what annotations provide: account requirements, paid plan for 'thorough', output format (findings packet with verbatim evidence + confidence + source + fetched_at + citation), gap[] behavior, contradiction scan, hop field, semantic excerpting, and latency expectations (15-60s, up to ~90s). This provides transparency about side effects, prerequisites, and response characteristics without contradicting the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is dense and front-loaded with the account requirement, then lays out purpose, usage, and behavior in a structured way. However, it is quite long and packed with parentheticals and clauses, which can make parsing harder. Every sentence carries useful information, but a more compact structure with segmentation (e.g., bullet points) could improve readability. Still, for a tool with no output schema, the length is justified.

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 2-param tool with no output schema, the description is remarkably complete. It explains the output structure in detail (findings packet, verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop, citation_uri), clarifies edge cases (when gaps are empty, citations only when resolvable), and covers timing. This fully compensates for the missing output schema and makes the tool's behavior and limitations unambiguous.

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

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

Schema coverage is 100%, and the description adds significant semantic depth beyond the schema's plain descriptions. It explains the concrete meaning of each depth level: 'quick=3 (single hop), standard=5 (default; adds a gap-recovery hop...), thorough=8 (paid; adds a full iterative hop...).' It also clarifies that the 'question' can be broad and that decomposition is intended, which is more than the schema states. This goes well above the baseline for parameters.

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

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

The description clearly identifies the tool as multi-source research over structured data, explicitly distinguishing it from open-web search: 'this is NOT open-web search.' It also differentiates from the sibling ask_pipeworx by noting deep_research is for broad/multi-part questions while ask_pipeworx is for single lookups. This gives a specific verb (research), resource (1455 structured sources), and clear 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?

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx,' 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx,' and 'If you are not signed in, use ask_pipeworx instead.' It also explains depth options and the trade-offs, so agents can select this tool vs alternatives with clarity.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond these: it explains the tool fan-outs across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), notes that USPTO PatentsView API will sunset May 2025 and 'soft-fails until reactivated', and describes news fallback (GDELT→GNews). This goes well beyond what annotations provide.

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

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

The description is a single paragraph that front-loads common use cases and then packs detailed behavioral information. It is efficient but could benefit from slight restructuring (e.g., bullet points for the returned items) to improve readability. Still, it avoids unnecessary verbosity.

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 enumerates what is returned: cik, company_name, recent_filings (with URIs), fundamentals (specific fields from 10-K), patents (with caveat), news (with fallback), and LEI. It also explains data sources and limitations, making the description self-sufficient.

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 by providing examples ('AAPL', '0000320193'), clarifying that names are not supported (directing to resolve_entity), and explaining that the type parameter only supports 'company' currently. This supplements the schema without redundancy.

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 concrete example queries like 'Tell me about X' and explicitly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call'. It clearly distinguishes from siblings such as resolve_entity (for name resolution) and deep_research (broader scope). The verb 'profile' combined with the resource 'US public company' leaves no ambiguity.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states when not to use: 'names not supported (use resolve_entity first)'. This provides clear when-to and when-not-to usage, including an alternative tool.

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

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

Annotations already indicate 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds significant behavioral context: compatibility_warning conditions, temporal_alignment details, skipped cross-type/subtype counters, and explicit caution about tradeability. No contradiction with annotations.

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

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

The description is dense but well-structured with clear sections (modes, response, safety fields). Every sentence adds value given tool complexity, though it is on the longer side. Could be slightly condensed but remains 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?

Given the tool's complexity, lack of output schema, and need to explain safety mechanisms, the description covers all essential aspects: input modes, response structure, compatibility warnings, and temporal alignment. It preemptively addresses common 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?

Schema coverage is 100% with descriptions. The description adds clarifying context beyond schema: lists all topic shortcuts, explains override mechanism, and provides examples for explicit tickers. This helps the agent understand parameter relationships and constraints.

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

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

The description clearly states that the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, covering two modes and key output fields. It distinguishes itself from siblings like polymarket_arbitrage by focusing on the spread across the two specific venues.

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 advises when to use (equivalent bet shapes, real signal) and when not (compatibility warnings, temporal misalignment), and provides alternative modes (topic shortcuts vs explicit tickers). It warns that real spreads are rare despite the shortcut list.

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?

Beyond the readOnly/idempotent annotations, the description discloses internal cascade through multiple endpoints, source labelling, explicit handling of unresolved identifiers, and graceful degradation when GLEIF/OpenFIGI are unavailable. This significantly exceeds annotation coverage and helps the agent anticipate behavior.

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

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

The description is lengthy but well-structured: it starts with example phrasings, states the core purpose, and then breaks down supported types with parenthetical details. Every sentence carries substantive information; there is minimal fluff. It is front-loaded with the primary use case, though the density could be trimmed slightly.

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 complex tool with two entity types, multiple sources, and no output schema, the description is remarkably complete. It covers input formats, expected outputs, source attribution, unresolved handling, and failure modes. This fully compensates for the absence of an output schema and complex nested behavior.

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 explaining per-type accepted inputs (ticker/CIK/name, brand/generic) and what the resolution returns, which goes beyond the schema's terse descriptions. It enriches understanding of how the value parameter behaves and what to expect.

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

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

The description opens with concrete user phrasings and clearly states the tool resolves names to canonical identifiers. It distinguishes itself from siblings by narrowing scope to ID lookup ('Use FIRST whenever you have a name but need an ID'). The verb 'resolve' and resource 'name to identifiers' is specific and actionable.

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 an explicit trigger: 'Use FIRST whenever you have a name but need an ID' and gives examples of when this applies. It also explains the tool replaces manual lookups, but it does not name alternative sibling tools or explicitly state when not to use it. Still, the guidance is clear enough for correct 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 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.