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?

Beyond readOnlyHint and idempotentHint, the description discloses that an LLM routes the prompt, that the tool may occasionally pick the wrong tool, and that it is a general-purpose router rather than a single data source. It also tells the agent it will fill arguments and return stable pipeworx:// citation URIs, which sets accurate expectations. No annotation 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 front-loaded with the most important instruction, 'PREFER OVER WEB SEARCH', followed by domains, examples, and alternatives. However, it is verbose and includes a malformed transition and minor copy issues, so it could be tightened without losing content.

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

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

For a complex open-ended router with no output schema, the description covers input type, domain scope, trigger phrases, routing behavior, citation-URI return format, and sibling fallback guidance. An agent has enough information to decide when to use it and what to expect back.

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

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

Schema description coverage is 100% and every parameter is already documented as a natural-language question or an alias for it. The description adds examples and trigger phrasing but no new parameter-level semantics, so the schema carries the burden and a baseline of 3 is appropriate.

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

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

The description identifies a concrete routing/answering behavior: it takes a natural-language factual question, routes it to one of 5,798 tools across 1,517 verified sources, and returns a structured answer with citation URIs. It also positions itself against web search and distinguishes itself from ask_pipeworx_grounded and ask_pipeworx_beta.

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 'PREFER OVER WEB SEARCH', lists trigger phrases like 'look up' and 'current', gives concrete examples, and says 'START HERE for most questions'. It names alternatives and their conditions: ask_pipeworx_grounded for deterministic/direct queries, ask_pipeworx_beta for different or unreleased behavior, deep_research for broad multi-part fan-out, and OOTW for multi-source current news.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing that candidate routing improvements are live only when under test, that no candidate is currently active, and that the tool currently behaves identically to ask_pipeworx. It also clarifies that this is a full working router rather than a fallback or stub, providing 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 each sentence adds value: scoping, current active state, usage instruction, comparison purpose, and operational reassurance. The key beta-versus-stable distinction is front-loaded, and there is no filler.

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

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

For a complex universal router with no output schema, the description provides strong context: identical scope, same response shape, current experimental status, and full functionality. It relies on ask_pipeworx for the exact response shape, which is acceptable given the sibling relationship, but a direct statement of the response format would make it fully self-contained.

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

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

Schema description coverage is 100%, with aliases like q, text, input, query, and prompt clearly documented. The description adds only the phrase 'same arguments as ask_pipeworx,' which does not meaningfully extend the parameter semantics beyond what the schema already provides.

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

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

The description clearly identifies this as the beta version of ask_pipeworx with the same universal routing scope: same 5,798 tools, same arguments, same response shape. It differentiates itself from the stable ask_pipeworx by the experimental routing candidate, making the tool's purpose immediately distinguishable from siblings.

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 to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router for merge decisions. However, it does not explicitly state when to prefer the stable ask_pipeworx or the other sibling variants, leaving some selection nuance 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?

The description adds significant behavior beyond the annotations: it discloses that the answer is extracted only from the tool result, that refusals can occur, and the exact refusal reasons. It also flags the extra LLM call cost. These details give the agent an accurate mental model of the tool's behavior without contradicting the readOnly/idempotent/openWorld 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 dense, information-rich sentences. The purpose is front-loaded, the return contract is specified precisely, and the usage tradeoff is given at the end. No filler, no repetition of schema or annotations — 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?

Even though there is no output schema, the description fully specifies the success return object and the refusal object with all refusal_reason values. Combined with the explicit usage guidance and cost tradeoff, an agent has everything needed to decide when to call it and what to expect back.

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

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

The input schema is fully documented with 100% coverage: one logical question parameter with five aliases, each described. The main description does not add parameter-level semantics beyond explaining that the question is routed across sources and used to fill arguments. That is adequate but not above the baseline given the schema's completeness.

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

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

The description opens with a precise, specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It goes on to explain the exact mechanism — picking a tool, fetching data, and extracting only from the tool result — and explicitly contrasts itself with ask_pipeworx, making its identity 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 states clear when-to-use conditions: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides an explicit alternative and tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is exemplary routing guidance.

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

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

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

Discloses a great deal beyond the annotations: account/pricing requirements, the non-open-web nature, parallel tool routing, findings packet structure, explicit gaps[] behavior, contradictions[] for standard/thorough, citation_uri fetchability guarantees, semantic excerpting, and expected latency. This adds rich behavioral context on top of readOnlyHint, openWorldHint, and idempotentHint.

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

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

The description is dense and front-loaded with critical account and alternative-tool info, but it contains a duplicated sentence ('For a single lookup use ask_pipeworx instead.') and some run-on, artifact-heavy phrasing. The length is mostly justified by the tool's complexity, but the redundancy and messy punctuation prevent a higher score.

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?

Because there is no output schema, the description correctly carries the burden of explaining return values, and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citation_uri, gaps[], contradictions[], and excerpting behavior. It also covers auth, pricing, latency, and alternatives, making the tool fully callable without additional context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates or contextualizes the depth semantics already present in the schema, such as paid thorough mode and hop behavior. It adds tool-level context like latency, but little per-parameter meaning beyond what the schema already provides.

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

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

States a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources, decomposing questions into facets and routing them in parallel. It also explicitly distinguishes itself from open-web search and from ask_pipeworx, making its identity clear.

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

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

Gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and clearly directs the agent to use ask_pipeworx when the user is not signed in or when the task is a single lookup. This is strong alternative routing with concrete conditions.

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 already establish the safe read-only/idempotent profile, and the description adds substantial behavior beyond that: parallel fan-out across sources, USPTO patents 'soft-fails until reactivated', expected-empty FDA sections for small-molecule/generic companies, the GDELT→GNews fallback, and the meaning of sources_used/sources_failed ('an empty section is a real no-data, not a bug'). It also discloses the private-company failure mode (resolved:false with notes, not a bare error), all of which prevents an agent from misinterpreting legitimate results.

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?

Information-dense and front-loaded: the intent-matching phrases and core purpose lead, and every subsequent clause (patent soft-fail, FDA expectation, no-data-not-bug semantics) prevents a real agent error — there is no filler. Deduction for structure: it is one long unbroken paragraph with no paragraph breaks, which hurts scannability compared with grouping the source list, return values, and edge cases into short sections.

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

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

For a complex multi-source tool with no output schema and two required parameters, the description carries the full interpretive burden, and it largely succeeds. It enumerates the major return sections (cik, company_name, resolved_from/resolved_to, up to 5 recent_filings with pipeworx:// URIs, LATEST 10-K fundamentals), per-source quirks, and the sources_used/sources_failed interpretation. An agent can invoke this tool and correctly interpret sparse or empty results without guessing.

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 both parameter descriptions are already thorough, so the baseline is 3. The description adds value on top by spelling out the behavioral consequences of value: names resolve via SEC EDGAR, resolved_from/resolved_to appear in the output when a name was passed, and an unresolvable private company yields resolved:false with an explicit notes line. These additions are genuinely beyond the schema, though modest.

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

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

States a specific function — 'full cross-source profile of a US public company in ONE parallel call' — with clear verbs (profile/brief/research) and a concrete resource, plus a battery of triggering query examples for intent matching. The 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' line and the sibling set (compare_entities, resolve_entity) make it easy to tell this tool apart without opening schemas.

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

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

Gives explicit when-to-use guidance: 'ALWAYS PREFER ... when the user asks for a holistic view', reinforced by the trigger-phrase list. The alternative class is named ('single-pack SEC/XBRL/news lookups') rather than specific sibling tools, and there is no explicit when-not-to-use statement, so the routing is strong but leaves the exclusion side implied.

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

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

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

This is the strongest dimension: beyond the readOnly/idempotent annotations, it discloses that Kalshi fees are not modeled and spreads are gross not net, that compatibility warnings can be non-empty even when pairs exist, that null temporal_alignment means 'could not compute' rather than aligned, and that unclassified legs are never paired. The explanation of compatibility codes and matched-pair flags adds substantial operational safety 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 long and dense, but nearly every sentence earns its place by adding an operational caveat or mode-selection fact. It is somewhat wall-of-text and could benefit from clearer structuring, but it contains minimal filler.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does so thoroughly: it enumerates leg-by-leg prices, spready spreads, compatibility codes, temporal_alignment semantics, fee disclosures, skipped-leg counters, and low-confidence pairs. An agent has enough context to call it correctly and interpret its output safely.

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 fully described in the schema, so the baseline is 3. The description elevates this by explaining that `topic` auto-fetches a matching event on each venue, that explicit parameters override the mapped side, and that both modes invoke the same token-overlap matcher. It adds useful selection context but does not go far beyond schema-level semantics.

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

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

The description clearly identifies the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question, and it explains the two operating modes. It is highly specific and informative, but it does not explicitly differentiate itself from closely related sibling tools such as polymarket_arbitrage.

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

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

The description gives concrete when-to-use guidance by distinguishing `topic` mode for pre-mapped macro shortcuts from explicit ticker/slug mode for custom pairings, and notes that both modes run the same matcher. It also warns that many pre-mapped topics currently return compatibility warnings, but it does not state when to prefer an alternative sibling tool.

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

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

Annotations already provide readOnlyHint, idempotentHint, 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?

Beyond the readOnly/idempotent annotations, the description discloses internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, a figi_candidates fallback when multiple instruments match, an explicit 'unresolved' field rather than silent omission, and a pipeworx citation for drug lookups. This is rich behavioral context that annotations alone do not provide.

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

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

The description is long and dense, but nearly every sentence earns its place given the tool's complexity and dual entity types. The opening examples are somewhat repetitive, yet they quickly convey intent. The structure moves from purpose to supported types to degradation behavior, which 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?

With no output schema, the description carries the burden of explaining return behavior, and it does: returned identifiers, figi_candidates, unresolved results, RxCUI with citation, and graceful degradation. It also covers all input modes and edge cases like non-US issuers and non-equity instruments. This is complete enough for an agent to select and invoke 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%, but the description adds substantial practical meaning: accepted value formats (ticker, CIK, ISIN, company name; brand or generic drug name), concrete examples, and an important caveat to pass the entity name only and not the full noun phrase for bonds. This goes well beyond the schema's generic property descriptions.

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

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

The description opens with concrete user queries then states a precise purpose: resolve a user-spoken NAME to canonical/official identifiers other tools require as input. It also lists supported entity types (company, drug) and the specific identifier systems used (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), making it distinct from siblings like entity_profile or compare_entities.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which gives a clear trigger condition. It does not explicitly contrast with alternatives such as entity_profile or compare_entities, but the resolver-vs-profile distinction is strongly implied by the identifier-focused wording and examples.

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.