Phone

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

Annotations indicate safe, idempotent behavior. The description adds value by explaining the return structure (per-model score, signals, raw_response) and cost implications for Anthropic, going beyond annotation hints.

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

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

The description is a tight single paragraph of four sentences, front-loaded with the core action, and every sentence adds essential information 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?

The description covers the main behavior and output structure despite lacking an output schema. It explains model selection, key usage, and return format, though could elaborate on scoring methodology.

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

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

Schema description coverage is 100%, so baseline applies. The description adds minor extra context (e.g., default model, optional key purpose) but doesn't significantly enhance understanding of parameters 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 probes LLMs for visibility scores, with specific verb 'probe' and resource 'LLMs'. It lists use cases but does not explicitly differentiate from sibling tools like 'ask_pipeworx' or 'deep_research'.

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

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

The description provides clear context for when to use the tool (AI-marketing audits, brand checks) but does not explicitly state when not to use it or offer direct alternatives from 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 convey read-only, open-world, idempotent, and non-destructive behavior. The description enriches this with the tool's router behavior (fills arguments, invokes sources), its 'one fast call' performance, tier availability, and the citation URI return format — details the annotations do not cover. 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 long but each sentence earns its place: capture preference, behavior, triggers, examples, alternatives, and the news exception. It is front-loaded with the actionable 'PREFER OVER WEB SEARCH' directive. Slightly wordy due to the example list, but not padded.

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

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

For a high-complexity router with no output schema, this description is nearly complete: it states what it returns (structured answer with citations), when to use, when not, and how it routes. It could detail response fields or edge-case behavior, but the essentials for correct invocation are present.

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

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

The schema covers all six parameters at 100%, including a clear description of 'question' and its five aliases. The description adds general guidance on phrasing queries ('what is', 'look up') and examples, but no new parameter-level semantics, so the schema-heavy baseline of 3 stands.

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

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

The description names a specific function: routing natural-language questions to one of 5,706 tools and returning structured answers with stable citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the tool's role 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?

It explicitly states when to prefer this tool ('PREFER OVER WEB SEARCH', 'Use whenever...'), lists trigger phrases and concrete examples, and says when to step up to alternatives (ask_pipeworx_grounded for verbatim evidence, deep_research for multi-part questions). This is comprehensive routing guidance with clear 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?

The description discloses the key behavioral trait: it is an experimental router that may have candidate improvements enabled, but currently has no active candidate and therefore matches ask_pipeworx exactly. It also clarifies that it is a full working router rather than a fallback. This goes well beyond the annotations by explaining the dynamic experimental state and its current equivalence to the stable router.

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 yet well-structured, front-loading the beta status and key facts. The sentence about the retired candidate adds useful context but is slightly verbose with a specific date. Overall, every sentence earns its place, and the flow from beta status to usage guidance to router nature is logical.

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

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

Combined with 100% schema coverage and strong annotations (read-only, open-world, idempotent), the description gives an agent sufficient context to call the tool correctly. It explains the relationship to ask_pipeworx, the current state, and usage guidance. It omits an example question but that is minor given the clarity of the router concept and 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?

The input schema provides complete coverage (100%) for all six parameters, which are aliases for 'question'. The description adds no parameter-specific semantics—it only references that arguments are the same as ask_pipeworx. Since the schema fully documents the parameters, 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 the tool as a beta version of ask_pipeworx, a universal router that handles the same 5,706 tools and arguments. It distinguishes itself from the stable sibling by emphasizing the experimental edge and explicitly states it is a full working router, not a fallback. This gives an agent a precise understanding of what the tool does and how it differs from related tools.

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

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

It explicitly states to use this tool exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router to decide merges. This clearly indicates when to prefer this tool over the stable alternative and implicitly advises against using it when stable behavior is required.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing refusal reasons, evidence quoting, source/fetched_at metadata, and the extra LLM call cost. It precisely defines both success and refusal shapes, which is essential behavioral context.

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

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

The description is dense but every clause carries useful information: purpose, routing behavior, return contract, refusal semantics, usage boundaries, and cost trade-off. It is front-loaded with the core purpose and uses compact parentheticals for enumerations.

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 fully specifies the success response and all refusal_reason values. It also covers the key decision between this tool and ask_pipeworx, so the agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already documents the question parameter and its aliases. The tool description adds no additional parameter-level detail, so the 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 states a specific purpose: hallucination-resistant grounded answering that extracts answers only from tool results. It explicitly contrasts with ask_pipeworx, naming the sibling and distinguishing grounded behavior from casual lookup behavior.

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

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

Usage guidance is explicit: use when answers will be quoted, cited, or acted on in high-stakes domains, and prefer ask_pipeworx for casual lookups because of the extra LLM call. This gives clear when-to-use and when-not-to-use instructions.

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 and idempotentHint. The description adds extensive behavioral detail: market resolution, classification, parallel fan-out, response structure, resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits, closed market handling, spread warnings, and resolution-rule risk. 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 thorough but verbose with multiple paragraphs and detailed subsections. It is well-structured (e.g., use of headers) but could be more concise. Every sentence adds value, but overall length may overwhelm.

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

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

Given the tool's complexity, 3 parameters with full schema coverage, and no output schema, the description covers all relevant aspects: input formats, depth options, behavior for various bet types, response shapes, error handling, safety, and resolution rules. Nothing significant is missing.

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

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

Schema coverage is 100%, baseline 3. The description adds useful context: explains 'market' accepts slug, URL, or question text; 'depth' enum values (quick vs thorough); 'include_raw' defaults false with rationale for keeping responses small. This adds meaning 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 it researches a Polymarket bet by pulling Pipeworx data, with specific use cases and examples. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, though the verb 'research' and fan-out to data sources distinguishes it somewhat.

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

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

Provides explicit when-to-use scenarios ('should I bet on X'), explains classifiers, fan-out examples, safety mechanisms, and response shapes. Lacks explicit when-not-to-use guidance, but the blocking conditions (low confidence, closed markets) serve as implicit 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: for type='company', it details data sources (SEC EDGAR/XBRL), specific metrics (revenue, net income, cash, debt), and correct handling of off-calendar fiscal years. For type='drug', it specifies FAERS data, FDA approvals, and trial counts. It also explains sorting by primary metric and return format (paired data + citation URIs). This far exceeds what annotations provide.

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

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

The description is efficiently written with no wasted words. It front-loads the most important information (trigger phrases and core purpose) in the first sentence, then progressively details behavior. Each sentence adds distinct value, covering usage, data sources, sorting, and return format.

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 2 parameters, full annotations, and no output schema, the description covers purpose, data source, sorting, and return format. The mention of 'paired data + pipeworx:// citation URIs' is somewhat vague but sufficient given the tool's simplicity. It could be slightly more explicit about the exact structure of paired data.

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 enriches both parameters: it explains the 'type' enum options with concrete data details and clarifies the 'values' parameter format (tickers/CIKs for company, drug names for drug) plus min/max constraints. The description adds meaningful context beyond the schema's brief 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 starts with clear trigger phrases and explicitly states the tool does 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses specific verbs ('compare', 'rank') and distinct resource types, and it distinguishes itself from sibling tools like entity_profile by advocating preference over sequential lookups.

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

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

The description provides explicit when-to-use guidance with trigger examples ('compare X and Y', 'X vs Y') and states 'ALWAYS PREFER over sequential single-pack lookups.' It implies alternatives but does not explicitly name sibling tools or state when not to use. The guidance is clear and actionable, though exclusion conditions are absent.

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, open-world, idempotent, and non-destructive. The description complements this by specifying that it returns a list of codes and that filtering is possible. It does not contradict annotations and adds value by describing the default behavior (listing all) and the type of filtering accepted.

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

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

The description is extremely concise: two sentences that front-load the purpose and provide clear instructions. Every word serves a purpose, with no redundancy or extraneous information.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains the tool's functionality, the effect of using vs. omitting the parameter, and gives examples. There is no missing information needed for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds examples ('germany', '49') and clarifies that the query parameter accepts country name, ISO code, or calling code. This reinforces the schema description and provides practical usage context, exceeding the bare minimum.

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: looking up international calling codes. It specifies the behavior without arguments (lists all) and with a query (filters by country name, ISO code, or calling code), with concrete examples. This effectively distinguishes it from sibling tools, none of which serve the same function.

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

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

The description provides explicit guidance on when to use the tool with or without the query argument. It explains that without arguments, it returns all codes, and with a query, it filters. While it does not compare to alternatives, the tool's narrow scope makes such comparison unnecessary. The guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds a wealth of non-contradicting behavioral detail: account/plan requirements, parallel decomposition across 5,706 tools, output structure with gaps[] and contradictions[], explicit statement that findings are never invented, citation_uri resolvability, semantic excerpting, and latency expectations. This far exceeds what annotations alone convey.

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

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

The description is long but densely informative and front-loaded with the most critical gating information (account required, paid tier). Each sentence adds substantive guidance. Minor redundancy exists — 'use ask_pipeworx' appears three times — but overall it is well structured and appropriately sized for a tool with this complexity.

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

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

There is no output schema, so the description must explain return values, and it does: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], hop field, contradictions[], and citation_uri. Access requirements, latency, limitations relative to live news, and second-hop behavior are all covered. Nothing an agent needs to correctly call this tool is missing.

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 real value on top: it explains the depth enum values with behavior (quick=3 single hop, standard adds gap recovery and contradictions, thorough adds follow-up and paid), notes that 'thorough' needs a paid plan, clarifies that question can be 'broad/multi-part', and gives latency implications. This goes beyond the schema's dry descriptions.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources'. It explicitly differentiates from open-web search ('this is NOT open-web search') and from sibling tools like ask_pipeworx, giving concrete examples of target questions. This is enough for an agent to distinguish the tool from all siblings without inspecting schemas.

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

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

Extremely explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also names alternatives and conditions, leaving nothing to inference.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the output format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' No contradictions.

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

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

The description is concise (4 sentences) with a clear front-loaded purpose, followed by examples and key benefits. Every sentence serves a purpose, and there is no redundancy or fluff.

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

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

Given the tool's moderate complexity, annotations cover safety, schema covers parameters, and description explains the output format. Sibling tools are many, but the description clarifies the tool's role as a discovery interface. No output schema needed for this use case.

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

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

All 6 parameters are described in the schema with 100% coverage. The description provides contextual aliases (q, task, search, description) and example queries, but adds minimal meaning beyond the schema. 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 states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples (SEC filings, FDA drugs, etc.) and distinguishes it from siblings by emphasizing discovery rather than direct tool use.

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

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

The description explicitly advises when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear usage context and implies when not to use (when already knowing the target tool).

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fans out across multiple sources, returns specific fields (e.g., recent_filings with pipeworx URIs, fundamentals sorted by period_end), notes the USPTO API sunset May 2025 (soft-fails). No contradiction.

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

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

The description is relatively long but dense with essential information. It front-loads usage examples and key directives. Every sentence adds value, though it could be slightly more concise 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?

Despite lacking an output schema, the description thoroughly explains return values (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and limitations (USPTO sunset). Given the tool's multi-source nature, the description is complete and sufficient.

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

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

Schema coverage is 100%, and the description enriches both parameters: for 'type', clarifies only 'company' is supported; for 'value', provides examples (ticker or zero-padded CIK) and reiterates that names are not supported, adding value beyond the schema.

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

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

The description explicitly states the tool generates a 'full cross-source profile of a US public company in ONE parallel call', listing data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields. It clearly distinguishes from sibling tools like 'resolve_entity' by specifying that names are not supported.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies input requirements ('Pass ticker or CIK — names not supported') and suggests using 'resolve_entity' first if only a name is available.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description reinforces the destructive nature without contradiction, adding context about clearing sensitive data. No hidden behaviors, but adds minimal value beyond annotations.

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

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

Two sentences covering purpose, usage, and pairing. No fluff, every sentence earns its place.

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

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

For a simple, single-parameter tool with clear annotations, the description is complete. It covers what, when, and how to use, with no missing information.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete.' The tool description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' providing a specific verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by focusing on deletion.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also advises pairing with 'remember' and 'recall,' offering clear guidance on 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?

Goes beyond annotations by describing the fetch-extract-emit process and output format. Annotations already indicate read-only, idempotent, non-destructive; description adds behavioral detail 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?

Three precise sentences: purpose/audience, process, use cases. No wasted words, front-loaded with key information. Highly 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?

For a simple tool with 2 params, no output schema, and rich annotations, the description fully covers purpose, process, and use cases. 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 covers 100% of parameter descriptions, including defaults and limits. Description adds no new semantic information beyond the schema for either parameter, so baseline 3 is appropriate.

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

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

Description states specific verb (generate), resource (llms.txt file for a URL), and outcome (site indexing by AI). Clearly distinguishes from sibling tools, none of which perform the same function.

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

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

Explicitly lists use cases (client site indexing, own project drafting, competitor auditing). Does not mention when to avoid or compare directly to siblings, but provides clear context for usage.

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, etc. Description adds specific return fields and mentions filtering by active/inactive subscriptions, enhancing transparency beyond annotations.

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

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

Two sentences clearly convey purpose and usage with no extraneous information. Front-loaded with the main action.

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

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

Given the tool's simplicity (no required params, one boolean), the description covers purpose, usage, and output fields adequately without needing an output schema.

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

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

Schema description coverage is 100% and the parameter 'include_inactive' is fully described in the schema. The description does not add extra meaning beyond what the schema provides.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates return fields. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context for appropriate use.

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

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

With all annotations false, the description carries full burden for behavioral disclosure. It adds critical details: rate limit (5 per identifier per day), no quota cost, claim_token flow for follow-up, and the team's daily digest/roadmap impact. It also explains what happens when filing without an account, making the tool's behavior predictable.

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

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

The description is front-loaded with the core purpose, then uses a clear if/when/not structure. Every sentence earns its place: exclusions, token flow, rate limit, cost, and roadmap impact. Although it runs several sentences long, there is zero filler—each piece of information is necessary for correct invocation.

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 feedback tool with no output schema, the description fully covers return behavior (claim_token, later status check), constraints (only Pipeworx tools, daily limit), and intended use. It leaves no significant ambiguities for an AI agent deciding whether and how to call 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?

Schema coverage is 100%, so baseline is 3. The description enriches the schema by explaining the round-trip usage of `claim_token` ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs users to frame context in terms of Pipeworx tools/packs, which maps to the `context` object. This goes beyond the schema's field 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 a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx tools) and distinguishes itself from siblings like ask_pipeworx by focusing solely on feedback. It also enumerates the exact types of feedback (bug, feature/data_gap, praise), removing ambiguity.

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

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

The description provides explicit when-to-use guidance: '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 includes a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This fully addresses alternatives and boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable context: the data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and the self-aggregating nature. 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 approximately four sentences, front-loaded with the main purpose, and each sentence adds meaningful information without redundancy. It is efficiently structured and easy to parse.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage scenarios, data source, caching, and output format implicitly. It is fully informative for an AI agent to understand and use correctly.

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

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

Schema coverage is 100% for the single parameter 'window', and its description already explains the enum values and their interpretation. The description does not add new parameter details beyond what the schema provides, so a 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 uses specific verbs ('Returns') and resources ('top tools, top packs, total call volume'), distinguishing it from sibling tools like 'discover_tools' or 'ask_pipeworx'. It clearly states the scope (recent window) and what is returned.

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 enumerates three explicit use cases (discovering hot data sources, confirming canonical choice, checking alignment). While it does not explicitly state when not to use it or list alternatives, the context provided is strong enough for an agent to decide when to invoke 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?

The description details internal checks (Jaccard similarity threshold, placeholder filtering, fill check using CLOB depth) and explains when signals are meaningful. All behaviors are consistent with annotations (readOnlyHint, idempotentHint, openWorldHint). 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 thorough but well-organized with clear section breaks. Every sentence adds value, though it is on the longer side. It could be slightly more concise without losing information, but overall it is efficiently structured.

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

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

Given the complexity of the tool (multiple modes, edge cases, response fields), the description is remarkably complete. It covers default behavior, parameter details, internal filters, response structure, and recommended next steps. No output schema exists, but the description adequately explains return values.

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

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

Schema coverage is 100%, and the description adds rich context beyond the input schema: it provides examples of event slugs and topic seeds, explains the difference between modes, and clarifies behavior with each parameter. This significantly aids correct invocation.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (default trending scan, event mode for specific markets, topic mode for cross-event scanning), and contrasts with siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly tells when to use each parameter: default for trending scan, 'event' for a specific market (recommended), and 'topic' for cross-event scanning. It also warns against trading when realizable_edge_pp <= 0 and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: caching at KV level, response structure with diagnostics, and details on how tradeable-edge knobs work. 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 very long and detailed. It front-loads purpose but becomes verbose with technical methodology. While structured with headings, it is not concise and could be trimmed.

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

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

Given the complexity (9 parameters, three model families, detailed output), the description is very complete. It covers input, methodology, output structure, diagnostics, caching, and tradeable-edge knobs, compensating for the lack of 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%, so baseline is 3. The description adds minimal extra meaning beyond the schema; it repeats some parameter info but does not significantly enhance 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explains the three model families and differentiates from siblings by detailing its unique methodology.

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 says it's built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It provides context for when to use but lacks explicit exclusions or comparisons to sibling tools like polymarket_arbitrage.

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

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

Annotations confirm safe, read-only, idempotent behavior. The description adds extensive behavioral details: data from daily snapshots, explanation of response structure (tracked, expired, snapshot_dates), limits (60-day TTL, decay from daily closes), and handling of gaps. This goes well 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 information-dense and front-loaded with purpose. While it is somewhat long, every sentence adds value, and the structure follows a logical flow from purpose to response format to limitations. Conciseness is good given the complexity.

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

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

No output schema exists, so the description fully explains return values (tracked, expired, snapshot_dates) with their fields and meanings. It also covers data limits and sources, making the tool's behavior completely understandable for a read-only telemetry 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 clear descriptions. The description reiterates parameter defaults and bounds but does not add significant new meaning beyond what the schema already provides. 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 states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge duration. It distinguishes itself from sibling polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description implies usage for analyzing edge history but does not explicitly state when not to use or suggest alternatives like polymarket_edges for current snapshots. It offers implicit context but lacks explicit 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?

Despite annotations already indicating readOnlyHint=true and idempotentHint=true, the description adds significant behavioral context: walking the order book ladder, returning top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; basket mode returns theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], forced_directional_risk. No contradiction with annotations.

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

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

The description is fairly long but well-structured: opening sentence defines purpose, then breaks into SINGLE-MARKET and BASKET sections, each detailing parameters and returns. It ends with usage guidance. Each section earns its place, though some sentences could be slightly more concise without losing meaning.

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 (dual mode, 4 parameters, no output schema), the description is remarkably complete. It covers both modes, parameter semantics, return values (explicitly listed), and usage context. The absence of an output schema means the description must explain outputs, which it does thoroughly. The description even addresses edge cases like thin_legs and forced_directional_risk.

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%, but the description elaborates on parameters beyond the schema: explains dual-mode (market vs event) logic, default side behavior (auto for basket), size_usd interpretation for single vs basket (spend vs target proceeds vs settlement notional), and clamp range (10–1,000,000). This adds value over the schema alone.

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

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

The description clearly states the tool's core function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes with explicit usage examples. The verb 'check edge' and resource 'live CLOB order-book depth' are specific, and the tool is clearly differentiated from siblings 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 provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround on thin books not capturable, partial fills convert arb to directional position) and includes risk warnings. This is exemplary usage guidance.

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

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

The description goes well beyond the annotations by detailing runtime behavior that cannot be inferred from readOnly/idempotent hints alone. It explains that compatibility_warning and compatibility_codes[] can be non-empty even when matched_pairs>0, that legs with 'unknown' metric_type or match_subtype are never paired, that skipped_cross_type/subtype counters expose dropped comparisons, and how temporal_alignment works. This is rich behavioral disclosure.

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

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

The description is long but densely packed with operational information, organized from purpose to modes to response fields to safety caveats. The critical warning that compatibility fields should be read 'even when matched_pairs>0' is front-loaded well. It is appropriately sized for the tool's complexity, though slightly dense, so 4 rather than 5.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so extensively: leg-by-leg prices, top_spreads_pp, compatibility codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and skip counters. The only notable gap is that it never clarifies what happens when no parameters are supplied or how topic and explicit overrides interact when both are provided.

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

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

All three parameters are already described in the schema, giving a baseline of 3. The description adds meaningful context on top: it enumerates the 10 pre-mapped topic values, explains the two-mode logic, and clarifies that explicit ticker/slug override the topic-mapped side. This elevates the score to 4.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' naming the precise operation, the two involved venues, and the object of comparison. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on Kalshi–Polymarket spread computation and explicitly describing two modes.

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

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

The description gives clear context: it states the use case, enumerates two invocation modes (topic shortcuts vs explicit ticker/slug), and warns that 'most pre-mapped topics return compatibility_warning today' and 'pre-mapped ≠ tradeable.' However, it does not name alternative tools or provide explicit when-to-use vs when-to-use-another-tool conditions, so it falls short of a 5.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context about scoping (by identifier) and that omitting key lists all. 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?

Two sentences: first states core purpose, second adds usage context. No wasted words, front-loaded with key information.

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

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

Given low complexity, 1 parameter, no output schema, and strong annotations, the description covers all necessary context. It explains behavior, scoping, and pairing with siblings.

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 'key'. Schema description already explains the parameter. Description adds minimal extra context (pairing with remember/forget), but 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 specifies verb (retrieve/list), resource (saved values/keys), and clearly distinguishes from siblings (remember, forget). It states exactly what the tool does and its scope.

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

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

Description explains when to use (look up stored context without re-deriving) and mentions scoping and pairing with remember/forget. It does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true. Description adds valuable behavioral details: the effect of mark_read on subsequent calls (flagging events as read), that polls work fine, and the existence of an alternative REST endpoint. No contradictions.

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

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

Description is four sentences long, front-loaded with purpose, then details fields, filtering, mark_read effect, and polling alternative. Every sentence adds value without redundancy or 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?

Covers return content (source, citation_uri, raw payload), filtering, mark_read effect, polling, and alternative endpoint. Lacks explicit mention of ordering or pagination beyond the limit parameter, but given the read-only nature and annotations, it is fairly 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 all parameters have descriptions. The description briefly rephrases parameters (e.g., 'ISO timestamp' for since, 'mark_read:true' behavior) but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description uses specific verb 'Pull' and resource 'fired events from subscription feed', clearly stating the tool's function. It details what each alert carries (source, citation_uri, raw payload), but does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'subscribe', though the purpose is distinct.

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 context: filtering by type/since, mark_read effect, polling suitability, and an alternative REST endpoint. Does not explicitly exclude sibling tools or state when not to use, but the guidance is sufficient for typical use.

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

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

Adds significant context beyond annotations: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail. Describes return structure with changes[] and citation URIs. Annotations already indicate read-only, idempotent, non-destructive, and description aligns.

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

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

Well-structured with examples first, then fan-out explanation, parameter details, return structure, and sibling distinction. Every sentence adds value, though slightly long; could be tightened slightly but still very good.

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 complex tool: covers multiple data sources, fallback behavior, parameter formats, return structure, and sibling differentiation. No output schema, but return structure is described. Handles edge cases like soft-fail for USPTO.

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

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

Schema has 100% coverage with descriptions, but description adds more: 'since' accepts ISO or relative shorthand with examples; 'value' explains ticker or CIK; 'type' states only 'company' supported. Provides usage suggestion for 'since'.

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

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

The description clearly states the tool provides a change feed for a company in a time window, with example queries like 'What's new with X' and explains it fans out to multiple sources. It distinguishes from sibling entity_profile, which is for static profiles.

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 provides example queries and when to use (e.g., monitoring changes). States alternative: 'Use entity_profile instead when you want the static profile'. Also notes fallback behavior for news sources.

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 storage as key-value pair scoped by identifier, persistence differences (authenticated vs anonymous), and 24-hour retention for anonymous. Annotations only cover idempotency, so description adds significant 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?

Front-loaded with main purpose, efficient but includes examples that add clarity. Not overly verbose, earns its sentences.

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

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

Simple tool with 2 params and no output schema. Description covers purpose, usage, storage behavior, and persistence, making it fully sufficient for correct usage.

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

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

Schema covers 100% with descriptions for both key and value. Description adds context about scoping and persistence but no new parameter-specific details beyond what schema already provides.

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

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

Clearly states the tool saves data for reuse across sessions or conversations. Specifies verb 'save' and resource 'data for reuse', and distinguishes from sibling tools recall and forget by mentioning 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 context of when to use: 'when you discover something worth carrying forward'. Lists examples and mentions pairing with recall and forget. No explicit when-not-to-use, but overall clear.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive traits, and the description adds rich behavioral context: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of source for each identifier, and the 'unresolved' field instead of silent omission. These details go beyond the structured annotations and are highly valuable.

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

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

Although the description is lengthy, every sentence delivers useful information. It is structured with 'SUPPORTED TYPES,' explicit examples, and behavior caveats, making it easy to scan. The front-loaded examples immediately communicate the tool's purpose, and the dense but organized format is appropriate 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?

With no output schema, the description adequately covers return behavior: it specifies resolved identifiers (CIK, ticker, LEI, FIGI, RxCUI), labels sources, states the 'unresolved' field, and explains fallback behavior. It also covers both entity types and address ownership queries, making it complete for an agent to trust the tool's output format.

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 significantly extends parameter semantics. For 'value', it explains that company input accepts ticker, CIK, ISIN, or name; for drug, brand/generic names; and it clarifies how ISIN maps to legal entity via GLEIF. This adds meaning not present in the raw schema.

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

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

The description states a clear verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides multiple example queries ('What's the ticker for…'), and distinguishes itself from siblings by specifying the tool produces IDs for other tools. The supported types are delineated, so there is no ambiguity about its function.

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

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

Explicit usage guidance is given: 'Use FIRST whenever you have a name but need an ID.' Additionally, the description explains when to choose 'company' vs 'drug' types and covers edge cases like ISIN resolution to legal entities, providing clear decision support for tool selection.

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

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

Description explains composite behavior (probes each entity, returns ranked list with score/confidence/signal density). Annotations already declare read-only, open-world, idempotent, non-destructive; description adds context about output structure 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?

Three sentences, front-loaded with main action, no wasted words. Every sentence provides essential information.

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

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

Covers main parameters and return value format despite no output schema. Lacks error handling or edge cases, but annotations mitigate some risk. Adequate for the 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 value by noting first entity is treated as subject for narrative, and explaining models optionality. This enriches parameter understanding 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 compares AI visibility across multiple entities, probes with ai_visibility_check, and ranks results. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Explicitly says 'useful for competitive AI-marketing audits' and gives an example question. Implicitly differentiates from single-entity check by mentioning probes with ai_visibility_check, but lacks explicit when-not-to-use or alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds extra detail on partial failures and timing (bundlephobia first measurement can take 5-30s), which goes beyond annotations and aids agent decision-making.

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 the main purpose. However, the first sentence is quite long and could be split for better readability without losing information.

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

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

Given the tool's complexity, the description covers purpose, usage scenarios, ecosystem limit, failure behavior, and return structure (summary block, advisories, links, alternatives). No output schema is provided, but the description sufficiently explains the output.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minor context (scoped packages accepted, version defaults to latest) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly defines the tool as a composite check for adding an npm package, listing specific data points from deps.dev and bundlephobia. It distinguishes itself from sibling tools by focusing on package dependency analysis, unlike other scanning tools like scan_competitor_ai_presence.

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: for questions about safety, popularity, size, or cost of adding a package. Also notes the ecosystem limitation (npm only in v1) and mentions that other ecosystems fall under a different tool, providing 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?

Adds rich behavioral detail beyond annotations: describes embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character limit (200K chars), and truncation behavior. Discloses return format (passages with offsets and scores). 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?

Single well-structured paragraph of ~100 words. Front-loaded with core purpose, followed by usage guidance, then technical details. No verbose or redundant statements, though could be slightly more concise with bullet points for key behaviors.

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

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

Given no output schema, the description explains return values (passages with offsets and scores). Covers embedding method, chunking, truncation, and pairing with another tool. Missing error handling or edge cases, but adequate for typical use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how each parameter is used in context (e.g., 'text you already pulled' for text, 'natural-language query' for query, 'top-N passages' for limit), reinforcing semantics 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 the tool performs semantic search inside a fetched record, specifying the resource as 'text you already pulled' and distinguishing it from sibling tools like ask_pipeworx_grounded. The verb 'search inside' and resource 'fetched record' are specific and unambiguous.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns passages with offsets for verification). Mentions pairing with ask_pipeworx_grounded, providing clear guidance on 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 indicate this is an idempotent, non-destructive write operation. The description adds significant context: it requires an OAuth account, describes the returned subscription id, explains that SMS has a 10/day cap and requires phone verification, and notes that webhooks auto-disable after 10 consecutive failures. This goes well beyond the annotations.

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

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

The description is fairly long but every sentence adds necessary detail given the tool's complexity. It is front-loaded with the primary purpose. Could potentially be broken into bullet points for readability, but the current structure is adequate.

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

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

The description is comprehensive: it covers the tool's primary function, parameters, subscription types, delivery channels, prerequisites, side effects (rate limits, auto-disable), and return value. No output schema exists, but the return of subscription id is stated. The tool is complex, but the description fully addresses what an agent needs to know.

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 has 100% coverage, but the description adds extensive semantic value: it provides concrete examples for each subscription type (e.g., sec_8k with items, fred_series with series_id), details delivery channel constraints (e.g., webhook HMAC signing secret returned once), and clarifies requirements (e.g., phone must match verified account). This richly supplements 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 that the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes itself from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description provides extensive guidance on when to use the tool, including the required OAuth account and limitations (e.g., anonymous/BYO cannot persist subscriptions). It also explains delivery channels and their prerequisites. However, it does not explicitly contrast with sibling tools like 'recent_alerts' or 'ask_pipeworx' for alternative ways to get data.

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

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

Annotations already indicate non-destructive, read-only, idempotent. Description adds behavioral details: it returns example questions, tool shapes, and is the onboarding entry point. No contradiction with annotations.

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

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

Well-structured with alternative phrasings, purpose, categories, usage instructions. Slightly verbose with alternative phrasings but still concise relative to information density.

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 single optional parameter and no output schema, the description fully explains behavior, usage, and expected content. 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 has 100% coverage for the single optional 'topic' parameter. Description adds context by listing example topics and effect of omission, surpassing the baseline of 3.

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

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

The description states the tool returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings by specifying it's for when the user doesn't know Pipeworx's capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and advises calling with no arguments or passing a topic. Though it doesn't list when not to use, it provides clear context for appropriate use.

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

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

The description adds valuable context beyond annotations: ownership enforcement and that the row is deactivated (not deleted), confirming the destructiveHint=false and readOnlyHint=false 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 that are concise and front-loaded, with no wasted words. Every sentence adds useful information.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, side effects, and domain context completely.

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

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

With only one parameter and 100% schema description coverage, the schema already documents it well. The description doesn't add extra meaning beyond what the schema provides, so a 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). It distinguishes itself from sibling tools like subscribe and list_subscriptions.

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

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

It specifies ownership enforcement (only own subscriptions) and explains the deactivation behavior. While it lacks explicit alternatives, the context is clear enough for appropriate usage.

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 safety (readOnly, idempotent, openWorld, non-destructive). The description adds valuable behavioral nuance beyond annotations: the meaning of could_not_verify vs. unsupported, the routing paths, and the return structure. This is exactly the kind of context that helps an agent interpret results correctly, especially the warning that could_not_verify is not evidence.

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

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

The description is somewhat long but every sentence earns its place: user intents, use case, routing, return values, verdict semantics, and efficiency justification. It is front-loaded with examples and structured logically, with the important caller warning called out explicitly. 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?

Despite no output schema, the description fully explains the return value shape (verdict, value, citation, reasoning) and the two key failure modes. It covers routing for different claim types, parameter overrides, and the protocol around could_not_verify. For a tool of this complexity, this description is highly complete.

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

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

Schema descriptions cover 100% of parameters, but the description enriches the semantics significantly. It explains tolerance_pct as overriding the wording-implied tolerance, gives a concrete use case (hallucination detection with 1-2), and clarifies the default cap. Claim examples in the schema are reinforced. This adds real value beyond the structured schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with a verdict and evidence. It provides specific user phrasings ("Is it true that…") and distinguishes itself from sibling research tools by focusing on fact-checking with defined judgment categories. This is a specific verb+resource description with strong differentiation.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing rules for company-financial vs. other claims. It does not name specific alternative tools like ask_pipeworx_grounded or deep_research, but the context is clear enough to guide tool selection. A slightly more explicit exclusion or mention of alternatives would push to 5.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context: it's keyless/offline, detects country, normalizes to E.164, and checks length plausibility. It also clarifies what it does not do, which is beyond the annotations.

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

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

The description is concise at three sentences, with no redundant information. It front-loads the core purpose, then provides usage patterns, and finally lists exclusions. 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 the tool's simplicity (2 params, no output schema, clear annotations), the description fully covers input requirements, constraints, and limitations. It is complete for an agent to correctly select and use the tool without confusion from sibling tools.

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

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

Schema has 100% coverage with clear descriptions for both parameters. The description adds meaning by providing usage examples and explaining the relationship between 'phone' and 'country', clarifying the two allowed input formats (international vs national+country).

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 validates and parses phone numbers against E.164, distinguishing it from siblings like 'country_calling_codes' by specifying it checks plausibility and detects country. It also explicitly states what it does not do (carrier determination), differentiating it from other 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 provides explicit usage modes: international number without country, or national number with country code. It also tells when not to use the tool (for carrier or line-type determination), and suggests an alternative ('keyed HLR lookup').

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