Geonames

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value beyond these by detailing authentication requirements ('pass _apiKey to also probe Anthropic'), cost implications ('you pay Anthropic directly'), and return format ('per-model {score, confidence, signals, raw_response} + a combined view'). No contradictions.

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

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

Three sentences, each earning its place: first sentence states purpose and scoring, second covers model options and API key, third describes return format and use cases. 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?

All four parameters are adequately described, the return format is outlined, and the use cases are given. No output schema exists, but the description compensates by detailing the response structure. It's complete for a probing tool, though rate limits or freshness are not covered.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: the default model is Workers AI Llama-3.3-70b (free), the _apiKey is only needed if 'anthropic' is in models, and the context parameter helps disambiguate. It also explains cost considerations, which are not in the schema.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs'), clearly stating the output ('score visibility 0-100 per model'). It distinguishes from siblings like 'scan_competitor_ai_presence' by specifying the use case for AI-marketing audits, pre-launch brand checks, and competitive monitoring.

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

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

The description explains when to use the free default model vs. the paid Anthropic model with an API key, and notes that you pay Anthropic directly for those calls. It doesn't explicitly mention when to avoid this tool or compare it to siblings, but the context is clear enough for an AI agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it routes to 4,552 tools across 1160 sources, returns structured answers with stable pipeworx:// citation URIs, and operates on all tiers with one fast call. This goes beyond annotations.

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

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

The description is front-loaded with key guidance ('PREFER OVER WEB SEARCH') and uses examples. It is somewhat lengthy but each sentence provides useful information (domains, alternatives, examples). Could be slightly tightened but overall well-structured.

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

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

Given the high schema coverage, rich annotations, and no output schema, the description fully covers usage context, alternatives, examples, and behavioral traits. It is complete for an agent to decide when to use this tool and how to invoke it.

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

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

Schema coverage is 100%, so the schema already describes all six parameters (with aliases). The description adds value by explaining the 'question' parameter as natural language and provides examples. It also gives context that the tool accepts query, q, etc. as aliases, but this is largely captured in the schema. Baseline 3 with slight increment for the usage context.

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

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

The description clearly states the tool routes questions to a large set of sources for authoritative structured data. It lists specific domains like SEC filings, FDA drugs, etc., and contrasts with siblings (ask_pipeworx_grounded, deep_research). The verb 'route' and resource '4,552 tools' make the purpose 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?

Explicit guidance is provided: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It tells when to use alternatives: 'Step up only when needed' and names grounded and deep_research with specific contexts. It even gives example queries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. The description adds behavioral details: costs one extra LLM call, returns explicit refusal reasons (not_in_source, no_tool_match, etc.), and explains the extraction process. No contradiction with annotations.

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

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

The description is somewhat lengthy but well-structured with clear sections: purpose, mechanism, return format, usage guidance. Front-loaded with key information. Could be slightly more concise but each 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 complexity (grounded mode, high-stakes reads) and many siblings, the description fully covers mechanism, return format, refusal reasons, and usage context. No output schema, but output structure is described in text.

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

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

Schema coverage is 100% with all parameters being aliases for 'question' with adequate descriptions. The description does not add additional parameter semantics 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and explains the mechanism of routing to the right tool and extracting answer only from tool results. It distinguishes itself from sibling 'ask_pipeworx' by describing its safety guarantees.

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 when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with specific examples. Also advises preferring ask_pipeworx for casual lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating safe read operations. The description goes far beyond, detailing fan-out behavior, response shapes, resolver contract, parent event extractor, news fallback, safety mechanisms (low-confidence short-circuit, closed markets), wide-spread illiquidity, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is comprehensive but lengthy (multiple paragraphs). It front-loads the main purpose and then dives into detailed subsections. While every sentence adds value, the overall length may overwhelm. Structurally, it uses clear labeling (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) but could be more concise.

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

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

Given the tool's complexity (Polymarket research with parallel fan-out, multiple data sources, edge cases), the description is remarkably thorough. It covers input variations, detailed output shapes, error handling (low confidence, closed markets), cancellation risk, and fallback behavior. No output schema exists, so the description compensates fully.

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 each parameter is documented. The description adds significant value: explains what types of input market accepts (slug, URL, question text) with examples, clarifies depth options (quick vs thorough), and details include_raw with size implications (~20KB vs 50KB-500KB). This enriches the schema definitions.

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

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

Description starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question) and output (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_edges and polymarket_arbitrage, which have different purposes.

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

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

The description explicitly states usage: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides detailed fan-out examples but does not explicitly exclude when not to use it or mention alternative tools. Guidance is clear but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years (e.g., AAPL Sep), and that results are sorted by primary metric. No annotation contradictions.

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

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

The description is compact and front-loaded with examples. Every sentence adds value: it states the purpose, preferred usage, data sources, edge cases, and output. No wasted words, and structured to be quickly parsed by an agent.

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

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

Given no output schema, the description explains that it returns paired data with citation URIs. It covers behavior for both entity types and fiscal year handling. It omits mention of sorting direction (descending by primary metric implied) but is otherwise complete for a 2-parameter comparison tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches the 'values' parameter by explaining the expected format for companies (tickers/CIKs) and drugs (names), and clarifies what data each type retrieves. This adds meaning beyond the raw schema.

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

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

The description starts with example queries and clearly states it performs side-by-side comparison of 2–5 companies or drugs in a single parallel call. It specifies data pulled per type (financials from SEC/EDGAR; FDA/FAERS for drugs) and distinguishes from sequential lookups, making the purpose unmistakable.

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, and provides example phrases ('X vs Y', 'rank these companies'). It implies a maximum of 5 entities but does not explicitly state when to use alternatives like entity_profile for single entities. Still, guidance is strong.

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

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

Discloses internal behavior (decomposes into facets, parallel routing across 4,552 tools), output structure (findings packet with evidence, confidence, gaps array), and limitations (returns empty gaps for non-structured topics). Annotations confirm read-only, idempotent, and non-destructive; description adds latency (15-60s) and never-invented gap policy. No contradiction.

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

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

The description is lengthy but front-loaded with critical prerequisite (account). Every sentence adds value, covering purpose, mechanics, output, alternatives, and limitations. Could be slightly more concise but appropriate for a complex tool.

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

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

Given no output schema, the description fully explains return values (findings packet, gaps). Covers use cases, limitations, prerequisites, and latency. Provides complete context for an agent to understand what the tool does, returns, and when to choose it.

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

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

Schema coverage is 100%, both params are fully described in the schema. The description reinforces the schema's depth semantics (quick=3, standard=5, thorough=8) and question format but does not add significant new meaning beyond examples. 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 specifies the tool as 'grounded multi-source research across Pipeworx's 1160 structured data sources' and contrasts with sibling ask_pipeworx for single lookups and live news. It provides concrete examples of multi-part questions, making the purpose and scope 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?

Explicitly states when to use (broad/multi-part questions over structured data) and when not to (single lookup, breaking news). Names alternatives (ask_pipeworx) and prerequisites (account, paid plan for thorough depth). Guides agent decision-making effectively.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that results are ready to call directly, which is valuable behavioral context 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 a single, well-structured paragraph: it states purpose, lists example domains, describes the return value, and gives usage advice. Every sentence adds value without being verbose.

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

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

Given no output schema, the description adequately explains what is returned (tool names, descriptions, full schemas with examples) and that results are ready to call. It also addresses the query parameter's flexibility. No important details are missing for this discovery tool.

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

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

Schema description coverage is 100% with basic descriptions like 'Alias for query.' The main description adds meaning by providing example queries ('look up FDA drug approvals,' 'analyze housing market trends') and explaining that the query parameter accepts natural language. The `limit` parameter is well described in the schema. This adds value beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings by advising to 'Call this FIRST when you have many tools available and want to see the option set.'

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: when you need to 'browse, search, look up, or discover what tools exist.' It also advises to call this tool first when many tools are available, implying it's for exploration rather than direct answers.

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 as true, and destructiveHint as false. The description adds context beyond annotations, including data sources used (SEC, XBRL, USPTO, news, GLEIF), the USPTO API sunset soft-fail, and return value structure. This is valuable but the annotation baseline reduces the burden.

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

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

The description is a single paragraph that efficiently packs many details. It front-loads example queries and then systematically lists behavior and outputs. While not broken into sections, every sentence adds value and the length is appropriate for the tool's complexity.

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

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

Given no output schema, the description fully explains return values (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news, LEI). It covers input constraints, behavior (parallel fan-out), and limitations. No major gaps for a tool of this complexity.

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

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

Schema coverage is 100%, providing basic parameter descriptions. The description adds significant meaning: explains that type is limited to 'company', value can be ticker or zero-padded CIK, and explicitly states that names are not supported. This goes beyond the schema.

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

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

The description explicitly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides specific examples and distinguishes itself from sibling tools by advising to prefer this over chaining single-source lookups and noting that resolve_entity should be used for names.

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

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

The description gives clear when-to-use guidance (holistic view), when-not-to-use (names not supported), and alternatives (use resolve_entity). It also mentions the USPTO soft-failure and the parallel nature of the call.

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 and idempotentHint, indicating no side effects. The description adds that the tool returns place name, country, admin region, postal code, and coordinates, which is useful context. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the core functionality and examples. Every sentence adds value without redundancy or unnecessary detail.

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

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

Given the absence of an output schema, the description fully explains what the tool returns (place name, country, admin region, postal code, coordinates). It covers both usage modes and key parameters, making the tool easy to invoke correctly.

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

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

Schema coverage is 100% with each parameter having a description, but the description adds value by explaining the two usage modes and providing examples, which clarifies the relationship between parameters and how to use them together.

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 looks up postal/ZIP codes and places by each other, using two distinct modes with specific examples ('what city is ZIP 90210', 'postal codes for Paris'). This clearly distinguishes it from sibling tools like search_geonames or get_nearby, as it is specifically for postal code 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 guidance on when to use each parameter (postal_code vs place) and recommends providing a country for accuracy. It does not explicitly state when not to use this tool or name alternatives, but the purpose is clear enough that an agent can infer 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?

Description confirms destructive action (delete) consistent with destructiveHint=true. Adds context about clearing sensitive data, but does not elaborate on error behavior or idempotency beyond annotations. No contradictions.

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

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

Two sentences: first states purpose, second gives usage guidelines. 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?

For a simple one-parameter destructive tool with annotations, the description fully covers purpose, usage, and relationships to siblings. No gaps given 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 100% with parameter description 'Memory key to delete'. Description adds no further details about key format or constraints, but baseline is appropriate given schema 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?

Description clearly states 'Delete a previously stored memory by key', specifying the verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by mentioning pairing and implying deletion vs storage/retrieval.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall', implying alternative use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by explaining the process (fetches page, extracts title/description/key links, emits markdown) and output format, which goes beyond the annotations.

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

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

The description is three sentences: purpose, process, use cases. No redundant words, every sentence adds value. Well-structured and 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?

Despite no output schema, the description explains the output is a single text blob for site-root/llms.txt, which is sufficient. It also mentions the extraction of title/description/key links and the standard markdown format, making the behavior complete for an agent to understand and 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?

Input schema covers both parameters (url, max_links) with descriptions. The description does not add new semantic information beyond what the schema already provides (e.g., 'Full URL' and default/max for max_links are identical). With 100% schema coverage, baseline 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt', and the outcome for AI crawlers. This purpose is distinct from all sibling tools, which are unrelated to llms.txt generation.

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

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

The description lists three use cases (indexing a client's site, drafting for own project, auditing competitors), providing clear context for when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient for an agent to decide.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds no new behavioral traits beyond stating that results are sorted by distance. With annotations covering safety, the description's contribution is minimal, marking an adequate but not exceptional score.

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 with two sentences and an example. It is front-loaded with the core purpose, followed by a concrete illustration. Every sentence earns its place without redundancy or 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?

Given the presence of an output schema and high schema coverage, the description is adequately complete. It explains what the tool returns and provides a usage example. However, it could mention the default radius and maximum radius from the schema to improve completeness, but the lack of that detail is minor.

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

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

The input schema has 100% coverage with clear descriptions for all four parameters. The description includes an example but does not add meaning beyond the schema. The schema already explains parameter formats and defaults (e.g., radius default 10 km), so the description adds no additional semantic value.

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

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

The description clearly states the tool finds places near a given latitude/longitude and specifies it returns nearby cities, landmarks, and features sorted by distance. The verb 'find' and resource 'places' are specific, and the distinct focus on proximity distinguishes it from sibling tools like search_geonames.

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 a use case with an example (Paris) but does not explicitly state when to use this tool versus alternatives like search_geonames or find_postal_codes. No guidance is given on when not to use it or which sibling tools to prefer for different scenarios.

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

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

Annotations already declare readOnly, idempotent, and non-destructive traits. Description adds value by specifying exact output fields (timezone ID, offsets, local time, sunrise, sunset) and showing an example call. 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?

Extremely concise: two sentences plus an example. Every element is useful with no redundancy or irrelevant 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 simplicity (3 params, all required, output schema exists), description fully satisfies informational needs. Example clarifies usage, and return fields are explicitly listed.

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

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

Schema covers all parameters with descriptions. The description includes an example but adds no semantic detail beyond what the schema already provides for lat, lng, and _apiKey.

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 gets timezone info for lat/lng, lists specific return fields (timezone ID, offsets, local time, sunrise, sunset), and provides an example. It distinguishes itself from sibling tools like 'get_nearby' or 'search_geonames' which serve different purposes.

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 implicitly covers when to use (getting timezone info) but provides no explicit guidance on when not to use or alternatives. No exclusion criteria or context for selecting this over siblings.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds value by stating default behavior (active only) and the returned fields, complementing the annotations without contradiction.

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

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

Two efficient sentences: the first states purpose and return fields, the second gives usage guidance. No filler, 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 tool with one optional parameter, no output schema, and full annotations, the description is complete. It covers purpose, data shape, usage context, and default behavior.

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

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

Schema coverage is 100% for the single parameter 'include_inactive'. The description does not add new semantics beyond what the schema already 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 the verb ('List'), resource ('subscriptions'), and scope ('caller's active'). It also lists the specific fields returned, which distinguishes it 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?

The description provides explicit context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It lacks explicit 'when not to use' but is sufficient for a simple list 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 are minimal (no safety hints), but the description fully compensates by disclosing rate limits (5 per identifier per day), that it does not count against tool-call quota, and that feedback is read daily and affects roadmap. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the purpose. Every sentence adds value, though it is slightly verbose in listing use cases and could be tightened without losing clarity.

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

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

Despite having no output schema, the description provides all necessary information for correct invocation: parameter meanings, constraints, rate limiting, and usage context. 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 all parameters with 100% description coverage, so baseline is 3. The description adds value by explaining the enum options (bug, feature, etc.) and providing usage tips for the message field (be specific, 1-2 sentences, 2000 chars max).

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: sending feedback to Pipeworx about bugs, feature requests, data gaps, or praise. It is well-differentiated from sibling tools, which are primarily research and data retrieval tools.

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

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

Explicitly describes when to use each feedback type (bug, feature, etc.) and provides clear guidance to avoid pasting end-user prompts. Also mentions rate limits and that it is free, helping the agent decide when to invoke.

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

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

Annotations already indicate readOnly, idempotent, nondestructive. Description adds caching details (5min-1h), data source (CF analytics-engine), no PII, and output shape (pack, tool, count). No contradiction with annotations.

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

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

Description is well-structured: front-loaded with purpose, then bulleted use cases, then technical details. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers caching, data source, privacy, and use cases comprehensively. Annotations further support completeness.

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

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

Schema coverage is 100% and the schema description for 'window' already explains the meanings (shorter vs longer windows). The main description does not add new semantic information beyond the schema's parameter description.

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

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

The description clearly states it returns top tools, packs, and call volume, with specific verb 'returns' and resource 'top tools, top packs, and total call volume'. It distinguishes from siblings like discover_tools and ask_pipeworx by focusing on trending data.

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

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

Provides three explicit use cases (hot data sources, canonical choice verification, alignment check). Lacks explicit when-not-to-use or comparison with siblings, but use cases give clear context.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: describes scanning modes, similarity filters (Jaccard ≥0.30), partition filters (placeholders), fill check with book depth, and scenarios where trades should not be executed (realizable_edge_pp ≤ 0). 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 lengthy but well-structured: it opens with the core purpose, then details each mode, filters, and response. Every sentence adds necessary information for a complex tool. While some redundancy exists (e.g., repeating 'partition_check'), the structure aids comprehension.

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 response fields (opportunities[], partition_check, fill check) and edge cases (skipped_low_similarity, placeholders filter). All modes are covered: no args, event, topic. The tool's complexity is adequately addressed, making it actionable for an AI agent.

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

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

Schema coverage is 100% with descriptions for both event and topic. The description enriches these by explaining when to use each parameter, providing example values (e.g., 'fed-decision-may-2026'), and detailing the behavior of each mode (single-event vs cross-event scan, semantic anchor, partition filter). This adds significant value beyond the schema.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the exact method (monotonicity violations and partition-sum checks) and resource (Polymarket arbitrage opportunities), distinguishing it from sibling tools like polymarket_edges which focus on edge detection.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It explains recommended use cases and mentions an alternative tool (polymarket_fill_risk) for custom sizing. However, it does not explicitly compare with all siblings (e.g., polymarket_edges).

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

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

The description discloses extensive behavioral details beyond annotations: the three model families with their formulas and sources (e.g., lognormal barrier from FRED, GDELT article-volume ratio), the edge calculation (edge_pp_net, kelly_fraction), tradeable-edge knobs, response structure including diagnostics like _diagnostics, and limitations (Fed candidates excluded due to unreliable signal). Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, and the description aligns with these.

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

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

The description is detailed and front-loaded with the core purpose, but it is lengthy (multiple paragraphs). It explains the three segments in depth, which is necessary for understanding, but some sentences are dense (e.g., 'partition_overround on mutually-exclusive events; per-leg favorite-longshot bias correction with per-sport α'). While comprehensive, it could be more concise.

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

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

Given the tool's complexity (9 parameters, three segments, no output schema), the description is highly complete. It explains the response structure (by_segment, fed_candidates, _diagnostics), why segments might be empty, and caching behavior (1h at KV level). Despite the lack of an output schema, the description provides sufficient context for an agent to understand what the tool returns and how to interpret results.

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

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

Schema description coverage is 100%, so the input schema already documents all 9 parameters. The description adds some contextual value for parameters like max_spread_pp ('Set to 2 to require tight books') and min_partition_leg_kelly (explains why min_kelly doesn't filter partition arbs). However, most parameter descriptions are restated or similar to schema, not significantly enhancing 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 states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly identifies the use case 'what should I bet on today' and distinguishes itself through the three model segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). The verb 'scan' and resource 'opportunities' are clear, and no sibling tool overlaps exactly.

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 a clear use case and mentions that agents can discover opportunities without paging hundreds of markets. It implies the tool is for finding betting opportunities based on Pipeworx disagreement. However, it does not explicitly state when not to use it or contrast with alternatives like polymarket_arbitrage or polymarket_edge_tracker, which are related sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds significant behavioral context: data comes from daily snapshots written on cache-miss, decay computed from daily closes (not intraday), response structure with tracked/expired/snapshot_dates, and 60-day TTL. 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 front-loaded with the core purpose, then details response structure. It is somewhat lengthy but each sentence adds value. Could be slightly more concise, but still efficient.

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

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

Given no output schema, the description fully explains the return value (tracked, expired, snapshot_dates) and addresses limitations (60-day TTL, snapshot gaps, intraday vs. daily). A complete and transparent description for a complex tool.

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

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

Schema coverage is 100% with both parameters described. The description adds default values and clarifies 'window' as snapshot family. This is baseline 3; no further semantic enrichment beyond schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry. It uses specific verbs ('answers how long has this edge existed and is it shrinking?') and distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis.

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

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

The description explains the use case (distinguishing fresh vs. old edges) and mentions limits (60-day TTL, daily closes). However, it lacks explicit when-to-use or when-not-to-use guidance compared to alternatives, such as polymarket_edges.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it walks the order-book ladder, returns specific risk metrics (thin_legs, forced_directional_risk), and explains basket-mode sum logic. No contradictions with annotations.

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

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

The description is lengthy but well-structured with headings (REQUIRES one of, SINGLE-MARKET, BASKET) and each sentence adds value. It could be slightly more concise, but the density of information and clear organization justify a score of 4.

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

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

Despite lacking an output schema, the description details return values (e.g., top_of_book, slippage_pp, profit_usd, thin_legs) and explains verdict meanings. It covers error and risk scenarios (cannot_fill, partially filled baskets). However, it omits error conditions for invalid slugs or connectivity issues, leaving minor gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains how `size_usd` is interpreted for baskets (settlement notional), clarifies default side logic for baskets (auto), and describes the role of `market` vs `event` with usage context. This provides helpful additional semantics.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and specifies the outputs (top_of_book, vwap_fill_price, verdict, etc.), making its purpose unambiguous and distinct from sibling tools.

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

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

The description explicitly advises using this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above $500, and explains why (partial fills convert arb to directional risk). It also specifies requirements (one of `market` or `event`) and differentiates modes, providing strong guidance on when and why to use it.

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

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

Annotations (readOnlyHint true, idempotentHint true) already indicate safe, read-only behavior. Description adds extensive behavioral context: two modes, response structure (leg-by-leg prices, top_spreads_pp), and safety fields (compatibility_warning conditions, temporal_alignment, skipped counters). No contradictions with annotations.

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

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

Well-structured, front-loaded with purpose and modes. Each sentence adds meaningful information: response format, safety fields, and limitations. No redundancy or filler; dense but clear.

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

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

Despite lack of output schema, description thoroughly explains the response structure: leg-by-leg prices, matched spreads, top_spreads_pp, safety fields (compatibility_warning triggers, temporal_alignment). Covers edge cases (skipped_cross_type) and temporal constraints. Complete for a tool with 3 optional parameters.

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

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

Schema covers all 3 parameters (100% coverage). Description adds value by explaining the two modes: topic as a shortcut listing valid values, and explicit parameters with override behavior. Provides examples and real-world usage patterns beyond 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?

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes two modes (topic shortcuts vs explicit pairings) and explains what the spread represents. Sibling tools like polymarket_arbitrage focus on single-venue arbitrage, making this tool's unique purpose evident.

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 describes when to use (comparing prices across venues) and limitations (compatibility warnings, temporal alignment). Warns that pre-mapped topics often yield non-tradeable spreads. Lacks direct comparison to alternatives but provides sufficient context for appropriate invocation.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds important context: scoping, behavior when key omitted (listing), and pairing with siblings. 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?

Concise multi-sentence description, front-loaded with core functionality, then examples and scope. Every sentence is informative.

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

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

Tool has low complexity (1 optional param, no output schema). Description covers purpose, usage, scope, and relationships to siblings 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?

Schema coverage is 100%, so baseline 3. Description repeats param explanation from schema but doesn't add new semantic detail beyond schema description.

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

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

Clearly states the tool retrieves a value or lists keys, with specific verb-resource pairing. Distinguishes from siblings (remember, forget) by naming them directly.

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 describes when to use (to look up stored context) and mentions alternatives (remember, forget). Also explains scoping to identifier.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds key behavioral details: the mark_read parameter flags events as read, the feed is persisted, and polling is safe. This enriches the agent's understanding beyond annotations without contradiction.

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

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

The description is concise with each sentence adding meaningful information (purpose, return fields, filtering, mark_read behavior, alternative access). No redundant statements, though it could be slightly more compact.

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

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

For a read operation with 5 optional parameters and no output schema, the description covers key expectations: what is returned, filtering options, mark_read behavior, and alternative access. It lacks explicit mention of default ordering or pagination, but overall it is sufficient for effective use.

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

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

Schema coverage is 100% with basic descriptions. The description adds semantic value by explaining how mark_read affects future calls, providing an example for type filtering, and clarifying that since expects an ISO timestamp. This goes beyond what the schema alone offers.

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

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

Clearly states the tool pulls fired events from the subscription feed, specifying what each event carries (source, citation_uri, payload). The description is specific and distinguishes it from sibling tools like list_subscriptions by focusing on alerts from the feed.

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 context on filtering by type and since, explains the mark_read parameter effect, and notes that polling works fine. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly state when to avoid this tool in favor of siblings.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description reveals key behaviors: fan-out to multiple APIs, fallback from GDELT to GNews on rate limits or errors, USPTO soft-fail due to sun setting, and the return structure with grouped changes and citation URIs. This fully informs the agent about side effects and dependencies.

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 somewhat lengthy. It is front-loaded with example queries, which is helpful. However, there is some redundancy (e.g., explaining `since` format twice) that could be tightened. Still, every sentence contributes to understanding.

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 the absence of an output schema, the description covers the return structure (array of changes grouped by source, total_changes count, citation URIs). It fully addresses input parameters, behavioral details, and the intended use case, making it complete for agent selection and invocation.

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

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

The input schema already describes all three parameters with 100% coverage. The description adds significant value by explaining the `since` parameter format in detail (ISO date vs relative shorthand like '7d', '30d', '3m', '1y') and clarifying that `value` accepts tickers or CIK numbers. This exceeds what the schema alone provides.

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

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

The description clearly states the tool's purpose: providing a change feed for a company over a specified window. It uses specific verbs like 'fans out' and lists data sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes the tool from the sibling 'entity_profile' by specifying when to use each.

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

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

The description explicitly tells when to use this tool (e.g., 'what's new with X' queries) and provides a direct alternative: 'Use entity_profile instead when you want the static profile'. This gives clear guidance on tool selection.

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

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

Annotations already indicate idempotentHint=true and non-destructive. Description adds valuable behavioral details: persistence differences between authenticated and anonymous sessions, and scope by identifier. 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?

Three sentences, no wasted words. First sentence states purpose, second gives usage guidance, third covers persistence and scope. Perfectly front-loaded and 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?

No output schema exists, but description fully explains what the tool does, when to use it, how it behaves, and what to pair it with. For a simple write tool with 2 parameters, this is complete.

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

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

Schema covers 100% of parameters with good descriptions. The description adds contextual meaning beyond the schema, explaining the key-value purpose and providing example keys. Baseline 3 is exceeded.

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 ('save data') and identifies the resource ('memory key-value pair'), with concrete examples ('ticker, address, preference'). It clearly 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?

Explicitly states when to use ('when you discover something worth carrying forward'), provides context ('so you don't have to look it up again'), and names alternatives ('recall' to retrieve, 'forget' to delete). Also covers scope and persistence differences.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: internal cascading through multiple endpoints, replacing 2-3 manual lookups, and auto-disambiguation. 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 concise (~4-5 lines), front-loaded with examples and purpose. Every sentence is informative with no redundancy.

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

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

Given the tool's complexity (two entity types, multiple input/output formats, internal cascading), the description is fully complete. It details return fields, input formats, and notes expected behavior 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?

Both parameters are described in schema (100% coverage). Description adds meaning: explains valid input formats per type (ticker, CIK, name for company; brand or generic for drug) and auto-disambiguation, going beyond schema descriptions.

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

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

The description clearly specifies the tool resolves names to canonical identifiers, provides query examples, and details returned fields per type. It distinguishes from sibling tools like compare_entities and entity_profile.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID.' Provides clear use case guidance, though does not explicitly mention alternatives or when not to use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns score/confidence/signal density. No contradiction with annotations.

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

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

Description is two sentences, front-loaded with core purpose, and no wasted words. It could be slightly more structured (e.g., list outputs), but remains efficient and clear.

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

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

Despite having no output schema, the description covers the tool's function, methodology (calling ai_visibility_check), and the returned data elements (score, confidence, signal density). It is sufficient for an agent to understand usage and results.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond schema: entities first entry treated as subject, rest as competitors; explains the role of models and _apiKey. This extra context justifies a 4.

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

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

The title and description clearly state the tool compares AI visibility across multiple entities. It specifies actions (probes, ranks, surfaces) and resources (entities, scores), distinguishing it from siblings like 'ai_visibility_check' which handles single entities.

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

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

The description explicitly states the use case (competitive AI-marketing audits) with an example question. It implies when to use this tool over 'ai_visibility_check' (multiple entities), but lacks explicit when-not or alternative references.

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 two services, partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, sources_failed listed. Annotations already show readOnly, idempotent, not destructive.

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

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

One dense paragraph, but efficient. Somewhat long but each sentence adds value. Could be slightly more structured (e.g., bullet lists), but still 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?

Given 2 parameters, rich annotations, no output schema, description explains return values (summary block, details, links, alternatives) and failure behavior. Fully adequate for agent 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 description coverage is 100%, so baseline 3. Description adds minimal extra: explains default for version and that scoped packages accepted. Adequate but not beyond expectation.

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's a composite check for adding npm packages, covering multiple aspects (license, advisories, bundle size, etc.). Distinguishes from sibling tools which are unrelated.

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

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

Explicitly says when to use: 'when an agent asks is X safe / popular / small' and provides ecosystem constraints (NPM only, fallback info).

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 that the tool returns coordinates, country, population, and feature type, which is useful behavioral context 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 plus an example. The purpose is front-loaded, followed by an example and sibling guidance. Every part is necessary and there is no fluff.

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

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

Given full schema coverage, rich annotations, and existence of output schema, the description is complete. It mentions return values (coordinates, country, population, feature type) and provides usage 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 schema already documents all parameters. The description only provides a usage example ('search_geonames("Paris", "FR")') which doesn't add 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?

The description clearly states the tool searches for places by name, with specific examples of resource types (cities, landmarks, regions). It distinguishes itself from sibling tool 'get_nearby' by explicitly mentioning it as an alternative.

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

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

Provides explicit guidance: 'Use get_nearby to find places near a known location.' This tells the agent when to use this tool versus an alternative. The example also clarifies typical 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?

Discloses technical details (BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag) and that passages include character offsets. Annotations already provide readOnlyHint and idempotentHint; description adds significant context beyond them.

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

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

Single paragraph with front-loaded main purpose, then usage guidance, then technical details. Efficient but could be slightly shortened; still well-structured.

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

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

Given no output schema, description explains return format (top-N passages with offsets and similarity scores), covers edge cases (truncation), and provides technical backend details. Complete for a tool with 3 params.

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

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

Schema covers all parameters with descriptions; the description adds context by explaining query as 'natural-language query' with examples and mentioning text as 'document text'. Enhances 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?

The description clearly states the tool performs semantic search inside a fetched record, specifying the action 'search' and the resource 'text' with examples. It distinguishes from siblings by mentioning its pair with ask_pipeworx_grounded and use case for large records.

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

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

Explicitly says when to use ('record too big to cram into the prompt') and pairs with ask_pipeworx_grounded, providing clear context. Excludes small records implicitly; lacks explicit alternatives for small texts.

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

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

The description adds significant behavioral context beyond annotations: it mentions that subscriptions require an account, details delivery channels with limitations (10/day SMS cap, webhook auto-disable after 10 failures), and the one-time webhook secret. These are critical behavioral traits not captured in annotations, fully leveraging the description's role.

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 well-structured. It front-loads the main purpose and then expands on types and delivery. While it could be slightly more concise (e.g., combining some details), every sentence adds necessary information. No waste.

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

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

For a tool with 3 parameters, nested objects, and no output schema, the description covers prerequisites, supported types with parameter examples, delivery options, constraints (10/day SMS, webhook auto-disable), and the always-on feed. It is complete enough for an AI agent to correctly invoke the 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 adds meaningful context beyond the schema by providing detailed examples for each type (e.g., sec_8k items, polymarket_edge topic) and elaborates on delivery channels with validation requirements (phone verification, 10/day cap). This adds value beyond the schema's own 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 verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It also distinguishes itself from sibling tools like list_subscriptions and unsubscribe by specifying it creates new subscriptions. The return of a subscription id is mentioned, adding clarity.

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 notes the prerequisite of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It lists supported types with examples, providing clear context. However, it lacks explicit guidance on when NOT to use this tool or alternatives within the sibling set, though the context is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns example questions with live tool calls, which is behavioral context beyond annotations. It does not disclose rate limits or performance, but given the safety profile, this is adequate.

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

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

The description is detailed but not overly verbose; it front-loads the purpose and usage guidelines. It could be slightly more concise, but it is well-structured with clear sections (alternatives, parameter usage).

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

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

Given the tool's role as an onboarding entry point with 31 sibling tools, the description fully covers what it does, when to use it, how to call it (no args or with topic), and what output to expect (category-bucketed examples with tool shapes). No output schema exists, but the description adequately describes the return value.

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 description for the 'topic' parameter. The description further elaborates on the topic values ('finance', 'pharma', etc.) and explains that omitting it gives a cross-category spread, adding meaning beyond the schema.

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

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

The description uses specific verbs like 'Returns category-bucketed example questions' and clearly states the resource (onboarding entry point for Pipeworx). It distinguishes from sibling tools like 'ask_pipeworx' and 'discover_tools' by positioning itself as the first tool to use when unfamiliar.

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 when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also implies alternatives by referencing other tools (ask_pipeworx, entity_profile, etc.) as things to learn about.

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

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

Beyond annotations, description clarifies deactivation (not deletion) and historical event persistence. Aligns with readOnlyHint=false and destructiveHint=false. Adds ownership enforcement 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?

Two concise sentences, front-loaded with purpose, then ownership and behavioral detail. No unnecessary words.

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

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

Complete for a simple one-param tool: covers action, constraint, and effect on data. Lacks explicit mention of return value but that is often implied.

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 parameter fully (id is subscription uuid). Description mentions 'by id' but adds no extra detail beyond schema description. Baseline 3 for 100% coverage.

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

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

Clearly states it cancels a subscription by id, distinguishing it from subscribe and list_subscriptions. Verb 'cancel' and resource 'subscription' are specific.

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

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

Provides ownership constraint ('you can only cancel your own subscriptions') and notes that historical events remain accessible via recent_alerts. Does not explicitly contrast with subscribe (to create) or list_subscriptions (to view).

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by detailing return values (verdict, citation) and noting it replaces 4-6 sequential calls, providing behavioral context 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 efficiently written, front-loading the purpose and usage. Each sentence adds meaningful information without redundancy.

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

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

Despite having no output schema, the description clearly explains what the tool returns (verdict, extracted form, actual value, citation, percent delta). It covers domain, usage, and structure completely for a single-parameter tool.

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

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

Schema coverage is 100% with one parameter. The description provides examples of claim values, enhancing understanding beyond the schema's description.

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

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

The description states the tool verifies natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. It gives example queries and return types, clearly separating it from sibling tools like deep_research or bet_research.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims) but does not list when not to use or alternative tools.

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