Transit Land

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds value by detailing the free default model, the need for an Anthropic API key with direct payment, and the return structure (score, confidence, signals, raw_response, combined view), going beyond annotation information.

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

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

The description is three sentences, immediately stating the core purpose and key details (scoring, default model, API key requirement, return fields). Every sentence adds value, and the structure is front-loaded with the most critical information.

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

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

Given the tool's complexity and the lack of an output schema, the description adequately explains the return shape (per-model score, confidence, signals, raw_response, combined view) and addresses cost implications. It covers the essential behavioral aspects for an agent to decide 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%, so baseline is 3. The description adds meaningful context for each parameter: explains that 'models' can be omitted for just workers-ai, that '_apiKey' is optional but required for Anthropic, and that 'context' helps disambiguate. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's action ('probe one or more LLMs') and resource ('what they know about a business/brand/product/topic'), specifying the scoring range (0-100) and default model. It effectively distinguishes itself from sibling tools by focusing on AI visibility measurement.

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 use ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly state when not to use it or compare to alternatives. The explanation of API key requirements gives some guidance but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it is a single fast call, covers many sources, and returns with citations, providing useful context beyond the annotations.

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

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

The description is long but well-structured, with the key directive front-loaded. Every sentence adds value, though some redundancy exists in examples.

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

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

Given the tool's complexity, the description covers scope, use cases, and comparisons to siblings. No output schema exists, but the description mentions structured answers with citations, which is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description explains that the tool accepts natural language questions and lists aliases, but does not add significant new meaning beyond the schema.

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

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

The description clearly states the tool routes questions to a large set of tools and returns structured answers with citations. It distinguishes itself from web search and siblings by emphasizing authoritative structured data.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides examples of when to use it vs. siblings like ask_pipeworx_grounded and deep_research. Also lists typical query phrases, making usage 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 readOnly, openWorld, idempotent, non-destructive. Description adds current state (no active candidate, matches stable), purpose (testing routing improvements), and fallback behavior. Consistent and complementary.

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

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

Three sentences, front-loaded with key identity and current state. Each sentence adds value. Efficiently communicates the beta nature and usage.

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

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

Given no output schema and beta context, description covers identity, current behavior, purpose, and usage comparison. Sufficient for the tool's role as an experimental alternative 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 aliases documented. Description only mentions same arguments, no additional meaning beyond schema. Baseline 3 appropriate.

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

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

Clearly states it's a beta version of ask_pipeworx with universal router and same tools. Specifies verb 'ask', resource 'pipeworx beta', and distinguishes from sibling by noting experimental routing improvements.

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

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

Gives clear context: use when you want the newest routing, exactly like ask_pipeworx. Results compared against stable router. No explicit when-not, but alternatives 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?

Description discloses behavioral traits beyond annotations: makes one extra LLM call, returns specific response structure with evidence and refusal reasons, and explains refusal types. No contradiction with annotations; actually adds useful 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?

Description is front-loaded with purpose and is well-structured, but is quite long. It earns its space with valuable details, though some technical point (like cost) could be more concisely stated.

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

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

Given the complexity (5,245 tools) and lack of output schema, the description adequately covers return format, refusal reasons, and use cases. Missing some edge cases but sufficient for the agent to use correctly.

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

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

Input schema has 6 parameters all aliases for the same question field, with descriptions provided. Schema coverage is 100%, so baseline is 3. Tool description does not add parameter details beyond the schema, but it is clear that only one need be provided.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and specifies the process: picks the right tool, fetches data, extracts answer only from tool result. It distinguishes from sibling ask_pipeworx by noting the extra LLM call and 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?

Explicitly says when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts. Also advises when to prefer ask_pipeworx for casual lookups, providing clear when-not-to-use guidance.

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

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

Annotations indicate readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description goes far beyond these, detailing fan-out behavior, response shapes, resolver contract (confidence, alternatives), safety mechanisms (low-confidence matches, closed markets), and tradeability checks. No contradictions with annotations.

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

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

The description is long but well-structured with labeled sections (RESOLVER CONTRACT, etc.). Every sentence adds essential information for an agent to use the tool correctly. Given the tool's complexity, the length is justified and not verbose.

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

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

There is no output schema, so the description must fully explain return values. It does so comprehensively: result.market with price fields, result.analysis with edge and warnings, result.evidence keyed by source, resolver contract fields, parent event extractor, and news fallback logic. All critical behavioral aspects are covered.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: explains the 'market' parameter's flexibility, the 'depth' enum's behavior, and the 'include_raw' field's impact on response size. It contextualizes parameters without repeating schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from siblings by focusing on data-backed research rather than arbitrage or edge tracking, with explicit 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?

The description provides explicit use cases ('should I bet on X') and example inputs. It doesn't explicitly state when not to use, but the use cases are clear. Sibling tools like polymarket_arbitrage and polymarket_edges cover alternative scenarios, so the context is sufficient.

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, idempotentHint, openWorldHint, and non-destructive. Description adds rich detail: sources (SEC EDGAR/XBRL, FAERS), metrics (revenue, net income, cash, debt, adverse events, trials), and behavior like off-calendar fiscal year handling and sorting by primary metric. 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?

Dense with information but well-structured: starts with example triggers, then explains behavior for each type. Every sentence adds value, though slightly verbose with the off-calendar note.

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

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

Covers entity types, data sources, metrics, sorting, and return format (paired data + citation URIs). No output schema, but description adequately summarizes returns. Complete for a comparison tool.

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

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

Schema coverage is 100%, and description adds meaning: explains type='company' vs 'drug' data sources, and describes array values (tickers/CIKs for company, names for drug) with limits (2-5 items). This surpasses the schema's bare descriptions.

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

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

The description clearly states the tool does side-by-side comparisons of 2-5 companies or drugs, with explicit example phrases. It distinguishes from sibling tools like entity_profile by focusing on multi-entity comparison.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance and example queries.

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, openWorldHint, idempotentHint, and not destructive. The description adds significant context: account requirements, parallel execution, return format (findings packet with gaps, contradictions, citations), timing, and semantic excerpting. No contradictions with annotations.

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

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

The description is dense and well-structured with line breaks, front-loading critical information (account required, alternative tool). However, it is somewhat verbose with details about contradiction fields and hop fields that might be secondary. Still, every sentence serves a purpose.

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

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

Given the complexity of the tool, the description covers all necessary aspects: account requirements, depth modes, parallel execution, return format (including gaps, contradictions, citations), timing, and edge cases (breaking news). No output schema is provided, so the description compensates by explaining the response structure clearly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context to both parameters: it explains the enum values for depth (quick, standard, thorough) in detail, and clarifies that question can be broad and multi-part. This adds value beyond the schema.

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

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

The description clearly identifies the tool as performing grounded multi-source research across Pipeworx's structured data sources in one call. It distinguishes itself from siblings by explicitly stating it is not open-web search and referencing ask_pipeworx for single lookups or current news. The verb 'research' and resource 'structured data sources' are specific.

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

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

The description provides explicit guidance on when to use the tool (broad/multi-part questions over structured data) and when not to (single lookups, breaking news). It names specific alternative tools (ask_pipeworx) and explains depth options and second-hop iteration. This helps the agent select correctly.

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 false. The description adds context by explaining the result is 'upcoming departures' and specifying the stop_id format. No contradictions, and it supplements annotations with concrete formatting details.

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

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

The description is a single concise sentence that immediately states the purpose, followed by an inline example for the key parameter. Every word is functional; no fluff. Front-loaded with the core action.

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

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

Given the presence of an output schema and comprehensive annotations, the description is complete for a simple query tool. It covers the main purpose, key parameter format, and default behavior. No missing critical details.

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%, meaning all 4 parameters are described in the input schema. The description adds value by providing an explicit example of a valid stop_id and hinting at default behavior for service_date ('default today'). This goes beyond the schema's format descriptions.

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

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

The description clearly states the tool's purpose: 'Upcoming departures from a stop.' It uses a specific verb ('Upcoming departures') and resource ('stop'), differentiating it from sibling tools like search_stops which find stops, not departures.

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 that stop_id must be a Transitland onestop_id and provides an example, implying the requirement. However, it does not explicitly state when to use this tool vs alternatives, nor does it provide negative usage guidance. The sibling list includes search_stops for finding stop IDs, but no direct mention.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that results include full input schemas with curated examples and are ready to call directly, which enriches the behavioral understanding 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 front-loaded with the core purpose, then provides details and usage context. While somewhat long, every sentence adds meaningful information. Minor redundancy in listing domains could be tightened.

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

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

Given 6 parameters and no output schema, the description covers what the tool returns (top-N tools with names, descriptions, schemas, examples) and how to use it. It does not detail the exact JSON structure of the response, but that is reasonable without an output schema.

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

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

All 6 parameters are described with full coverage. The description clarifies that several parameters (q, task, search, description) are aliases for 'query,' and specifies default and max for 'limit.' This adds significant value 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 explicitly states the tool's purpose: 'Find tools by describing the data or task.' It lists multiple domains and explains the output (top-N relevant tools with schemas). Distinguishes from sibling tools by being a discovery tool versus specific task 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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance, though it does not explicitly state when not to use it.

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

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

Annotations already declare safe, idempotent, read-only. Description adds rich detail: the tool fans out across SEC, XBRL, USPTO, news, GLEIF, and returns specific fields. It documents a soft-fail for patents post-sunset. No contradictions; the description complements the annotations well.

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 efficient. Front-loaded with examples and a clear directive. Every sentence adds value (use case, behavior, return details, limitations). Could be slightly more concise, but the density of information justifies the length for a complex 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?

No output schema, so description must compensate. It thoroughly lists return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with details like URIs and sorting. It covers the tool's full behavior, including fallbacks and sunset. No gaps identified.

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. Description adds meaning: explains 'type' only supports 'company', 'value' accepts ticker or zero-padded CIK, and clarifies that names are not supported. Redundancy: param descriptions in schema already say similar things, but the text aggregates the key point. Slight improvement over schema alone.

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

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

Description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call'. Examples like 'company profile for Microsoft' and 'everything you know about $TICKER' make purpose immediately understandable. Sibling differentiation is present: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and references resolve_entity for name resolution.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' tells when to use. Foreshadows a limitation: 'names not supported (use resolve_entity first if you only have a name)'. Also warns about patents sunsetting. No alternative tools are listed, but the context is sufficient for an agent to choose correctly.

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

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

Annotations already indicate destructiveHint=true. The description reinforces destructive behavior ('delete', 'clear sensitive data') and adds usage context, but does not disclose additional behavioral traits like auth requirements 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?

Two sentences, front-loaded with the core action and resource, followed by usage guidance. Every sentence is purposeful and compact.

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 delete tool with one parameter and no output schema, the description is complete. It explains the tool's role in relation to siblings and covers appropriate use cases.

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

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

Schema covers 100% of the single parameter with description 'Memory key to delete'. The description text adds no extra semantic detail 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 verb 'Delete' and the resource 'previously stored memory by key'. It distinguishes itself from sibling tools 'remember' and 'recall' by mentioning pairing them.

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 context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions pair with remember and recall, providing alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' No contradiction with annotations.

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

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

The description is two sentences of moderate length, front-loaded with the main action. Each sentence adds value, but could be more concise by merging the use cases.

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

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

Given the simple input (URL, optional max_links) and no output schema, the description covers purpose, behavior, and output format adequately. Slightly more detail on edge cases or output structure would improve completeness.

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

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

Schema description coverage is 100% with both parameters documented. The description adds context about max_links default (25) and maximum (50) and clarifies the output format, slightly surpassing 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 generates a 'production-ready llms.txt file for any URL', specifying the verb (generate) and resource (llms.txt). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation.

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

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

The description lists explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing...') but does not explicitly state when not to use or compare with alternatives.

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

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

Annotations already provide safety traits (read-only, idempotent). The description adds behavioral details: specific return fields (feed id, url, operator, last fetch status) and pagination behavior, going 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?

One concise sentence (25 words) that front-loads the action and includes all key elements. 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 low complexity (2 optional params) and presence of an output schema, the description fully covers what the tool does, how to use it, and what it returns.

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 only 50%, but the description adds meaning to both parameters: 'filter by spec type' for 'spec' and 'paginate with limit' for 'limit', compensating for the missing schema description on 'limit'.

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

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

The description uses a specific verb 'List' and resource 'feeds', adds context about Transitland aggregation, and distinguishes from sibling tools which focus on different entities (agencies, routes, stops).

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 listing available feeds with filtering and pagination. No explicit alternatives are mentioned, but the sibling tools do not offer similar functionality, so 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 cover readOnly, idempotent, non-destructive; description adds return fields and scope (caller's subscriptions), adding value beyond annotations.

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

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

Two well-structured sentences: first states purpose and output, second provides usage guidance, with no extraneous 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?

Fully covers what the tool does, what it returns, and when to use it, consistent with simple tool scope and rich 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 covers the only parameter with clear description; tool description reinforces active-only default, aligning well.

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

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

Description clearly states it lists the caller's active subscriptions, specifies return fields, and distinguishes from sibling tools like subscribe/unsubscribe by its read nature.

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

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

Explicitly says to use for reviewing monitoring before adding more or finding an id to cancel, providing clear usage 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 provide no safety hints (false for all). Description adds critical behavioral details: rate-limited to 5 per identifier per day, free, no quota consumption, team reads daily, affects roadmap. No contradiction with annotations.

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

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

Every sentence is informative and earns its place. Starts with purpose, then usage guidelines, then behavioral notes. No fluff or redundancy.

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

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

Despite lacking output schema, the description explains what happens after submission (team reads, roadmap impact). All input parameters are covered, rate limits are stated, and no additional context is needed for correct invocation.

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

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

Schema coverage is 100% but description adds meaning: explains enum values with examples, specifies message length (1-2 sentences, 2000 chars), and clarifies context object fields. Goes well beyond schema descriptions.

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

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

The description uses specific verbs ('Tell', 'is broken, missing, or needs to exist') and clearly identifies the resource (Pipeworx team feedback). It distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than queries.

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

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

Explicitly lists when to use (bug, feature/data_gap, praise) and when not (don't paste user prompt). Also mentions rate limits and free usage, providing full context for appropriate invocation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description enriches this with: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and parameter effect (shorter windows for hot, longer for steady-state). This adds significant value beyond annotations.

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

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

The description is front-loaded with the main purpose and uses bullet-style enumeration for use cases. It is efficient but a bit lengthy. Every sentence earns its place, but 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?

Despite no output schema, the description adequately explains the return structure (top tools, top packs, total call volume) and parameter behavior. The tool's use cases and caching are covered. No gaps remain for an agent to misuse.

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

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

With 100% schema description coverage, baseline is 3. The description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This explains the semantic difference between enum values, increasing usefulness.

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 returns 'top tools, top packs, and total call volume' over a configurable window. The verb 'Returns' and specific resource listing make the purpose unambiguous. It differentiates from siblings by its unique output (trending data) and explicit 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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and checking alignment. This gives clear guidance on when to use. However, it does not explicitly contrast with similar siblings like 'discover_tools', missing an opportunity to clarify when not to use this 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 declare readOnlyHint, openWorldHint, idempotentHint = true, destructiveHint = false. The description aligns and adds deep behavioral context: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slug filtering), fill check logic, and cross-event pairing details. No contradiction with annotations.

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

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

The description is comprehensive but somewhat verbose. It front-loads the core purpose but then delves into many details (semantic anchor, partition filter, fill check). While every sentence adds value, a more structured format (e.g., bullet points for modes) could improve scanability. Still, it remains coherent and not overly long given complexity.

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

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

Without an output schema, the description fully explains the response structure: opportunities array with fields (gap_pp, suggested_trade, reasoning) and partition_check object in event mode. It covers edge cases like placeholders, low similarity skipping, and fill check indicating when not to trade. Nothing major is omitted.

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 both parameters described. The description adds significant meaning beyond schema: explains that 'event' expects slug like 'fed-decision-may-2026', 'topic' expects seed question, and no args triggers trending scan. Provides context for parameter values and behavior.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no-arg trending scan, event mode, topic mode) and explicitly contrasts with sibling tools like polymarket_fill_risk.

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

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

The description provides explicit when-to-use for each mode: no args for trending, event for specific markets, topic for cross-event scanning. It recommends event mode with example slugs and advises against trading when fill_check shows non-positive realizable edge. References polymarket_fill_risk as alternative for custom sizing.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: caching details (1h KV), model families, edge calculations, slippage assumptions, and diagnostics. No contradictions with annotations.

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

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

The description is comprehensive but verbose, with many technical details. It is structured into sections and front-loaded with purpose, but could be more concise without losing essential 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 no output schema, the description fully details the response structure (by_segment, fed_candidates, diagnostics) and explains caching, knobs, and empty segment reasons. It is complete for an information tool with 9 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%, baseline 3. The description adds value beyond schema by explaining parameter rationale (e.g., slippage_pp discusses Polymarket fees and thin depth) and special behaviors (e.g., min_partition_leg_kelly explains why min_kelly doesn't filter partitions).

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

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

The description clearly states the tool scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, specifying the action and resource. It distinguishes from sibling tools like polymarket_arbitrage by detailing three model families, making its purpose unique.

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 daily betting decisions ('what should I bet on today') and explains filtering via knobs. It notes Fed bets are excluded but does not explicitly state when not to use or compare to alternatives, though the sibling list provides 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?

Despite strong annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds crucial behavioral context: data source (daily snapshots), limitations (60-day TTL, snapshot availability gaps), and response semantics (trend computation, decay numbers from daily closes). 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?

Every sentence in the description is informative and necessary. It is structured logically: purpose, argument explanations, response breakdown, and limitations. Despite length, it remains efficient and front-loaded with key insight.

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 comprehensively covers the response fields (tracked, expired, snapshot_dates) with detailed attribute explanations. It also addresses data freshness, limitations, and edge cases (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?

The input schema already describes both parameters with default and range. The description adds value by explaining the 'window' parameter's role (snapshot family) and providing additional context for 'days' limit (max 30 as per schema clamp).

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 articulates the tool's purpose: measuring edge persistence and decay. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tool polymarket_edges by focusing on time-series analysis of edge age and trend.

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 when this tool is appropriate (e.g., differentiating fresh vs. old edges), but does not explicitly state when to avoid it or mention alternatives. The usage is clear but lacks explicit exclusions.

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 behavior. The description adds detailed behavioral context: walks the order-book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict (clean|degraded|cannot_fill). For basket mode, it explains per-leg fill detail, thin_legs, and forced directional risk. 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?

Well-structured: opens with purpose, then required parameters, then separate sections for single-market and basket modes. However, it is quite dense and could be made more concise by omitting some redundant clarifications. The length is justified by the tool's complexity, but there is minor room for trimming.

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

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

For a complex tool with two modes and no output schema, the description thoroughly documents return fields: for single-market (top_of_book, vwap_fill_price, slippage_pp, etc.) and for basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). Also covers edge cases like partial fills and size limits. Complete enough for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema: clarifies side defaults for both modes, explains size_usd in basket mode as 'settlement notional — shares per leg, each paying $1 at resolution', and mentions clamp range 10–1,000,000. Adds value but schema already describes parameters adequately.

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?

Specifically states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and clearly distinguishes two modes (single-market and basket). Explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on their signals.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains when not to rely on theoretical overround and warns about partial basket fills converting arb into directional position. Clearly states requirement of providing either 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?

Adds extensive behavioral context beyond annotations: safety fields (compatibility_warning, temporal_alignment, skipped_*), explanation of when spreads are real vs. meaningless, and caution about rarity of actionable spreads. 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?

Well-structured with front-loaded purpose and clear sections. Slightly verbose but each sentence adds value. Appropriate length for the complexity.

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

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

Despite no output schema, the description details response structure (legs, spread, warnings, alignment). Covers most scenarios, though missing explicit behavior when both topic and explicit are provided.

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 value by explaining parameter relationships (topic vs explicit) and listing topic values. Moderately 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific mention of delta and two modes. It distinguishes from siblings like polymarket_arbitrage by emphasizing cross-venue nature.

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?

Describes two modes (topic vs explicit) with clear examples and a strong warning that most pre-mapped topics return compatibility warnings, implying when not to rely on spreads. Lacks explicit exclusion of alternatives but provides actionable 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 provide safety profile (readOnly, idempotent, non-destructive). Description adds valuable context on scoping and pairing behavior beyond annotations.

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

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

Two sentences: first immediately states core function, second adds context and pairing. No wasted words, front-loaded with purpose.

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

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

Tool is simple with one optional parameter. Description covers when, how, scoping, and pairing. Annotations cover safety. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that omitting 'key' lists all keys, which extends meaning beyond the schema.

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

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

The description clearly states the tool's verb ('retrieve' or 'list') and resource ('value' or 'saved keys'), and distinguishes it from sibling tools 'remember' and 'forget'.

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

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

Explicitly tells when to use ('look up context the agent stored earlier'), provides concrete examples, mentions scoping, and points to siblings (remember, forget) for related operations.

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, destructiveHint=false, idempotentHint=true. The description adds valuable context: it returns source, citation_uri, and raw payload; describes mark_read behavior that affects subsequent calls. It does not contradict annotations. For a read-only tool, this is thorough. Score 4 because it adds beyond annotations but could mention ordering (most recent) more explicitly.

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

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

The description is four sentences, with the core purpose front-loaded. Every sentence adds new information: return fields, filters, mark_read behavior, and an alternative access method. No redundant or vague statements. It is concise yet comprehensive.

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

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

Given no output schema, the description covers return fields and filtering well. It explains mark_read's effect on subsequent calls. However, it does not explicitly state the default ordering (most recent by time) or that limit defaults to 50. Still, it is adequate for correct usage. Score 4: complete for most use cases.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds examples (e.g., 'sec_8k') and context for mark_read. It does not repeat schema docs but provides usage hints. This adds value beyond the schema, earning a 4.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed alerts) and the action (pull/return). It distinguishes from sibling tools like list_feeds and list_subscriptions by focusing on alerts. The verb 'Pull' and the mention of 'recent alerts' make 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 gives context: 'Polls work fine' suggests it's suitable for repeated calls, and it points to an external URL as an alternative. It does not explicitly state when not to use this tool versus siblings, but the filtering options and mark_read behavior provide clear usage guidance. A score of 4 reflects clear context with minor omissions.

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

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

Annotations indicate safe, read-only, idempotent behavior. Description adds details on parallel fan-out, fallback from GDELT to GNews, USPTO soft-fail, and return structure (changes grouped by source, total_changes, citation URIs). No contradictions.

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

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

Description is comprehensive but slightly verbose. Front-loaded with example queries and key info. Every sentence earns its place, but could be tightened.

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

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

Given no output schema, description explains return format (changes grouped by source, count, citation URIs). Covers multi-source behavior, fallback, and soft-fail. Complete for a complex tool.

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

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

Schema has 100% coverage. Description adds context: type limited to 'company', since accepts ISO or relative shorthand with typical monitoring suggestion, value as ticker or CIK. Enhances schema meaning.

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

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

The description clearly states the tool provides a change feed for a company in a recent window, listing sources (SEC, GDELT/GNews, USPTO) and example queries. It distinguishes from sibling entity_profile by advising when to use each.

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

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

Explicit usage scenarios are given ('What's new with X' etc.) and when not to use (use entity_profile for static profiles). Parameter guidance for since is also provided.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context: persistence scoped by identifier, 24-hour retention for anonymous sessions, and explicit mention of related tools (recall/forget). No contradictions with annotations.

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

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

The description is extremely concise (3 sentences) and front-loaded with the core purpose. Every sentence adds value without redundancy, making it easy to scan and understand quickly.

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 only two simple parameters and no output schema, the description fully covers the tool's behavior: storage mechanism, persistence rules, and relationship to sibling tools. No gaps remain.

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

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

Input schema already describes both parameters with examples (100% coverage). The description adds contextual meaning by explaining they form a key-value pair scoped by identifier, and provides usage examples that enhance 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 action: 'Save data the agent will need to reuse later.' It provides specific examples of what to store (resolved ticker, target address, etc.) and distinguishes from sibling tools like recall and forget, making the purpose unmistakable.

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

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

The description gives explicit guidance on when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with recall and forget, though it doesn't explicitly state when not to use the tool. Clear and actionable.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it internally cascades through multiple lookup endpoints, replacing 2-3 manual lookups, and explains return values per type. 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?

Description is detailed but not overly verbose. It is well-structured with examples and type-specific details. Could be slightly shorter, 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 two-parameter tool with no output schema, the description fully covers expected outputs and behavior. It explains what each entity type returns and that it replaces multiple lookups. 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%, baseline is 3. Description adds significant meaning: explains enum values (company/drug), describes input formats (ticker, CIK, name for company; brand/generic for drug), and details output for each type. Goes well beyond schema.

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

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

Description clearly states the tool resolves names to canonical IDs, provides query examples, and explicitly says 'Use FIRST whenever you have a name but need an ID.' It distinguishes from siblings by specifying it is for name-to-ID conversion, which no other sibling tool does.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also lists supported entity types and input formats. However, it does not explicitly state when not to use or mention alternative tools, though the strong 'first-use' guidance compensates.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it internally calls ai_visibility_check, requires an API key for certain models, and returns score, confidence, and signal density. This goes 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 three sentences, no fluff. It front-loads the main action (compare AI visibility), then explains mechanism and output. Every sentence earns its place, and the structure is logical.

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

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

Given the tool has 4 parameters and no output schema, the description fully covers the return format (ranked list with score, confidence, signal density), internal call mechanism, and usage context. It also clarifies the role of the first entity, making the description complete 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 coverage is 100% with well-described parameters. The description adds meaning by stating that the first entity in 'entities' is treated as the subject for narrative, which is not in the schema. It also clarifies that 'models' omits 'anthropic' by default, reinforcing 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 compares AI visibility across multiple entities side-by-side, using a specific verb 'compare' and resource 'AI presence'. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on competitive AI-marketing audits.

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

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

The description provides clear usage context: 'useful for competitive AI-marketing audits' and gives a concrete example question. While it doesn't explicitly exclude other uses or name alternatives, the context implies when to use this tool over single entity checks. A few more exclusions would push to 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 declare readOnly, idempotent, no destruction. Description adds graceful partial failure behavior, including bundlephobia's slow first measurement and sources_failed listing. 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?

Well-structured, front-loaded with purpose, then usage, return format, and limitations. No redundant sentences.

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

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

Despite no output schema, description fully explains return fields and behavior. Covers partial failures, version defaults, ecosystem limitations.

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

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

100% schema coverage. Description adds context: scoped packages accepted, version defaults to latest. Enhances schema.

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

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

Description clearly states it is a composite check for npm packages, aggregating license, advisories, version history, bundle size, and tree-shake support. Differentiates from siblings by being a one-call composite.

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 examples of when to use ('is X safe/popular/small', 'what does adding lodash cost me') and notes that non-npm ecosystems fall under a different tool (deps.dev:version directly).

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

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

Annotations already declare the tool as read-only, non-destructive, and idempotent. The description adds minor context (e.g., 'operators are the entities running services'), but does not disclose additional behavioral traits like pagination, rate limits, or result ordering.

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

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

Two sentences with no filler. The first sentence states the purpose and scope, the second clarifies what 'operators' are. Every word earns its place.

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

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

Given the good annotations and output schema, the description is adequate but lacks usage guidelines to differentiate from siblings. It does not describe return value structure (though output schema covers that) or explain parameter interactions.

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, so the description adds relatively little. However, it provides high-level grouping ('by name or geo') that helps agents understand the two main parameter modes (query vs. lat/lon/radius), which is not explicitly in the schema.

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

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

The description clearly states the tool searches 'transit agencies/operators by name or geo' and clarifies that operators are entities running services. This distinguishes it from sibling search tools like 'search_routes' and 'search_stops'.

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 does not provide any guidance on when to use this tool versus alternatives such as 'search_routes' or 'search_stops', nor does it mention prerequisites or limitations.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds no behavioral context beyond annotations, which is acceptable given rich 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: first states purpose, second lists route_type codes. Efficient and front-loaded, though could be slightly more 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?

With 8 parameters, 0 required, and a low schema coverage, the description partially fills gaps (route_type) but leaves many parameters unexplained. Output schema exists but is not used to compensate.

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

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

Description adds route_type code mappings (0-12) and mentions search criteria, but schema coverage is low (38%) and many parameters (lat, lon, radius_m, agency_id, operator_id, limit) are not explained. Partial compensation for missing schema descriptions.

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

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

Description clearly states it searches routes by name, type, agency, or location (specific verb+resource+criteria). Lacks explicit differentiation from sibling tools like search_agencies or search_stops, but context implies it is for routes.

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

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

No guidance on when to use this tool vs. alternatives. Does not mention when not to use or provide context about related 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no new behavioral context (e.g., pagination, limits, or data freshness). It does not contradict annotations.

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

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

Two sentences, front-loaded with purpose and a concrete example. 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?

With an output schema, return values are covered. However, the 7-parameter tool has no required parameters and the description only addresses one use case. Missing guidance on other parameters and cross-use with sibling tools.

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

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

Schema description coverage is 57%, and the description adds context for lat+lon+radius_m ('stops near point'). However, it does not explain other parameters like stop_id, query, or served_by_route_type 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 clearly states 'Search stops/stations' and provides a specific use case ('stops near point' with lat+lon+radius_m). It differentiates itself from siblings like search_routes or search_agencies by focusing on stops, though not explicitly.

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 one explicit usage scenario (stops near point) but does not compare with alternatives or specify when not to use. Usage guidance is implied rather than explicit.

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 safety traits (readOnly, idempotent) and the description adds behavioral details: truncation at 200K chars, embedding model (BGE-base-en), overlap window size (500 chars), and output format (passages with offsets and scores). 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?

Description is well-structured with front-loaded purpose and usage. Some redundancy (e.g., mentions truncation twice) slightly reduces conciseness, but still efficient.

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

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

Without output schema, the description explains return values (top-N passages with offsets and scores), covers limits, and mentions pairing with another tool. It is complete for effective use.

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

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

Schema coverage is 100%, but description adds context beyond schema: max char limit for 'text', natural-language query examples, and default limit. This enhances 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 'Semantic search INSIDE a fetched record' with a specific verb and resource. It explains the use case (record too large for prompt) and distinguishes itself from siblings by mentioning pairing 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 says 'Use when the record is too big to cram into the prompt' and provides guidance on when to use. It also suggests pairing with another tool, offering clear context for selection.

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

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

Annotations already indicate a write operation (readOnlyHint: false) and idempotency hint. The description adds value by detailing authentication requirements, return of a subscription ID, delivery channel limits (10/day SMS cap), and auto-disable after 10 consecutive webhook failures. No contradictions with annotations.

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

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

The description is front-loaded with purpose and return info, then details prerequisites and channel-specific notes. While somewhat lengthy, every section adds necessary context. Minor redundancy with schema but overall efficient given the complexity.

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

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

Given 3 parameters with nested objects and no output schema, the description fully covers: purpose, authentication, supported types with examples, delivery options, return value, and failure handling. An agent would have sufficient information to call the tool correctly.

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

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

The schema coverage is 100%, but the description enriches parameter understanding with type-specific examples, constraints (e.g., phone must be verified, webhook HTTPS only, signature verification details), and format guidance. This exceeds the schema's descriptions significantly.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes from siblings like list_subscriptions and unsubscribe by implying creation, but does not explicitly differentiate. The verb 'subscribe' and title 'Subscribe to Alerts' are self-explanatory.

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 prerequisites (Pipeworx OAuth account) and alternatives (anonymous/BYO cannot persist). It lists supported subscription types with detailed parameter examples and delivery channels. However, it does not directly tell when to use this tool versus other tools like list_subscriptions or just polling.

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 behavioral context: it returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog, and that calling with no argument gives a full spread. No contradictions with annotations.

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

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

The description is dense but every sentence contributes unique value: aliases, use case, output format, parameter guidance, and placement in the agent's workflow. It is well-structured with no filler or redundancy.

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

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

Given the simplicity (1 optional param, no output schema), the description is fully self-contained. It explains what the tool returns, how to invoke it, and the variety of categories, compensating for the lack of output schema. It provides complete information for an agent to select and use this tool correctly.

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

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

Schema coverage is 100% (topic described). The description enhances parameter meaning: explicitly states 'omit for full spread', provides concrete examples of topics ('finance, pharma, betting'), and explains the effect of the parameter on the output, going beyond the schema's brief description.

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

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

The description uses a specific verb-resource pair ('suggest questions' about 'what Pipeworx can do') and lists multiple aliases. It clearly distinguishes from sibling tools by positioning itself as the onboarding entry point, contrasting with tools like discover_tools or ask_pipeworx.

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 ('FIRST when you do not yet know what Pipeworx can do') and when not (implies after you know, use other tools). Name-drops specific sibling meta-tools (ask_pipeworx, entity_profile, etc.) and explains how the results help learn tool calls.

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 significant behavioral context beyond the annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events. There is no contradiction with the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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

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

The description is extremely concise: two sentences that front-load the core action and then add relevant behavioral details. Every word serves a purpose 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 the tool's simplicity (one parameter, no output schema), the description covers the key aspects: action, ownership, and side effects. It could mention idempotency (covered by annotations) or return value, but is sufficiently complete for an agent to use correctly.

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

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

The input schema has 100% coverage with a clear description for the 'id' parameter ('Subscription id (uuid) returned by subscribe.'). The description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and identifies the resource (subscription). It also distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation behavior.

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

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

The description provides clear context: ownership is enforced so you can only cancel your own subscriptions. It explains the effect (deactivation, not deletion). However, it does not explicitly state when not to use it or suggest alternative tools for related actions.

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 value by detailing the two processing pipelines (fast path for financial claims, grounded pipeline for others), the verdict types, and the evidence citation format—beyond what annotations 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 moderately long but well-organized: examples first, then core logic, then return details. Every sentence adds value (purpose, scope, behavior, output). Slight redundancy in listing many query examples, but overall efficient.

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

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

With only 2 well-documented parameters, no output schema, and robust annotations, the description provides complete context: what the tool does, how it handles different claim types, what verdicts it returns, and how it cites sources. No gaps for the agent to infer.

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

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

Input schema coverage is 100% with detailed descriptions for both parameters (claim and tolerance_pct). The description reaffirms the tolerance_pct override role but adds no new semantic information beyond the schema, meeting the baseline for high 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 begins with natural-language examples precisely indicating the tool's purpose: verifying factual claims. It clearly distinguishes between company-financial claims (SEC EDGAR+XBRL path) and other claims (grounded pipeline), making its scope explicit and distinct from sibling tools.

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

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

It states 'Use whenever the agent needs to check whether something a user said is factually correct'—a direct usage guideline. It also explains fallback routing and efficiency benefits (replaces 4-6 calls). Missing explicit 'when not to use' scenarios, but the guidance is clear.

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