Materials

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by disclosing the default model (Workers AI Llama-3.3-70b), key requirement for Anthropic, and return structure (per-model {score, confidence, signals, raw_response}). 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?

Two sentences with clear front-loading: action, default behavior, optional key, response shape. 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?

The tool has 4 parameters (100% described), no output schema, but the description summarizes return structure (per-model + combined view). Though it lacks details on 'raw_response', annotations provide safety profile. Completeness is adequate for selection and 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%, baseline 3. The description adds meaning beyond schema: clarifies default model for 'models', explains when '_apiKey' is needed, and gives examples for 'entity' and disambiguation for 'context'. This extra context justifies a higher score.

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

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

The description uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility'), distinguishing it from siblings like 'deep_research' or 'compare_entities'. It clearly identifies the tool's role in AI-marketing audits and brand checks.

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

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

The description explicitly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not provide explicit when-not-to-use or alternative tools. However, the context of sibling tools implies alternatives, and the guidance is clear enough for appropriate 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 mark the tool as read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds useful behavioral context: the tool internally routes, fills arguments, and returns a structured answer with stable citation URIs. It does not disclose failure modes or rate limits, but the annotation coverage reduces that 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 front-loaded with the most important directive, 'PREFER OVER WEB SEARCH', then gives a domain list, trigger phrases, examples, and routing guidance. It is somewhat verbose and slightly repetitive in the final paragraphs, but every major section contributes useful decision-making 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?

For a tool with no output schema, the description does a strong job of setting expectations: it returns structured answers with stable pipeworx:// citations. It also covers the breadth of supported question types, gives explicit routing to alternatives, and includes examples, so an agent has enough context to decide when and how to invoke it.

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

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

The input schema has 100% description coverage: all six parameters are documented as aliases for the single 'question' parameter. The description adds no parameter-specific meaning beyond what the schema already provides, which matches the baseline of 3 for well-covered schemas. Its examples illustrate natural-language phrasing but do not add new parameter semantics.

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

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

The description clearly states what the tool does: it routes natural-language questions to the right one of 5,798 tools across 1,517 verified sources and returns structured answers with pipeworx:// citation URIs. It also distinguishes it from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, making the tool's role as the default entry point unambiguous.

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

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

The description explicitly says to prefer this tool over web search and to start here for most questions, and it gives concrete trigger phrases and examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It also tells when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant verbatim answers and deep_research for broad/multi-part questions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the beta nature, live candidate routing improvements, the current absence of an active candidate, the comparison process against the stable router, and the fact that it is a full working router with no fallback. This is rich, honest 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 front-loaded with the core beta router concept and uses compact parentheticals effectively. Some redundancy exists between 'identical universal router', 'currently matches ask_pipeworx exactly', and 'full working router', but the overall length is justified for a beta tool.

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

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

The description fully covers what the tool is, its current operational status, how to use it relative to the stable version, and what happens to its results. The absence of an output schema is mitigated by the statement that the response shape is identical to ask_pipeworx.

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

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

Schema coverage is 100%, with all parameters documented as aliases for question, so the description does not need to explain them. It mentions 'same arguments' as ask_pipeworx but adds no parameter-level meaning beyond what the schema already provides.

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

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

The description identifies the tool as the beta version of ask_pipeworx and a universal router with the same tools, arguments, and response shape, which is specific enough. It distinguishes it from the stable ask_pipeworx by the experimental routing edge, though it does not explicitly contrast it 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?

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and states that results are compared against the stable router. This is clear context, though it does not explicitly state when NOT to use it or mention the grounded sibling variant.

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

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

The description goes well beyond the annotations by disclosing the return shape, evidence verbatim quotes, confidence, source, and refusal reasons. It transparently reveals refusal behavior when data does not directly answer, which is critical for high-stakes use.

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

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

Long but information-dense; every sentence earns its place by covering purpose, routing, return format, refusal conditions, use cases, and cost tradeoff. The key differentiator is front-loaded in the first phrase.

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 compensates by specifying the exact return object and refusal variants. It also covers the selection criteria, behavior, and cost, making the tool self-sufficient for an agent to invoke correctly.

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

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

The input schema already covers 100% of parameters, all aliases for the single required question parameter. The description adds no parameter-specific details, but none are needed given full schema coverage.

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

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

The description clearly identifies the tool as a hallucination-resistant grounded answer mode for high-stakes reads. It distinguishes itself from ask_pipeworx by specifying that it extracts answers only from tool results and returns evidence/refusals.

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

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

Explicitly states when to use this tool: when answers will be quoted, cited, or acted on, and when facts must not be invented. It also provides a direct alternative routing rule: prefer ask_pipeworx for casual lookups due to the extra LLM call cost.

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, detailing market resolution, fan-out logic, response shapes, safety mechanisms (low-confidence short-circuit, closed markets), tradeability warnings, and resolution-rule risk. It also warns agents to inspect match confidence before trusting analysis.

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

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

The description is very long and includes many sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.), which is informative but could be more concise. It front-loads the main purpose, but the length may be excessive for an AI agent.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all relevant aspects: resolution confidence, parent events, news fallback, safety, closed markets, wide spreads, and cancellation rules. It leaves no gaps.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the 'market' parameter accepts slug, URL, or question text, and describes the effect of 'depth' and 'include_raw' defaults. This provides context 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 researches Polymarket bets using Pipeworx data, with specific verb and resource. It distinguishes from sibling tools like ask_pipeworx and polymarket_edges by providing use-case examples such as 'should I bet on X' and explaining the output structure.

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 examples and classifiers, but does not provide when-not-to-use or alternatives. The examples are comprehensive, but a brief exclusion note would improve 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), fiscal year handling, result sorting, and citation URI inclusion. This enriches the agent's understanding of side effects and output characteristics without contradicting annotations.

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

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

The description is a single paragraph but front-loaded with example queries, which aids quick comprehension. Every sentence adds value: usage guidance, data sources, sorting behavior, and efficiency claim. While it could be slightly more structured (e.g., bullet points), it remains concise given the amount of useful detail.

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 explains what the output contains (paired data + pipeworx:// citation URIs, sorted by primary metric) and how data is sourced and handled (fiscal year corrections). For a tool with only two non-nested parameters, this provides complete context for an agent to understand both input and output 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% with descriptions for both parameters. The description adds semantic value by explaining what each type retrieves (e.g., 'type="company" pulls LATEST 10-K revenue + net income + cash + long-term debt') and gives concrete examples for values (tickers/CIKs for company, drug names). This goes beyond the schema's basic type and range 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 the tool performs side-by-side comparison of 2-5 companies or drugs. It uses specific verbs like 'compare' and identifies the resource (companies/drugs). It distinguishes from siblings by recommending preference over sequential single-pack lookups, which contrasts with tools like entity_profile.

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

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

The description provides explicit guidance to prefer this tool over sequential single-pack lookups when comparing entities. It lists example queries that trigger the tool. However, it does not explicitly state when not to use it, though the schema constraints (2-5 values) and examples imply single-entity cases are handled by other tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context beyond those: it returns a findings packet with verbatim evidence, confidence, source, fetched_at, and citations; it explicitly reports gaps[] and 'never invented' findings; it describes contradiction detection, semantic excerpting, and expected latency (15–60s, up to ~90s). This goes far beyond the annotation hints.

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

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

The description is dense and contains a lot of valuable information, but it is structured as one long paragraph with many phrases crammed together (e.g., 'ACCOUNT REQUIRED...' plus depth variants and timing). Most sentences earn their place, but formatting with separators or bullet-like structure would improve scanability. It is not wasteful, just packed.

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 (2 params, no output schema), the description is remarkably complete: it covers auth requirements, fallback behavior, data source scope, parallelism, output contents, gap handling, contradiction detection, citation semantics, excerpting behavior, and latency expectations. An agent has nearly everything needed to invoke it correctly and interpret its results.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds meaningful detail beyond the schema, particularly for the depth parameter: it explains quick=3 (single hop), standard=3 (gap-recovery hop + contradictions scan), and thorough=6 (paid, full iterative hop), plus timing implications. This enriches agent understanding of trade-offs.

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

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

The description states a specific verb and resource: grounded multi-source research across 1,517 structured data sources in one call. It explicitly differentiates from siblings by noting 'this is NOT open-web search' and directing single lookups to ask_pipeworx, so an agent can select it correctly.

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 conditions: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead'. It also names an alternative for unsigned-in users ('use ask_pipeworx instead'), making routing decisions explicit rather than implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable details: returns top-N tools with names, descriptions, and full schemas, and that results are ready to call without a second lookup. This informs the agent about the tool's behavior 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 well-structured with the purpose stated upfront, followed by usage examples and return details. It is slightly verbose due to listing many domain examples, but each sentence adds value. It remains efficient and easy to parse.

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 discovery tool, the description fully covers its purpose, input (natural language query), output (top-N tools with full schemas), and usage context (call first). No output schema exists, but the description clearly explains what the agent receives. The information is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds value by providing concrete usage examples (e.g., 'look up FDA drug approvals') and clarifying that the query accepts natural language, enhancing the semantic 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 begins with a clear verb 'Find tools by describing the data or task', explicitly stating what the tool does. It distinguishes itself from sibling tools by positioning it as a discovery/browsing tool, not a task-specific tool like 'bet_research' or 'deep_research'.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear context for when to use. It also lists example tasks (SEC filings, FDA drugs, etc.) to illustrate applicability, though it does not explicitly state 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 signal a safe read-only, idempotent operation. The description adds rich behavioral context beyond that: it fans out across multiple named sources, reports sources_used/sources_failed, clarifies that an empty section means genuine 'no data' rather than a bug, explains resolved_from/resolved_to behavior, and describes the private-company fallback with resolved:false and a notes line. This fully discloses the tool's execution characteristics without contradicting 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 contributes: it front-loads example queries and the central directive, then systematically covers sources, return fields, input shapes, and edge cases. While it could be tightened, the density of necessary information justifies the length — this is not padded prose.

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 to fall back on, the description fully carries the burden of explaining return values. It enumerates the returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents, contracts, fda_products, hiring, news, LEI), status flags (sources_used/sources_failed), and edge cases (private companies, small-molecule drugs with no FDA biologics). Nothing essential is missing for an agent to call this correctly.

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

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

The schema already covers both parameters fully (100% coverage), including that type accepts company/ticker interchangeably and value can be a ticker, CIK, or company name. The description adds extra nuance beyond the schema: zero-padded CIK format, resolution via SEC EDGAR's company-name match, and the private-company resolved:false behavior. This genuinely enhances the agent's understanding of valid inputs.

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 example queries and immediately states the tool's core function: 'full cross-source profile of a US public company in ONE parallel call.' This clearly distinguishes it from chained single-source lookups and sibling tools like resolve_entity or deep_research, so an agent can select it correctly without inspecting the schema.

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

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

The description provides an explicit routing rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies that a private company returns resolved:false instead of failing, which tells the agent what to expect. It doesn't name specific sibling tools or list explicit 'when not to use' conditions, but the holistic-view trigger is strong 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 destructiveHint=true and idempotentHint=true, so the description's disclosure adds limited value. The description confirms deletion but does not elaborate on side effects or reversibility.

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 action, and includes usage guidance. No extraneous words.

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

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

For a simple tool with one parameter, full schema coverage, and sufficient annotations, the description covers purpose, usage context, and relationship with siblings. No gaps.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The description adds no new semantic information beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings 'remember' and 'recall'.

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 scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. Lacks explicit when-not-to-use but is sufficient for a simple 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 (readOnly, idempotent, non-destructive) are present, and description adds the fetch/extract/emit process and output format. Does not mention potential limitations like rate limits or URL validation.

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 only: purpose, process, use cases. No redundancy, front-loaded with key information.

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

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

Output format (single text blob) is described despite no output schema. Could mention error handling or URL validation, but sufficient for a simple generation 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 covers both parameters (url, max_links) with descriptions, so description adds no extra meaning. Baseline 3 is appropriate for 100% schema coverage.

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

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

Clearly states verb 'Generate', resource 'llms.txt file', scope 'for any URL', and distinguishes from sibling tools (none other produce llms.txt). Also lists specific use cases.

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

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

Provides explicit use cases (client indexing, own project, competitor audit) but lacks when-not-to-use or alternative tools. Context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return fields and scope (caller's subscriptions) but doesn't contradict. With annotations, the added behavioral context is moderate.

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 purpose, every sentence adds value. No waste.

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 fully covers purpose, usage, and return fields.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add information about the include_inactive parameter beyond what schema already provides.

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

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

Clear verb and resource: 'List the caller's active subscriptions.' Specifies return fields. Does not explicitly differentiate from siblings but is unambiguous.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides practical context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it returns structure IDs, formulas, elements, site count, and a link, and notes the data is computed with millions of entries. 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 well-structured paragraph that front-loads the purpose, gives usage guidance, lists filtering options, and disambiguates from siblings. Every sentence is meaningful 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?

Given no output schema, the description explains return fields (id, formula, elements, site count, link) and mentions scale. The input schema is fully covered with examples and parameter descriptions, leaving no gaps.

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

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

Schema coverage is 100% with descriptions, so baseline is 3. The description adds some nuance (e.g., 'formula' normalized to OPTIMADE reduced form) but does not significantly surpass the schema. A 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 searches computed (DFT) crystal structures across multiple databases, specifying the verb 'Search' and the resource. It distinguishes from sibling tools like materials_stability and the COD pack for experimental structures.

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 recommends when to use this tool over web search for materials queries and provides specific use cases (element sets, exact formula). It also guides users away to sibling tools for experimental structures or stability data.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by detailing the computed nature and listing return fields (composition, formation energy, hull stability, band gap, etc.), which provides behavioral context beyond the annotations. 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 concise and well-structured: it starts with the tool's main purpose, then gives usage guidance, parameter examples, and return schema. Every sentence adds value, with 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 lack of output schema, the description adequately explains return fields and provides usage examples. It covers the essential aspects for a tool with 4 parameters and no nested objects. Minor omissions like default values or error handling are mitigated by the schema and annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description significantly adds meaning by providing examples (e.g., 'Fe, O' for elements, 'stable_only: true'), explaining parameter format, and clarifying the effect of 'stable_only'. This goes well beyond the schema alone.

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

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

The description clearly states the tool computes thermodynamic stability and formation energy from OQMD (DFT) for a chemical system, using a specific verb ('computed') and resource ('OQMD'). It distinguishes itself from web search with explicit use cases, making the purpose unambiguous.

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

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

The description explicitly recommends this tool over web search for specific queries like 'is <compound> stable' or 'formation energy of <material>', providing clear context for when to use it. However, it does not mention alternative tools within the sibling set, such as 'materials_search', which could be a comparable option.

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 rich behavioral context beyond annotations: explains the claim_token behavior ('Filing without an account returns a claim_token; pass it back later'), rate limits ('Rate-limited to 5 per identifier per day'), and that it is free, not counting against tool-call quota. This supplements the annotations (which are all false) and does not contradict them.

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

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

Although longer than two sentences, each sentence earns its place: purpose, use cases, exclusions, claim_token mechanics, rate limits, and quota. The information is front-loaded with the core purpose and organized logically, making it easy for an agent to parse.

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 covers return values ('returns a claim_token', 'Returns the status and, once resolved, what actually changed'). It also covers account behavior, rate limits, and exclusions, making it complete for a feedback submission tool with 4 parameters.

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, but the description adds extra meaning: for claim_token, it specifies how to use it ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and that it should be used with no other arguments. It also clarifies message length expectations (1-2 sentences typical).

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

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

The description states a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists feedback types (bug, feature, data_gap, praise) and distinguishes from siblings by clarifying it is for feedback about Pipeworx tools only, not for asking questions or getting data like the sibling ask_pipeworx or discover_tools.

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

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

Provides explicit when-to-use scenarios ('Use when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well'). It also gives clear when-not-to-use guidance: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). No contradictions.

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

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

Three sentences with bullet-pointed use cases. Front-loaded with the core purpose. Every sentence serves a purpose; no fluff.

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

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

The description explains what the tool returns (top tools, top packs, total call volume) and data freshness. With no output schema, a bit more detail on the exact structure (e.g., whether counts are included) would be helpful, but it's largely 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?

Only one parameter 'window' with 100% schema coverage. The description adds interpretive guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing the schema's enum values.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It provides three specific use cases (discovering hot data, confirming canonical choice, aligning use case), and the purpose is distinct from siblings like discover_tools.

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

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

The description gives explicit use cases and explains window selection (shorter for hot, longer for steady-state). However, it lacks explicit guidance on when not to use this tool or alternatives among the many sibling tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, confirming safe, non-destructive behavior. The description adds significant behavioral context: the internal checks (monotonicity, partition sum), semantic anchor (Jaccard similarity >=0.30), partition filter (dropping placeholder slugs), response structure, and the fill check that references live CLOB depth. This goes well beyond annotations to inform the agent about what happens during execution.

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

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

The description is long but well-structured with sub-headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and capital emphasis. It front-loads the main purpose and modes. However, some internal details like the Jaccard threshold and placeholder fraction could be condensed without losing clarity, making it slightly less concise than ideal.

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

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

Given the tool's complexity (multiple modes, internal logic, and structured response), the description is remarkably complete. It explains the response fields (opportunities[], partition_check fields), the fill check mechanism, and even references polymarket_fill_risk for custom sizing. Without an output schema, the description fully compensates by describing the return format, so the agent understands what to expect.

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

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

Both parameters (event, topic) have schema descriptions, yielding 100% schema coverage. The description adds substantial meaning: it explains that event can be a slug or full URL, topic is a seed question, and provides examples for both. It also details mode-specific behavior, such as how topic searches related events and flattens markets, which is not captured in the schema alone.

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

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

The description clearly states the tool's purpose: to find arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, and the verb 'Find' combined with the resource 'arbitrage opportunities' makes the purpose unambiguous. This differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description gives explicit guidance on when to use each mode: no args for a trending scan, event for a specific market (recommended), and topic for cross-event scanning. It explains why cross-event mode is useful (catches patterns missed by single-event) and directs users to polymarket_fill_risk for custom sizing, providing an alternative. This makes selection and invocation 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 declare readOnlyHint true, and the description adds extensive behavioral details: model families, edge net of slippage, Kelly fractions, 24h-move warning, diagnostics. No contradiction.

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

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

The description is lengthy but well-structured with sections and bullet points. It front-loads the purpose but could be slightly more concise without losing value.

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

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

Despite no output schema, the description details return structure (by_segment, fed_candidates, diagnostics) and caching behavior. It is fully informative given 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?

Schema coverage is 100%, and the description adds meaningful context for each parameter (e.g., min_partition_leg_kelly explanation, slippage_pp defaults).

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and specifies three segments. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 mentions tradeable-edge knobs. However, it lacks explicit guidance on when not to use this tool versus alternatives like polymarket_arbitrage.

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 beyond annotations by detailing data source limitations (60-day TTL, snapshot start), computation details (daily closes, not intraday), and response structure. 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 well-structured but somewhat lengthy. It front-loads purpose and then details response and limits. Could be slightly more concise, but 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 tool with no output schema, the description thoroughly explains response fields (tracked, expired, snapshot_dates) and their meanings, plus data source and limitations. Complete and self-contained.

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

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

Schema coverage is 100% and description adds context: default values, max for days, and purpose of window parameter. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay from daily snapshots. It uses specific verbs ('track', 'answers') and distinguishes itself from the sibling tool 'polymarket_edges' which likely provides raw snapshots.

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 for understanding edge longevity and decay, but lacks explicit when-to-use vs alternatives or exclusions. The context is clear but could be more direct.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: walks the order book ladder, returns fill details and a verdict (clean|degraded|cannot_fill), warns about forced_directional_risk, and explains that partial basket fills convert an arb into an unhedged directional position. 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 somewhat lengthy but well-structured with clear sections for single-market and basket modes, and includes a critical usage warning. It is front-loaded with the primary purpose. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is comprehensive. It explains both modes, the return values, the rationale for usage, and potential risks. An agent has all necessary information to correctly invoke this tool in the intended 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 description coverage is 100%, and the description adds meaning beyond the schema: it explains the default behavior for 'side' (auto for basket), clarifies the interpretation of 'size_usd' for each mode (max spend vs target proceeds vs settlement notional), and provides usage context for event and market parameters. This significantly aids correct parameter selection.

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 specifies the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and lists specific outputs (top_of_book, vwap_fill_price, slippage_pp, etc.), effectively differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale—theoretical overround on thin books is not capturable and partial fills cause directional risk—and provides clear prerequisites (requires market or event).

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, but the description adds substantial behavioral context beyond those: compatibility_codes semantics, the gross-vs-net fee disclosure, the unclassified legs never being paired, and the temporal_alignment null meaning. It thoroughly discloses the matching limitations and edge cases, which is exactly what an agent needs to interpret the tool's output 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?

The description is long but information-dense and organized by modes, response fields, safety fields, and standing disclosures. Every sentence contributes a distinct operational fact, and key warnings are front-loaded in the opening sentence and reinforced near the end. It could be tightened slightly, but it earns its length given the tool's complexity and the absence of an output schema.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively: raw probabilities, top_spreads_pp, compatibility_warning/codes, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped_cross_type/subtype counters. It also explains null semantics and what is never paired. This is complete enough for an agent to invoke and interpret the tool correctly in both modes.

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 each parameter individually. The description adds meaning beyond that by explaining how the parameters interact: `topic` auto-fetches matching events on both venues, the explicit ticker/slug override the topic-mapped sides, and both modes share the same token-overlap matcher. This clarifies execution semantics rather than just listing values, so a 4 is warranted over the baseline 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 a precise verb and object: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool's scope from related arbitrage and edge tools by emphasizing cross-venue comparison and equivalent bet shapes, so an agent can tell what this tool does without opening the schema.

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

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

The description gives explicit usage guidance for both modes: when to use `topic` shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug`, and states that both modes run the identical matcher. It also warns that most pre-mapped topics return compatibility warnings and that pre-mapped ≠ tradeable. It does not name sibling alternatives like polymarket_arbitrage, but the within-tool routing 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?

Consistent with annotations (readOnly, idempotent, non-destructive) and adds scoping context. Does not mention potential error cases but annotations already cover safety.

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, fully front-loaded with purpose and usage, 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?

Adequately covers purpose, usage, scoping, and pairing. Lacks explicit error conditions but acceptable for a simple retrieval tool with robust annotations.

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

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

Schema coverage is 100%, so baseline is 3. Description adds scoping context but does not significantly extend the schema's parameter 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 retrieves a saved value or lists all keys when omitted, explicitly distinguishing from siblings 'remember' and 'forget'.

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

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

Provides a clear use case ('look up context stored earlier') and scoping information, though it does not explicitly state when not to use it.

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

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

The description discloses that setting mark_read:true flags events as read, implying a mutation. However, annotations declare readOnlyHint=true, indicating no write side effects. This contradiction undermines transparency and could mislead an agent.

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 (3-4 sentences), front-loaded with the purpose, and every sentence adds relevant detail without 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?

The description covers most operational aspects (return fields, filtering, mark_read side effect, polling, alternative endpoint) but the annotation contradiction creates ambiguity about side effects, reducing completeness 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 descriptions cover all 5 parameters (100% coverage). The description adds value by explaining mark_read's side effect, providing an example for type, and specifying ISO timestamp for since. It does not mention limit or unread_only, but the extra context improves 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 clearly states it pulls fired events from a subscription feed and returns recent alerts with specific fields. It distinguishes from siblings like list_subscriptions by focusing on event retrieval rather than subscription management.

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 context for usage: filtering by type and since, setting mark_read, and notes that polling works fine and an alternative endpoint exists. It does not explicitly exclude alternatives but gives enough context for typical 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant context: it makes one parallel call to multiple sources, describes fallback behavior (GDELT->GNews), mentions USPTO soft-failure, and outlines the return structure (changes[] grouped by source with pipeworx:// URIs).

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

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

The description is somewhat long but every sentence contributes useful information. It is front-loaded with example queries. Minor redundancy could be trimmed, but overall it is efficiently structured.

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

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

Given the tool has three required parameters, no output schema, and annotations indicating safety, the description provides complete context: data sources, fallback mechanism, parameter formats, return structure, and limitations. An agent can confidently invoke this tool based on the description alone.

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 covers 100% of parameters with descriptions, but the description adds value by providing usage examples for the since parameter (e.g., '7d', '30d', '1y'), clarifying that type is currently limited to 'company', and explaining that value can be a ticker or CIK.

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, then clearly states it is a change feed for a company within a time window. It lists specific data sources (SEC EDGAR, GDELT->GNews, USPTO) and distinguishes itself from the sibling tool entity_profile by noting when to use that instead.

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 tells when to use the tool (for 'what's new' queries) and when not to (use entity_profile for static profile). It provides guidance on the since parameter format (ISO date or relative shorthand) and typical values like '30d'.

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 (idempotentHint, destructiveHint), the description adds scoping by identifier, persistence differences for authenticated vs anonymous sessions, and retention duration (24 hours). 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?

Four sentences, efficiently conveying purpose, usage, behavior, and related tools. No unnecessary words; front-loaded with key information.

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

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

Given a simple key-value store with no output schema, the description covers all necessary aspects: purpose, when to use, behavior, and relationship to sibling tools. Complete and self-contained.

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

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

Schema already covers both parameters with descriptions. The description adds value by providing concrete examples (e.g., 'subject_property', 'target_ticker'), enhancing usability.

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 ('Save') and resource ('data'), and clearly distinguishes from sibling tools like recall and forget by mentioning them as paired operations.

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 clear usage scenarios ('discover something worth carrying forward') with examples, but lacks explicit when-not-to-use guidance. Still above average.

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 internal cascading ('Each call cascades through several lookup endpoints internally'), graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and ambiguity handling ('returns figi_candidates to pick from'). Annotations already mark the tool read-only and safe, so the description adds substantial behavioral context beyond what annotations provide.

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

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

The description is long but densely packed with useful information. It is structured with SUPPORTED TYPES and front-loaded with examples. While it could be shorter, each section contributes to correct usage; it's comprehensive without being repetitive.

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 thoroughly covers return behavior: identifier sources, unresolved identifiers handled under `unresolved`, and ambiguous matches producing `figi_candidates`. It also notes the tool replaces multiple manual lookups, setting expectations. This is 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?

The input schema covers both parameters at 100%, but the description adds essential meaning: examples (ticker, CIK, ISIN, brand name), constraints (e.g., never pass the full noun phrase for bonds), and type-specific behavior. This elevates the guidance well above the schema descriptions alone.

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

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

The description explicitly states the purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example queries and lists supported types, making the tool's function unmistakable and distinguishing it from other tools that consume identifiers.

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 clear guidance with 'Use FIRST whenever you have a name but need an ID.' It includes specific parameter instructions like 'Pass the ENTITY NAME ONLY' and warns against including trailing security-class words. However, it doesn't explicitly name alternative tools or conditions when not to use it, so it's not a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, covering core safety. The description adds behavioral details beyond these: it probes each entity with ai_visibility_check, returns a ranked list with score, confidence, and signal density, and treats the first entity as the subject. This enriches understanding without contradicting 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 concise sentences plus a parenthetical example, front-loading the core action and then providing context. Every sentence adds value with no fluff, making it efficient for an AI agent to parse.

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 adequately explains the return value: a ranked list with score, confidence, and signal density. Combined with annotations (readOnlyHint, etc.), the description covers usage, parameters, and behavior, making the tool fully understandable for an AI agent.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful value by explaining that 'entities' should have the first entry as the subject and provides examples for 'context'. This goes beyond the schema descriptions, which are already clear.

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: compare AI visibility across multiple entities side-by-side using ai_visibility_check, rank by score, and identify most/least recognized. It provides a specific use case example and distinguishes itself from sibling tools like ai_visibility_check.

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

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

The description explains when to use this tool ('useful for competitive AI-marketing audits') and implies not to use it for single-entity checks by referencing ai_visibility_check. It does not explicitly list when not to use or direct to alternatives, but the context is clear.

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

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

Annotations already declare safe read-only behavior. The description adds that bundlephobia's first measurement can take 5-30s and that partial failures are handled gracefully with sources_failed. 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 but is well-organized and front-loaded with the main purpose. Every sentence adds value; could be slightly more structured but remains clear.

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

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

Without an output schema, the description fully details the return fields (summary block, advisory details, links, alternatives) and failure behavior. Covers inputs, outputs, constraints, and ecosystem scope.

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

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

Schema coverage is 100%. Description adds context: scoped packages accepted for 'package', and version defaults to latest if omitted. This goes beyond schema basics.

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

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

The description clearly states the tool performs a composite check for adding npm packages, combining deps.dev and bundlephobia data. It is distinct from sibling tools, which focus on other domains (e.g., AI presence, research).

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

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

Explicitly mentions use cases: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also states NPM-only in v1 and points to deps.dev directly for other ecosystems.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds technical details: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars with truncation flag), and output features (character offsets, similarity scores). These go beyond annotations to inform agent of limitations and 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?

Four sentences, each carrying essential information: purpose, use case, paired tool, technical implementation details. Front-loaded with the core action. Zero redundant or irrelevant content.

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

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

Covers all necessary aspects for an agent: what the tool does, when to use it, how it works technically (embeddings, windows, truncation), output format (passages with offsets), and relationship to sibling tools. Although no output schema, the description adequately describes return values.

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% (3 params all described). Description provides concrete examples for 'text' (SEC 10-K) and 'query' (supply-chain risk, drug interactions). For 'limit', it mentions 'top-N passages' implicitly. This adds value 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?

Description clearly states 'Semantic search INSIDE a fetched record' and specifies the verb (search) and resource (a record's text). It distinguishes itself from siblings by explaining it is for sub-document retrieval and explicitly pairs 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 states when to use: 'when the record is too big to cram into the prompt'. Describes alternative approach (grounding over passages vs. whole document) and names a sibling tool (ask_pipeworx_grounded) for the complete workflow.

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

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

The description adds substantial behavioral details beyond annotations: requires OAuth, phone verification for SMS, 10/day SMS cap, webhook HMAC signing, and auto-disable after 10 failures. Annotations indicate idempotency and non-destructive nature, which the description does not contradict.

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 core purpose and then systematically covers types, delivery options, and constraints. It is efficient for the complexity but could benefit from slight structuring (e.g., bullet points or separate sections).

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

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

The description fully covers all parameters (type, params, delivery) with detailed sub-parameters, return value (subscription ID), prerequisites (OAuth account, phone verification), and edge cases (SMS cap, webhook failures). No output schema exists, but the description sufficiently explains what to expect.

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

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

The description enriches the schema by providing concrete examples for each subscription type (e.g., sec_8k with items, fred_series with series_id). The schema already has 100% coverage, so the description adds valuable usage examples without being redundant.

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 creates a proactive monitoring subscription, returns the subscription ID, and distinguishes itself from siblings like list_subscriptions and unsubscribe by specifying it is for creating new subscriptions.

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

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

The description provides clear context on when to use the tool: requires a Pipeworx OAuth account, describes supported subscription types with examples, and mentions delivery channel constraints. However, it does not explicitly contrast with alternatives like list_subscriptions or unsubscribe.

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, and destructiveHint=false, so the safety profile is clear. The description adds behavioral details like drawing from a live catalog of thousands of tools and returning exact tool+argument shapes, but these are more feature descriptions than behavioral restrictions or side effects.

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

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

The description is fairly long but front-loaded with alternative phrasings and structured logically. Every sentence contributes useful information, though a slight reduction in length could improve conciseness.

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

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

Given the single optional parameter and no output schema, the description adequately explains what the tool returns (category-bucketed example questions with tool+argument shapes) and its role in onboarding. It also references meta-tools to connect with the broader tool ecosystem.

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

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

Schema coverage is 100% and the schema already describes the 'topic' parameter well. The description adds value by listing example values for the topic and explaining the behavior when omitted (cross-category spread), which goes beyond the schema's 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 that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by positioning itself as the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly says when to use it ('when you do not yet know what Pipeworx can do' and 'Use this FIRST'). It also mentions that calling with no arguments gives the full spread and passing a topic focuses the results. However, it does not explicitly state when not to use it or provide alternative tools for specific scenarios beyond the meta-tools 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?

Discloses that the row is deactivated (not deleted) and historical events remain via recent_alerts, adding important context beyond annotations. 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?

Two sentences, no fluff, front-loaded with action and key constraint. Every sentence provides 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?

Covers essential aspects: what it does, ownership constraint, behavior (deactivate vs delete), and relation to recent_alerts. Sufficient for a simple 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 already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' with 100% coverage, so description adds no additional meaning.

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

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

Clearly states 'Cancel a subscription by id' with specific verb and resource. Ownership enforcement distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement, indicating when to use (own subscriptions) and when not to. Could be more explicit about context, but provides good guidance.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by explaining the nuanced semantics of verdicts: could_not_verify means the check did not happen and is not evidence, unsupported means no source found, and it discloses the verification_error field. This is critical behavioral context that annotations alone don't convey.

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

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

The description is long but efficiently structured: trigger phrases, purpose, routing logic, return semantics, and error semantics. Each section earns its place, though it is somewhat dense and could optionally be tightened by moving some examples elsewhere.

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 the absence of an output schema, the description fully enumerates verdicts, the error scenario, and the evidence/citation behavior. It provides enough operational detail for an agent to invoke the tool correctly without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that tolerance_pct overrides the implied tolerance and defaults to a cap of 5, and by illustrating claim formats. This extra nuance raises the score above baseline.

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 defines claim verification against authoritative sources with a specific verb ('verify') and resource. It opens with natural-language trigger phrases, distinguishes between financial and non-financial claims via distinct pipelines, and enumerates the verdict types returned, making it unmistakable from sibling tools like deep_research.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use context. It also details routing for company-financial vs. other claims. However, it doesn't name alternative tools for related but distinct needs (e.g., exploratory research), leaving some exclusions implicit.

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