Visa Requirements

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds behavioral details: probing LLMs, scoring 0-100, cost implications (BYO key for Anthropic), and default model (free). It does not detail rate limits or error handling but sufficiently supplements 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, front-loaded with the primary action, and each sentence provides distinct value: action/scope, default model/cost, output structure, and use cases. No waste.

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

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

For a tool with 4 parameters and no output schema, the description comprehensively covers input semantics (entity, models, _apiKey, context), returns (per-model fields + combined view), and use cases. It is complete enough for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context like 'free' for Workers AI and 'passed straight through to api.anthropic.com' for _apiKey, but these are not essential beyond the schema descriptions. The description does not significantly enhance 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 action ('probe one or more LLMs... score visibility (0-100) per model') and the specific resources (LLMs, entity). It distinguishes itself from siblings like 'compare_entities' and 'entity_profile' by focusing on AI visibility scoring.

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

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

The description provides clear contexts for use ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), but does not explicitly state when not to use the tool or name alternative tools. It implies usage scenarios 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 cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explaining that the tool routes across many sub-tools, fills arguments automatically, and returns stable citation URIs. It does not mention latency, failure modes, or rate limits, but given the annotation coverage this is a minor gap.

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 appropriately sized for a broad meta-tool. It front-loads the most important instruction ('PREFER OVER WEB SEARCH'), then covers scope, invocation patterns, examples, and sibling alternatives without filler. Every sentence serves a clear 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?

Despite having no output schema, the description explains the return format, the citation behavior, the routing behavior, and the main alternative tools. It is complete enough for an agent to select and invoke this tool correctly in most situations.

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

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

Schema description coverage is 100%, and the schema already documents the question parameter and its aliases. The description adds useful example queries and trigger phrases, but it does not add meaningfully new parameter semantics beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a factual question-routing tool: it takes a natural-language question, routes it to one of 5,710 tools across 1,494 verified sources, and returns a structured answer with pipeworx:// citation URIs. The scope is explicit with concrete domains, and it distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and trigger phrases like 'what is', 'look up', 'find', 'get the latest'. It also lists when-not-to-use alternatives: remember/recall for memory, ask_pipeworx_grounded for supporting quotes, and deep_research for long multi-part reports.

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 safe, read-only, idempotent operation, but the description adds valuable dynamic behavior: candidate routing improvements are only active during tests, no candidate is currently active, and the tool currently matches ask_pipeworx exactly. It also discloses that results are compared against the stable router and that this is a full working router rather than a fallback stub.

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 compact and every sentence contributes important context: beta status, equivalence to ask_pipeworx, current live behavior, and experimental evaluation. The phrase 'Falls back to nothing' is slightly ambiguous, but the clarification immediately after prevents major confusion.

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

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

Given no output schema, the description compensates by explicitly stating the response shape matches ask_pipeworx. It covers the current experimental state, the absence of an active candidate, and how results are evaluated, making it complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, with parameters documented as aliases for 'question'. The description adds only that it takes the same arguments as ask_pipeworx, which is a useful cross-reference but does not provide new parameter-level semantics beyond what the schema already offers.

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 this as a beta version of ask_pipeworx and explains that it is an identical universal router with the same 5,710 tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx sibling by noting the experimental routing improvements, so an agent can distinguish it without opening schemas.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, giving clear context for selection. It does not list exclusions or contrast it with ask_pipeworx_grounded, but the 'newest routing' condition is a strong usage signal.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint:false) already establish the safety profile, and the description adds substantial behavior beyond them: the full success contract ({answer, evidence as verbatim quote, confidence, source, fetched_at}), the explicit refusal envelope with seven enumerated refusal_reason values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the cost tradeoff (one extra LLM call). The strict 'ONLY what the tool result contains' guarantee is exactly the kind of behavioral disclosure annotations cannot express. Consistent with annotations — 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?

Roughly 115 words, front-loaded with the core differentiator and organized as behavior → return contract → refusal contract → usage guidance → cost tradeoff. Every sentence earns its place; there is no filler. It loses one point only because it is a single dense paragraph that would benefit from a little structural breathing room, and the usage sentence slightly overlaps the opening 'high-stakes reads' framing.

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

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

With no output schema, the description fully carries the return-shape load: success object, refusal envelope, refusal_reason taxonomy, cost, and grounding guarantee. It also names the primary alternative. The only marginal gaps are not addressing ask_pipeworx_beta (another sibling that may compete for the same call) and lacking a short worked example — minor omissions that do not block correct selection or 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?

Context signals report 100% schema description coverage, so the baseline of 3 applies; the schema's question parameter is already well-documented with aliases (query, q, prompt, text, input). The description only says 'fills arguments,' which describes routing behavior rather than adding per-parameter meaning. The rendered schema fragment contained corrupted/duplicated content, but the declared coverage signal keeps this at baseline rather than requiring compensation from the 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 opens with a precise verb+resource pair — 'Hallucination-resistant answer mode for high-stakes reads' — and explains the mechanism: picks from 5,710 tools across 1,494 sources, fills arguments, fetches data, then extracts the answer only from what the tool result contains. It explicitly carves its niche versus the sibling ask_pipeworx ('Same routing as ask_pipeworx … then EXTRACTS the answer using ONLY what the tool result contains'), so an agent can distinguish this from its siblings without opening schemas.

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

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

Gives explicit when-to-use criteria: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also gives the exclusion and the alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is textbook routing guidance with no left-to-inference gaps.

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 read-only, idempotent, non-destructive. The description adds extensive behavioral details: fan-out logic, response shapes, handling of low-confidence matches, closed markets, wide spreads, cancellation rules, safety mechanisms (blocking statuses). This goes far 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 very long (500+ words) with extensive detail on edge cases and response shapes. While well-organized, it is not concise for an AI agent; key information could be prioritized.

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

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

Given the tool's complexity (multiple fan-out categories, response shapes, edge cases), the description is exhaustive. It explains return values (market, analysis, evidence) and covers safety, interpretation, and resolution details. No output schema exists, so description carries full burden and does so thoroughly.

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

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

Schema covers 100% of parameters. The description adds usage examples, depth enum details, and size implications for include_raw. It supplements schema with practical context.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). It distinguishes from siblings like 'ask_pipeworx' or 'polymarket_edges' by focusing specifically on Polymarket bets with a fan-out mechanism.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives rich context on when to use but does not explicitly mention when not to use or compare to sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds significant behavioral context: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). No contradictions with annotations.

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

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

The description is 6-7 sentences, well-structured with natural language triggers first, then behavior, then specifics. It efficiently conveys the tool's value without fluff. A minor reduction for slightly verbose examples, but still excellent.

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

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

Given the tool's complexity (two entity types, different data sources, sorting, citation URIs) and no output schema, the description covers all major aspects. It explains what to expect for each type and the efficiency gain. Minor gaps like pagination or limits are not critical for this tool.

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

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

Input schema coverage is 100% with descriptions for both parameters (type and values). The description adds context about what data is retrieved for each type and that results are sorted, but it does not add new semantic meaning beyond the schema's descriptions. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides clear examples of natural language triggers ('compare X and Y', 'which is bigger') and specifies the data retrieved for each entity type (financials for companies, adverse-event counts for drugs). This clearly distinguishes it from siblings like entity_profile which returns a single entity.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It implies when to use (comparing 2-5 entities) and when not to (sequential lookups are discouraged). It also provides alternatives implicitly by naming the tool as the preferred method for comparisons.

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

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

Annotations already mark the tool read-only, idempotent, open-world, and non-destructive, so the description does not need to repeat those. It adds rich behavioral context: parallel routing to 5,710 tools, verbatim evidence with confidence/source/fetched_at/citations, explicit gaps[] with a never-invents guarantee, contradictions[] for standard/thorough, semantic excerpting, and latency ranges. Nothing here contradicts 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 dense but not padded; every sentence carries operational information such as auth, scope, output structure, alternatives, and latency. It front-loads the most decision-relevant facts (account requirement, not open-web search) before the mechanics. It could be slightly more scannable with bullets or shorter sentences, but it earns its length.

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

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

This is a complex tool with no output schema, so the description carries the full burden of explaining return behavior. It does so thoroughly: findings packet fields, gaps[], contradictions[], citations, excerpting, latency, auth tiers, and the sibling to use instead. An agent has enough context to decide when to call it and what to expect back.

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

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

Schema description coverage is 100%, and the input schema already documents both parameters thoroughly, including the depth enum's hop counts, gap-recovery behavior, contradictions scan, and paid status. The description adds some timing and auth context but does not materially extend parameter-level semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources' in ONE call, and explicitly distinguishes itself from open-web search. It also differentiates from the sibling ask_pipeworx by noting it is for single lookups. The decomposition, parallel routing, and findings-packet output make the tool's function 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?

Gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' with concrete examples. It also names the alternative: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead.' The paid-tier requirement for 'thorough' depth is also disclosed, so an agent can route or warn 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 provide read-only, idempotent, and non-destructive hints. The description adds value by clarifying that each result includes full input schemas with examples and is ready to call directly, eliminating the need for a second lookup.

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

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

The description is well-structured, starting with the core purpose, followed by usage context, domain list, return format, and actionable advice. It is slightly lengthy 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?

Given no output schema, the description sufficiently explains return content (names, descriptions, full schemas with examples, ready to call). It covers behavior, when to use, and expected output, making it complete for a tool discovery function.

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

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

Schema coverage is 100%, so baseline 3. The description mentions the query parameter accepts natural language and lists aliases, but this largely mirrors the schema. No additional semantic details are provided beyond the schema's own descriptions and examples.

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

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

The description uses the verb 'Find tools' and specifies the resource (tools) with concrete domains and return details. It distinguishes this discovery tool from its many siblings by positioning it as the first call to explore available tools.

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

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

Explicitly states when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists specific data/task types, providing clear 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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: parallel execution across multiple sources, soft-fail for patents (USPTO API sunset), and specific return fields. No contradiction with annotations.

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

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

The description is a single dense paragraph, but it is front-loaded with example queries and structured logically from examples to details. While every sentence adds value, it could benefit from bullet points or slightly more concise phrasing for easier scanning.

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 details return fields like cik, company_name, recent_filings (with URIs), fundamentals, patents (with sunset notice), news, and LEI. It also notes limitations (patents soft-fail, name not supported), making it complete for a complex tool.

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

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

Schema coverage is 100% with both parameters described in the schema. The description adds meaning beyond the schema: explains that 'value' must be ticker or zero-padded CIK, and that names are not supported. This enhances understanding of parameter usage.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' and gives multiple example queries like 'Tell me about X' or 'company profile for Microsoft'. It distinguishes itself from sibling tools like resolve_entity by noting that names are not supported directly, requiring resolution first.

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

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

The description explicitly advises to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use resolve_entity first if only a name is available. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true, and the description confirms the destructive action but adds no new behavioral traits beyond 'delete' and 'clear sensitive data.' There is no mention of return behavior, error handling, or permissions.

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

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

The description is concise with three sentences: purpose, usage guidance, and pairing suggestion. It is front-loaded with the core action and contains no wasted words.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose and usage adequately. It does not specify behavior when the key does not exist, but the idempotentHint suggests a graceful no-op. Overall complete enough for the tool's complexity.

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

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

Schema coverage is 100% for the single parameter, and the description adds no additional meaning beyond 'by key,' which is already covered by the schema description. Baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using the verb 'Delete' and specifying the resource 'memory'. It distinguishes from siblings by mentioning 'Pair with remember and recall.'

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

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

The description provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with related tools. However, it does not explicitly state 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context by stating the tool fetches the page, extracts title/description/key links, and emits a standard format. This goes beyond the annotations by explaining the actual actions taken.

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

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

The description is concise, with two main sentences and a bullet-like list of use cases. It is front-loaded with the primary purpose. Minor wordiness in the 'Useful for' section could be tightened, 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?

Given the tool has only 2 parameters, no output schema, and rich annotations, the description provides sufficient context: purpose, output format, use cases. It lacks details on error handling or validation, but these are acceptable gaps given the tool's simplicity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add new meaning beyond what the schema provides; it only reiterates the extraction of links. The baseline of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the verb 'Generate', the resource 'llms.txt file', and the target audience (AI crawlers). It distinguishes from sibling tools by focusing on producing the standard file format, not just checking AI visibility.

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 concrete use cases (getting a client's site indexed, drafting for own project, auditing competitors), providing clear context for when to use the tool. It does not explicitly mention when not to use it or compare to alternatives, but the use cases implicitly differentiate it from related siblings.

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

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

Annotations already cover readOnly, idempotent, non-destructive. Description adds that it returns specific fields and defaults to active subscriptions, complementing 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?

Two sentences, front-loaded with purpose and return fields, followed by usage guidance. No superfluous text.

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?

Complete for a simple listing tool: describes purpose, return fields, parameter effect, and usage context. No output schema needed as return fields are listed.

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 one parameter with 100% coverage. Description adds context by explaining 'active' default and that include_inactive includes cancelled subscriptions, enhancing 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?

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from siblings like subscribe and unsubscribe by implying listing existing ones.

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: 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context relative to siblings.

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

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

Although annotations are all false, the description adds meaningful behavioral context: filing without an account returns a claim_token that can be passed back to check status, rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, and the team reads digests daily. This goes well beyond what annotations convey and gives the agent a clear picture of side effects and follow-up behavior.

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

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

The description is dense but every sentence carries essential information: scope restrictions, claim_token flow, rate limits, quota impact, and roadmap signaling. It is front-loaded with the core purpose. A slight deduction because it's a wall of text without bullet points, but it remains appropriately sized given the tool's complexity.

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

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

Given the tool's complexity (feedback categories, scope boundaries, claim_token lifecycle, rate limits, quota impact), the description covers all necessary context. It has no output schema, so the description carries the burden of explaining what happens after filing (returns claim_token, later status reads) and the operational details. There are no significant 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% and each parameter already has a detailed description. The tool description adds extra semantic value by explaining how claim_token fits into the workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and contextualizing the type enum in the usage guidelines. This exceeds the baseline of 3 for full schema coverage.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This immediately defines the tool's function and scope, distinguishing it from the sibling research/query tools. It also enumerates specific use cases (bug, feature/data_gap, praise), leaving no ambiguity about what the tool is for.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server ... file it with that server instead.' This is excellent when/when-not guidance with a concrete alternative.

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, destructiveHint. Description adds value by noting data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating signal.

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

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

Description is concise, well-structured with front-loaded purpose and bullet-like use cases. Every sentence adds value with no waste.

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

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

For a simple tool with one parameter and no output schema, description covers return values, data source, caching, and use cases adequately. Complete enough for effective use.

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

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

Schema coverage is 100% with enum and description. Description reinforces window choices but adds minimal extra meaning beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a window, using specific verb+resource. Differentiates from siblings like discover_tools and 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 lists three use cases for when to use the tool. Does not mention when not to use or alternatives, but the use cases are clear and provide good 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?

The description discloses significant behavioral details beyond annotations: monotonicity checks, partition-sum checks, Jaccard similarity threshold, placeholder filtering, and fill check against live CLOB depth. No contradiction with annotations (all read-only, idempotent).

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

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

The description is long but every sentence serves a purpose. It is front-loaded with the main use case and uses clear sections. Minor redundancy in explaining partition check twice, but overall efficient 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?

Given the tool's complexity (two modes, multiple checks, fill analysis) and the absence of an output schema, the description comprehensively details the response structure, conditions for signals, and when to avoid trading. It also points to a related tool for further actions.

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

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

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds rich semantics: explains the internal logic for each mode, provides examples of event slugs and topic phrases, and clarifies 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 on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

The description explicitly tells when to use each parameter: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It also warns when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context about the three model families, caching, and response structure, which enhances transparency beyond the safe-read annotation.

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 detailed but well-structured, front-loading purpose then detailing segments and knobs. It is not overly verbose given the complexity, though could be slightly more concise.

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 9 parameters with full schema, no output schema, and strong annotations, the description thoroughly covers response structure, caching, diagnostics for empty segments, and edge-case guidance, making it complete.

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

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

All 9 parameters have descriptions in the schema (100% coverage). The description adds value by explaining the purpose of knobs like min_liquidity and min_partition_leg_kelly, and how they affect results, going beyond the schema descriptions.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on disagreement and model-driven opportunities.

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 tool is described as being for discovery without paging, with explicit guidance on when to use segments and knobs. However, it does not explicitly state when to avoid using it or compare to sibling tools, though context implies it is for initial scanning.

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, including history bounded by 60-day TTL, decay from daily closes (not intraday), snapshot gaps due to cache-miss, and the meaning of edge_pp_net sign. 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 detailed but front-loaded with a clear summary. Every sentence adds value, though slightly verbose in places. Overall efficient 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?

Given no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and derived fields (trend, decay). Limits and caveats are covered. Complete for the tool's purpose.

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

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

Schema coverage is 100%, so baseline is 3. The description adds defaults, constraints (max 30), and defines window as snapshot family (24hr, 1wk, 1mo), providing meaning beyond the schema's parameter 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 provides edge persistence and decay telemetry from daily snapshots. It uses specific verbs like 'answers' and 'tracks', and distinguishes itself from siblings (e.g., polymarket_edges) by focusing on time series and decay, not just current edges.

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

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

The description implicitly guides usage by contrasting fresh vs. old edges and explaining response structure. It does not explicitly state when not to use or name alternatives, but the context is clear enough for an agent to infer appropriate use cases.

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 and idempotent. Description adds behavioral details: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and includes a verdict. 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?

Description is long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence adds value. Front-loads core purpose and is efficient with no wasted words.

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

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

Comprehensive explanation of return fields for both modes and usage context. Minor gap: does not specify behavior if both market and event are provided (likely error). Otherwise complete for a tool with no output schema.

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

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

Schema coverage is 100%, but description adds significant meaning: explains parameter dependencies (REQUIRES one of market or event), mode-specific interpretations of size_usd, and default values. 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 it checks realizable-vs-theoretical edge against live order book depth, distinguishes single-market and basket modes, and lists return fields. It is specific and differentiates from sibling tools like polymarket_arbitrage.

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

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

Explicitly states when to use ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains consequences of not using it (partial fills cause directional risk). Provides clear context and alternatives.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description goes far beyond them. It discloses the safety fields (compatibility_warning, compatibility_codes[]), lists all possible codes, explains that unclassified legs are never paired, and warns that pre-mapped pairings are unverified. This level of behavioral detail is exemplary.

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 clear labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes), and every sentence carries operational meaning. It front-loads the core purpose before diving into detailed flags and codes, which is appropriate given the tool's complexity.

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

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

For a tool with no output schema and only three optional parameters, the description is exceptionally complete. It explains response fields (spread, top_spreads_pp), safety codes, skipped-pair categories, temporal alignment, and real-world limitations. An agent has enough context to call the tool correctly and interpret results without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by explaining that topic auto-fetches the matching event on each venue, that explicit kalshi_event_ticker and polymarket_event_slug override the mapped side, and how the two modes interoperate. This moves beyond the schema's terse descriptions without being redundant.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' giving a specific verb, resource, and scope. It also clarifies the two entry modes (topic shortcuts vs. explicit ticker/slug), which effectively separates this from sibling Polymarket tools like polymarket_arbitrage and polymarket_edges.

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

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

The description clearly explains when to use topic mode vs. explicit mode and warns that most pre-mapped topics currently return compatibility warnings ('pre-mapped ≠ tradeable'). It stops short of explicitly naming alternative tools for comparison, but it provides strong within-tool routing guidance and caveats about when returned spreads are not trustworthy.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping and behavior when key is omitted (list all), without contradicting annotations.

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

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

Four sentences, front-loaded with core function, each sentence adds value (scoping, pairing). No unnecessary words.

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

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

Given low complexity (1 optional param, no output schema), the description fully covers behavior, scoping, and sibling relationships. 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%, so baseline is 3. The description provides usage examples but does not add new meaning beyond the schema's parameter description.

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

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

The description clearly states the tool retrieves or lists saved values, using specific verbs and resource. It distinguishes from siblings 'remember' and 'forget' by mentioning pairing, and gives concrete examples like ticker and address.

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 (look up stored context without re-deriving), implies when not (use 'remember' to save, 'forget' to delete), and explains scoping to identifier.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: the side-effect of mark_read flagging events as read, the polling suitability, and the alternative static feed. No contradictions.

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

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

The description is compact: 4 sentences that cover the core action, return structure, filtering, side-effect, and alternative access. Every sentence provides value. No fluff.

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

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

Despite having no output schema, the description mentions the return fields (source, citation_uri, payload). It documents all 5 parameters indirectly through the filtering examples. It also provides cross-reference (HTTP endpoint) and operational hint (polls work fine). Fully sufficient for a read-only list tool.

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

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

All 5 parameters are already described in the input schema (100% coverage). The description adds extra context: example for type ('sec_8k'), clarification that since is an ISO timestamp, and explains the effect of setting mark_read=true and how it affects subsequent calls.

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 starts with a clear verb and resource: 'Pull fired events from your subscription feed.' It also specifies what each returned event carries (source, citation_uri, raw event payload), distinguishing it from any sibling list tools by focusing on alerts from subscriptions.

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

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

Description mentions filtering by type and since, setting mark_read, and that polls work fine. It also provides an alternative HTTP endpoint, giving usage context. However, it doesn't explicitly state when not to use this tool vs. siblings like 'list_subscriptions', but the purpose is distinct enough.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds details: fans out to multiple sources, fallback to GNews when rate-limited, and USPTO soft-fail until reactivated. Lacks details on ordering or pagination of results but adds good behavioral context.

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

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

Single paragraph, but starts with example queries and logically flows through sources, parameters, and alternatives. Could be more structured but is efficient and informative.

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

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

With no output schema, description explains return format (grouped by source, total_changes, citation URIs). Covers fallback and soft-fail. Adequately complete for a moderate-complexity tool.

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

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

Schema covers all parameters (100% coverage). Description adds: 'type' limited to company, examples for 'value' (ticker or CIK), and relative shorthand for 'since' (e.g., '7d', '3m') with recommendation. Adds value 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?

The description clearly states the tool returns a change feed for a company, fanning out to SEC filings, news (GDELT/GNews), and patents. It provides example queries and explicitly distinguishes from sibling tool 'entity_profile'.

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

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

Explicitly states when to use ('What's new with X' queries) and when not to use ('Use entity_profile instead when you want the static profile'). Also provides recommended 'since' values like '30d' or '1m'.

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?

Disclosures go well beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Annotations idempotentHint=true and destructiveHint=false are consistent; description adds context about scope and retention policy.

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

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

Four sentences, each with distinct value: purpose, usage, examples, retention behavior, and pairing. No wasted words. Front-loaded with primary 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?

For a simple 2-parameter tool with no output schema, the description covers all necessary aspects: purpose, usage, behavior, retention, and relationship to siblings. Complete.

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

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

Schema covers 100% of parameters with clear descriptions. The description adds no additional parameter-level detail beyond the schema, but it does reinforce the purpose. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'save' and resource 'data the agent will need to reuse later', with concrete examples like resolved ticker, target address. It distinguishes itself from sibling tools recall and forget by explicitly mentioning pairing with 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?

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' and gives specific use cases. Also mentions when not to use by pairing with recall and forget, implying these are complementary.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, labels identifiers with their source, and explicitly lists unresolved identifiers. This goes well beyond the annotations and helps the agent anticipate edge cases.

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 front-loaded with realistic queries and a crisp summary of the tool's purpose. It packs a lot of necessary detail (types, sources, fallback behavior) without fluff. It could be tightened, but the length is justified by the tool's complexity and the need to disambiguate multiple entity types.

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 there is no output schema, the description does a strong job of describing expected returns: it lists the identifiers returned for companies (CIK, LEI, FIGI) and drugs (RxCUI, ingredient, brand), explains source labelling, and specifies that unresolved items appear under 'unresolved'. It also explains fallback behavior and when multiple internal lookups are replaced. This is nearly complete for an agent to know 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?

While the schema descriptions already cover the parameters (type and value), the description enriches them significantly. It gives concrete examples (AAPL, CIK, ozempic), explains the meaning of ISIN for company resolution, and elaborates on the drug type (returns RxCUI + ingredient + brand). This adds meaning beyond the schema's basic enum and string 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 opens with concrete example queries and clearly defines the tool's purpose: resolving a user-spoken name to canonical/official identifiers. It explicitly differentiates itself by saying 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

The description gives an explicit condition for use: 'Use FIRST whenever you have a name but need an ID.' This clearly signals when to invoke the tool. However, it lacks explicit guidance on when not to use it (e.g., if you already have an ID or need broader entity profiles), so it misses full exclusion clarity.

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

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

Discloses internal use of ai_visibility_check and return format (ranked list with score, confidence, signal density). Adds value beyond annotations without contradiction.

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

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

Two sentences, front-loaded action, no wasted words. Efficiently conveys key information.

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

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

Given no output schema, description covers return details, behavior, and parameter roles. Complete for a tool with 4 parameters.

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

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

Schema coverage is 100%, and description adds meaning by noting first entity is treated as subject for narrative, enhancing the entities parameter.

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 specifies compare/scan of AI visibility across multiple entities, distinguishes from sibling ai_visibility_check by emphasizing side-by-side comparison and ranking.

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 concrete use case ('does Claude know about us as well as our competitors?') but does not explicitly state when to avoid or list alternative tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds critical behavioral details: partial failures from bundlephobia timeout, graceful degradation, and sources_failed field. No contradictions.

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

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

Two well-structured sentences: first defines purpose and outputs, second covers usage and failure modes. Dense but efficient; minor room for tighter phrasing.

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

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

Despite no output schema, the description fully explains return structure (summary block, per-advisories, links, alternative versions), ecosystem limitation, and failure behavior. Comprehensive for agent decision-making.

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 repeats that version defaults to latest and scoped packages are accepted—both already in schema. No additional semantic value beyond what schema provides.

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

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

The description clearly defines the tool as a composite check for adding an npm package, listing specific checks (license, advisories, bundle size). It distinguishes from siblings by specifying NPM-only scope and naming alternative tools for other ecosystems.

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

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

Provides explicit guidance: 'Use whenever an agent asks "is X safe / popular / small"' and notes that PyPI/Maven/Cargo/Go fall under deps.dev:version directly, clarifying 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 already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds detailed behavioral context: embedding model (BGE-base-en), windowing (500-char overlapping), capacity cap (200K chars with truncation flag), and output structure (offsets, scores). This goes beyond annotations but is not fully exhaustive (e.g., no mention of rate limits).

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-paragraph structure is efficient: first paragraph defines core purpose and usage, second adds technical depth. Every sentence adds value, no repetition or fluff. Front-loaded with the most important info.

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

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

Given no output schema, the description adequately explains what the tool returns (passages with character offsets and similarity scores). It covers input constraints (200K chars), technical details (embeddings, windowing), and integration with 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?

Schema coverage is 100% but the description adds meaning beyond schema: it explains the truncation cap for 'text', gives a natural-language example for 'query', and states default for 'limit' (5). This compensates for any ambiguity in schema descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verbs like 'search inside' and 'returns passages'. It distinguishes from siblings by contrasting with fetching whole documents and mentioning its 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 states when to use ('when the record is too big to cram into the prompt'), explaining the benefit (saves context, returns only relevant passages). Also provides guidance on complementary tool (ask_pipeworx_grounded), indicating when to use 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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds substantial behavioral context: requires OAuth, delivery channel behaviors (SMS cap of 10/day, webhook auto-disable after 10 failures, signing secret returned once), and 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?

Description is appropriately sized for the tool's complexity, front-loaded with purpose, and uses structured examples for types and delivery. Every sentence adds value, though some sections are dense and could benefit from bullet-point formatting for readability.

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 (3 parameters with nested objects, 5 subscription types, multiple delivery channels), the description covers all necessary context: return value (subscription ID), authentication requirements, type-specific parameter formats, delivery constraints, and failure behaviors. No output schema needed as description adequately addresses return info.

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 rich meaning: type enum with concrete examples per type (e.g., sec_8k items codes, polymarket_edge topic/min_spread_bps), params with required fields per type, and delivery with SMS/email/webhook constraints. Exceeds baseline 3 by providing detailed type-specific parameter guidance.

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

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

Description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation, and lists supported types with examples.

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

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

Provides clear when-to-use context (creating subscriptions) and prerequisites (Pipeworx OAuth account). Mentions limitations (anonymous/BYO cannot persist) and details delivery channel options. However, it does not explicitly contrast with alternative subscription actions or provide 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the tool returns example questions with tool+argument shapes, but does not contradict annotations.

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

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

The description is somewhat long but front-loaded with key intent. Every sentence adds value, but minor trimming is possible for brevity.

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

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

Even without output schema, the description details what is returned (category-bucketed example questions with tool shapes). For a tool with one optional parameter and clear annotations, this is fully complete.

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

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

Schema coverage is 100%, and the description adds meaning by listing possible topic values (finance, pharma, etc.) and explaining behavior with/without topic, going beyond the schema's parameter description.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions, distinguishing it from sibling tools like ask_pipeworx or discover_tools. It specifies the exact use case of helping a new agent understand what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call meta-tools. It also describes optional topic parameter usage and the effect of omitting it.

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

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

The description adds context beyond annotations: ownership enforcement, deactivation vs deletion, and impact on historical events. No contradictions with annotations.

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

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

Two sentences, no wasted words, front-loaded with the action. Highly concise and well-structured.

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

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

For a simple tool with one required parameter, the description covers the action, ownership, and side effects completely. 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%, and the description does not add extra parameter meaning beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'cancel' and resource 'subscription by id', distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description explains ownership enforcement and the deactivation behavior, implying when to use, but does not explicitly state when not to use or compare to 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?

The description goes well beyond the annotations by disclosing the internal routing logic (SEC EDGAR/XBRL fast path vs. grounded pipeline), the return structure (verdict, actual value with citation, reasoning), and the semantics of each verdict, especially the critical distinction between could_not_verify (verification did not happen) and unsupported (no source exists). It also exposes that the tool replaces multiple sequential calls, providing behavioral transparency that annotations alone do not convey. No contradiction with annotations.

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

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

The description is longer than average but every sentence earns its place by specifying triggers, routing, return values, and error semantics. It is front-loaded with the core purpose and then logically expands into technical details. However, the trigger-phrase list could be shortened without loss, and there is slight redundancy between 'natural-language claim verification' and the later 'grounded pipeline.' Nonetheless, the structure is clear and appropriately detailed for the tool's complexity.

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

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

The tool has no output schema, so the description carries the full burden of explaining return values. It enumerates all possible verdicts (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify) and elaborates on the critical error semantics for could_not_verify and unsupported. It also specifies the scope (public US companies for financial claims) and the substitution of multiple calls. Given the tool's moderate complexity and rich annotations, the description is exceptionally complete—arguably covering more than expected.

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

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

The input schema already provides 100% coverage with highly detailed descriptions for both parameters, including examples and edge-case usage for tolerance_pct (e.g., overrides implied tolerance, default capped at 5). The tool description adds little beyond the schema; it mentions 'exact percent-delta math' but doesn't further explain the parameters. With such rich schema coverage, the baseline of 3 is appropriate; the description does not significantly enhance parameter 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 the tool's purpose as natural-language claim verification against authoritative sources, distinguishing it from sibling tools by specifying it replaces 4–6 sequential calls. It also explicitly differentiates between company-financial claims (SEC EDGAR/XBRL path) and all other factual claims (grounded pipeline). This is a specific verb+resource+scope definition that leaves no ambiguity about what the 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 whenever the agent needs to check whether something a user said is factually correct' and provides a list of natural-language trigger phrases. It clearly explains the two routing paths (financial vs. any other factual claim) and gives important guidance on how to interpret cannot_verify and unsupported results, effectively dictating when and how to use the tool. No alternative tools are named, but the usage context is unmistakably defined.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: grouping by requirement, including stay days for visa-free, counts for others, and data snapshot date (2026-02-18). No contradictions.

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

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

Two sentences plus an example, front-loaded with purpose. Every sentence adds value; no redundancy. Structured with clear question-answer framing.

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

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

No output schema, but description adequately explains output structure (grouped lists with stay days and counts). Data source and date are provided. Complete for a query tool of this complexity.

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

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

Schema coverage is 100%, but description adds meaning: explains default behavior (full lists for certain categories, counts for others), enumerates filter values, and provides an example. This adds value 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?

The description clearly states the tool lists destinations by visa requirement for a given passport, with specific verb 'Lists' and resource 'destinations for a passport'. It distinguishes from sibling tools like visa_requirement (specific country) and visa_passport_compare (comparison).

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

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

The description explains the tool's purpose and optional filter, implicitly guiding use for 'where can I go' queries. However, it lacks explicit when-not-to-use instructions or direct comparison to alternate tools, though sibling context provides differentiation.

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

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

Annotations already mark readOnlyHint=true and destruptiveHint=false. The description adds valuable context: data snapshot date, output structure (counts per category), and the extra list of differing destinations for 2 passports (up to 30). No contradictions.

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

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

The description is a single efficient sentence covering purpose, input range, output details, data source, and an example. Every sentence earns its place 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?

Despite lacking an output schema, the description fully explains the output (counts for categories, and for 2 passports a list of differences up to 30). It also provides the data source and date, making it complete for a simple one-parameter tool.

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

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

Schema description coverage is 100% (parameter description explains formats). The tool description reinforces with an example and adds behavioral context like the data snapshot and special case for 2 passports, enhancing 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 'Compare passport power' with specific resource and scope (2-5 passports, categories like visa-free, on arrival, etc.). It distinguishes from siblings like 'visa_free_destinations' and 'visa_requirement' which are single-passport 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 tells when to use this tool (for 2-5 passports) and mentions the special behavior for exactly 2 passports. It does not explicitly list when not to use or alternatives, but siblings are implicitly differentiated.

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, idempotent, and non-destructive. The description adds valuable context: data is community-maintained, last updated 2026-02-18, covering 199×199 country pairs, and advises verifying with official sources. It also illustrates the output format via an example. 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 concise and front-loaded with a natural language question ('Do I need a visa?'). It efficiently conveys purpose, input, output, coverage, data source, and an example in a few sentences without redundancy.

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

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

Despite lacking an output schema, the description compensates by listing possible return values, providing an example, stating coverage (199×199 country pairs), and noting data freshness and source. This is complete for a lookup tool with such 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 coverage is 100% with detailed descriptions for both parameters (passport and destination). The description goes beyond the schema by providing accepted formats (ISO2, ISO3, country name) and an example usage that explicitly shows how to call the function. This adds significant 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's function: it returns visa requirements for a single passport-destination pair. It lists possible return values (visa-free, visa on arrival, e-visa, eTA, visa required, no admission) and distinguishes itself from sibling tools like visa_free_destinations and visa_passport_compare by focusing on a single country pair.

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 implicitly guides usage by specifying input as one passport and one destination. However, it does not explicitly compare with sibling tools or state when to use this tool versus alternatives. An example and coverage note are provided, but clearer exclusion criteria would improve this dimension.

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