What3words

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe and idempotent. The description adds behavioral details: scoring range (0-100), per-model return fields (score, confidence, signals, raw_response), combined view, and default model. 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 three sentences, front-loaded with purpose, then provides key usage details. Every sentence adds information without redundancy or wordiness.

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 specifies the return format (per-model {score, confidence, signals, raw_response} + combined view). All four parameters are explained with clear context. The tool's purpose and behavior are fully described for a probing/auditing 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%, so baseline is 3. The description adds value beyond schema by explaining the default model behavior (Workers AI free) and the role of `_apiKey` (BYO key for Anthropic). Examples in entity description help disambiguate input.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses specific verbs ('probe', 'score'), identifies the resource (LLMs), and distinguishes from sibling tools like 'ask_pipeworx' and 'entity_profile' by focusing on multi-model visibility scoring.

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

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

The description provides explicit guidance on when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how to configure (default model vs Anthropic with API key). It does not explicitly mention when not to use or name alternatives, but the context signals and sibling list imply distinct 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. The description adds valuable context: routes to 5,008 tools, returns structured answers with citation URIs, works on all tiers. 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 relatively long but well-structured with front-loaded key guidance and bold highlighting. Every sentence adds value, though some repetition of domains could be slightly tightened. Overall, effective use of space.

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 is highly complete: explains what kind of answers to expect (structured with citations), coverage (5,008 tools), and provides many examples. It also clarifies limitations by pointing to alternative tools when needed.

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

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

Schema coverage is 100% with 6 alias parameters for 'question'. The description adds value by providing extensive examples and clarifying that it accepts natural language queries, though it does not add new parameter-level details 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 it answers factual questions using structured data from many sources, explicitly distinguishing itself from web search and sibling tools like ask_pipeworx_grounded and deep_research. It lists specific domains and example queries.

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

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

The description provides explicit when-to-use guidance (e.g., 'PREFER OVER WEB SEARCH', 'START HERE for most questions', examples) and when-not-to-use (step up to grounded or deep research for specific needs). It also addresses breaking news routing.

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, etc.) are consistent with description. Description adds value by disclosing the beta nature and the source-preference ranking behavior. It does not contradict annotations; the tool is read-only as per annotations and description does not claim mutation.

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 and well-structured. It first establishes identity (beta, identical router), then explains the specific improvement, and finally gives usage guidance. 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?

Given the complexity (router with thousands of tools) and the presence of annotations (readOnly, openWorld, idempotent), the description sufficiently explains the tool's behavior and usage. It lacks explicit return shape, but annotations and context imply a text response. Overall, complete enough for correct agent invocation.

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

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

Schema coverage is 100% with aliases described. The description adds meaning beyond schema by explaining that the question is routed through the universal router, providing context that the input is a natural language request. This elevates from baseline 3.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with 5,008 tools. It explains the specific routing improvement (source-preference ranking) and distinguishes from the stable ask_pipeworx sibling by noting it is the experimental edge.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against stable router. It also states 'Falls back to nothing — this IS a full working router'. This provides clear context for when to use it, though it doesn't explicitly exclude sibling tools like ask_pipeworx_grounded.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds return format (answer, evidence, confidence, etc.), refusal reasons, and the extra LLM call. 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 fairly lengthy but efficient; front-loads key info (hallucination-resistant, high-stakes). Structured with return format and refusal reasons. Some redundancy but overall well-organized.

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

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

Given 6 params, 35 siblings, and no output schema, the description is very complete: explains behavior, return values, refusal scenarios, cost tradeoff, and when to use vs alternatives.

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 aliases for question. Description only repeats alias list; adds no extra meaning beyond schema. Baseline 3 as per guidelines.

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, differentiates from ask_pipeworx (casual lookups), and explains it extracts answers only from tool results.

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 (high-stakes, factual scenarios) and when not to (prefer ask_pipeworx for casual lookups). Mentions cost tradeoff and lists refusal reasons.

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 behavior. The description adds that results are ranked and can be biased by focus point, providing useful 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 efficient sentences, front-loaded with the core purpose and a key option. Every word earns its place.

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

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

With an output schema present, description does not need return details. It covers the input and the main functionality, though could briefly mention other parameters like country and n_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%, so parameters are well-documented. The description adds minimal extra meaning beyond summarizing the input type and optional focus point.

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

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

The description clearly states the tool's function: taking a partial/mistyped 3-word input and returning ranked suggestions, with optional focus point biasing. This distinguishes it from siblings like 'words_to_coords' and 'suggest_questions'.

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

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

The description implies usage for autocomplete scenarios but does not explicitly state when to use or avoid this tool. No alternatives or exclusions are mentioned.

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

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

The description goes far beyond annotations (readOnlyHint: true, idempotentHint: true) by detailing fan-out patterns, safety short-circuits, resolution-rule risk, and response shapes. It also explains edge cases like closed markets and GDELT 429s. 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-organized with capitalized section headers. Every sentence adds value, covering classification, fan-out examples, response shapes, and safety mechanisms. While not concise, it is efficient for the complexity of the 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 the tool's complexity (classification, fan-out, multiple sources, safety, resolution rules), the description is exceptionally complete. It covers input, output, edge cases, and even fallback behavior. No output schema exists, but the description sufficiently explains return values.

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

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

All three parameters have schema descriptions, and the tool description adds rich context: examples for market_input, the quick/thorough distinction for depth, and the size implications for include_raw. This fully compensates for any schema limitations.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_edges and polymarket_arbitrage, 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?

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on inspecting fields like market_match_confidence before trusting analysis. While it doesn't explicitly state when not to use it, the context is clear.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds valuable behavioral details: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and citation URI inclusion. No contradictions.

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

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

Description is detailed but efficient, front-loaded with trigger phrases. It covers multiple aspects without excessive verbosity, though it could be slightly shorter.

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 complexity (two entity types, multiple data sources, sorting, citations), the description covers key aspects. No output schema, but it mentions return format. Missing details on error handling or response size limits, but adequate for most scenarios.

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. Description adds meaning: explains 'type' entity-specific data pulls, 'values' format (tickers vs names), and min/max items. It goes beyond schema by describing result sorting and data handling.

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 side-by-side comparison of 2-5 companies or drugs in a single call, with specific trigger phrases like 'X vs Y'. It distinguishes from sibling tools like 'entity_profile' by emphasizing parallel lookups over sequential ones.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups', providing clear guidance on when to use. However, it does not mention scenarios where this tool should not be used or alternatives beyond comparing entities.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds minimal behavioral context (default language, conversion nature) but does not detail errors, rate limits, or the quality of results. Consistent with annotations.

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

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

Two short sentences, front-loaded with the core purpose. No redundant information; every word adds value.

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

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

Given the tool's simplicity, annotations, and the presence of an output schema, the description is adequate. It covers the primary use case and language customization. No missing critical details for a read-only, idempotent conversion tool.

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

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

Schema coverage is 100% and already documents parameters. The description adds slight value by clarifying the language parameter default and usage ('Defaults to English; pass a 2-letter language code'), but does not enhance latitude/longitude 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 'Convert a lat/lon to a what3words 3-word address', specifying the verb, resource, and output. It also distinguishes itself from the sibling tool 'words_to_coords' (reverse operation) and notes language customization.

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

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

The description provides context on default language and how to customize it ('pass a 2-letter language code'). It implies usage for any lat/lon conversion but does not explicitly state when not to use or compare with alternatives beyond the sibling list.

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 idempotent and read-only. Description adds: returns gaps[], contradictions[], hop field, citation URIs, semantic excerpting, expected time (15-90s). 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?

Long but every sentence adds value. Front-loaded with required account info. Could break into clearer sections but still highly 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?

Covers all important aspects: account requirement, input schema semantics, execution process (decomposition, parallel routing), return packet contents, depth behaviors, timing, and distinctions from siblings. No output schema but return format is well-described.

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

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

Schema covers 100% with descriptions. Description adds detail: depth levels explained (quick=3 facets, standard=5 with gap recovery, thorough=8 with leads chase), and question param is described as accepting broad/multi-part natural language.

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 performs grounded multi-source research across structured data sources, decomposes questions into facets, and returns a findings packet. Distinguishes from ask_pipeworx (single lookup, live news).

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 an account is required (free sign-up, paid for thorough depth), recommends ask_pipeworx if not signed in or for breaking news. Provides guidance on when to use each depth level.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail beyond annotations: it returns top-N most relevant tools with names, descriptions, and full input schemas with curated examples, ready to call directly. No contradictions.

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

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

The description is concise (5 sentences) and well-structured, front-loading the purpose and then listing examples and usage guidance. Every sentence adds value with no wasted words.

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

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

Given the tool's meta-nature and many sibling tools, the description is complete: it explains what the tool does, when to use it, what it returns (including full schemas with examples), and how results are ready to call directly. The lack of an output schema is acceptable as the description covers the return structure.

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

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

Schema coverage is 100% with detailed descriptions for all parameters including aliases. The description reinforces the usage of natural language queries but does not add new meaning beyond what the schema already provides. 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's purpose: to find tools by describing data or task, listing many domains. It distinguishes itself from sibling tools by being a meta-tool for discovery, and it specifies that it returns top-N tools with schemas, ready to call 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?

The description explicitly guides when to use: when you need to browse, search, look up, or discover tools, and suggests calling it FIRST when many tools are available. It provides clear context but does not include explicit when-not 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 declare readOnly, openWorld, idempotent, non-destructive. Description adds detailed behavior: fans out across SEC, XBRL, USPTO, news, GLEIF; returns specific data fields; notes soft-fail for patents; mentions fallback mechanisms. 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?

Well-structured with examples first, then purpose, then return details. Slightly verbose but all content is useful and earns its place. Could be tightened slightly 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?

Without output schema, description fully explains return fields (CIK, filings, fundamentals, patents, news, LEI) and handles edge cases (soft-fail, name restriction). Complete for a profile tool.

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

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

Schema coverage is 100%, and description adds meaning by explaining type is only 'company', value is ticker or zero-padded CIK, and clarifying that names are not supported—beyond what schema provides.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' with specific examples of user queries. It distinguishes from siblings like resolve_entity by noting that names are not supported.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and warns that names should be resolved first via resolve_entity. Provides clear when-to and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description confirms deletion but adds no new behavioral details beyond the usage reasons, which are more about context than behavior.

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

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

The description is two sentences, front-loaded with the action, then usage guidelines. Every sentence adds value, with no wasted words.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, usage scenarios, and related tools. It is sufficient but could optionally mention 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 description already covers the key parameter ('Memory key to delete'), and description coverage is 100%. The description reinforces but does not add new 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 deletes a previously stored memory by key, using a specific verb and resource. It distinguishes from siblings like remember and recall by indicating this is the deletion counterpart.

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 lists when to use: when context is stale, task is done, or to clear sensitive data. It also recommends pairing with remember and recall, providing clear usage context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds behavioral context like fetching the page, extracting data, and emitting standard markdown, which informs the agent about potential latency and output format.

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

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

Front-loaded with purpose, concise enough at four sentences. Could trim some redundant phrases but overall well-structured 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?

Given only two parameters and no output schema, the description fully explains input, process, and output (a text blob ready to drop). No missing information for agent to select and invoke.

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 full descriptions. Description adds minimal extra context (e.g., 'or a specific landing page' for url) but does not enhance understanding beyond schema defaults.

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 generates an llms.txt file for any URL for AI crawlers. Distinguishes from siblings like scan_competitor_ai_presence and ai_visibility_check by focusing on file generation.

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

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

Provides three specific use cases: indexing client site, drafting for own project, auditing competitor. However, does not explicitly mention when not to use or suggest alternative tools from sibling list.

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, so the safety profile is well-covered. The description adds that the result includes code and name for each language, but does not disclose other behavioral traits like whether the list is static or dynamic, or any rate limits. Given the rich annotations, the description provides marginal additional context.

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

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

The description is a single, concise sentence that is front-loaded with the purpose. Every word is necessary, and there is no 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 tool has no parameters, a rich set of annotations (readOnly, idempotent, openWorld), an output schema (not shown but exists), and a clear description of the return content (code + name), the description is complete enough for an agent to understand and use the tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed since the schema is empty and fully covered.

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

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

The description clearly states the tool lists supported languages for 3-word output, specifying it returns code and name. This verb+resource pairing is specific and distinguishes it from sibling tools like coords_to_words or words_to_coords, which deal with coordinates.

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

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

The description implies usage when needing to know which languages are supported for 3-word output, but provides no explicit guidance on when to use or not use this tool, nor any comparison to alternatives among the sibling tools. The context is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it returns only active subscriptions by default and lists the return fields, which is useful 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 clear sentences with no unnecessary words, efficiently conveying purpose, return fields, and usage guidance.

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 list tool with good annotations and a single parameter, the description is complete enough. It explains what is returned and when to use it, though it could mention pagination or limits if applicable.

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 the parameter 'include_inactive' described. The description adds meaning by mentioning 'active subscriptions' and implying the default behavior, providing slight additional 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 lists the caller's active subscriptions, specifies the verb 'list' and resource 'subscriptions', and distinguishes from siblings 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 guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel', indicating when to use it and for what purpose.

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 behavioral traits beyond annotations: it's a write operation (readOnlyHint=false), rate-limited to 5 per identifier per day, and does not count against tool-call quota. It does not discuss potential side effects like duplicate handling or persistence, but provides sufficient context for safe invocation.

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 with a clear opening sentence followed by practical usage guidelines. It is moderately concise; every sentence adds value. Minor improvement could be trimming redundant phrases like 'Use when...' but overall efficient.

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

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

Given the tool's low complexity and lack of output schema, the description covers all necessary information: purpose, use cases, parameter details, constraints (rate limit, free usage), and behavioral notes. The agent has enough context to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the enum values in detail and providing usage advice for the message field (be specific, 1-2 sentences, 2000 char max). It also clarifies that context is optional and what each sub-field means.

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 the Pipeworx team about broken, missing, or needed functionality. It enumerates specific use cases (bug, feature, data_gap, praise) and is distinct from sibling tools which focus on research, search, and other utilities.

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

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

The description provides explicit guidance on when to use the tool (e.g., wrong/stale data, missing tool, praise) and when not to (avoid pasting end-user prompts). It also mentions rate limits, that it's free, and that the team reads digests daily, which helps the agent decide appropriately.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. Description adds value by explaining data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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 concise sentences plus bullet list. Front-loaded with main functionality. No redundant or 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?

For a simple tool with 1 optional param and no output schema, the description fully covers purpose, parameters, return values, use cases, and behavioral traits. Annotations handle safety.

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

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

Schema has 100% coverage with enum description. Description adds interpretive context: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' 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 states verb+resource: 'Returns the top tools, top packs, and total call volume over a recent window'. This clearly distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' 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?

Explicitly lists three use cases (discovering hot data, confirming canonical tool, aligning use case). Does not explicitly state when not to use, but context makes it clear this is for aggregate trends.

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 read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral context: internal logic (monotonicity violations, partition-sum checks), similarity threshold, placeholder filtering, fill check against CLOB depth, and response structure. 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 dense but not overly verbose; every sentence adds value. It is front-loaded with the main purpose and then provides detailed explanations. Slightly more structured formatting could improve scannability, but it is efficient for the complexity involved.

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

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

Given the tool's complexity (multiple modes, filters, fill checks) and absence of output schema, the description is remarkably complete. It covers behavior, modes, internal logic, response format, limitations (fill check, similarity threshold, placeholder filtering), and even links to a sibling tool for custom sizing.

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

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

Schema descriptions cover parameters well (event slug, topic seed question), but the description adds significant extra meaning: examples of slugs, how each mode works internally, and the fill check interaction. With 100% schema coverage, baseline is 3, but the added detail 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 description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It explicitly distinguishes two modes (event and topic) with specific use cases, making it highly 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?

The description provides explicit guidance on when to use each mode: no args for trending scan, event for single-event partition check, topic for cross-event scan. It also warns against trading when realizable_edge_pp ≤ 0 and suggests an alternative tool (polymarket_fill_risk) for custom sizing.

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

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

The description goes far beyond annotations by detailing the behavioral traits of the tool: it explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), the caching behavior ('Cached 1h at the KV level'), and the output structure with diagnostics. It does not contradict any annotations; readOnlyHint, idempotentHint, and destructiveHint are all consistent with the described behavior.

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

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

The description is verbose and includes many details that are important but could be more concise. It is structured with numbered sections and bullet points, which helps readability, but the length may be overwhelming. Front-loading the main purpose is good, but some redundancy exists (e.g., repeating edge_pp_net). A tighter description would improve conciseness.

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 lack of an output schema, the description thoroughly explains the return structure (by_segment, fed_candidates, diagnostics), parameter behavior, and underlying models. It covers all aspects a caller needs to understand what the tool does, how to configure it, and interpret results. This is a very complete 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?

The input schema already has 100% coverage with descriptions for all 9 parameters. The tool description adds value by providing contextual usage tips (e.g., 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade' for slippage_pp, and 'min_kelly skips opportunities that are too small to bet sensibly'). This extra context elevates understanding 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb and resource, and distinguishes itself by being a discovery tool for betting opportunities without paging through markets. The title and description align well with the tool's function.

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

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

The description provides a clear use case: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It also gives tuning knobs and explains when to use filters like min_liquidity and max_spread_pp. However, it does not explicitly mention when not to use this tool or compare it with sibling tools like polymarket_arbitrage, so some guidance is missing.

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. The description adds rich behavioral details: data source (daily snapshots), decay computation (on edge_pp_net, net of slippage), snapshot gaps, expiration logic, and response structure. No contradiction with annotations.

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

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

The description is a single dense paragraph. While it front-loads purpose, it lacks white space or structure (e.g., separate sections for input, output, limits). It is information-rich but could be more scannable.

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 response (tracked, expired, snapshot_dates) and limitations (TTL, decay source). It covers the complexity of time-series decay and expiration comprehensively.

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 description adds marginal value beyond schema. It provides default values (days=14, window='1wk') and clamping (max 30). However, the description focuses more on output than parameter details, 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 tool provides 'edge persistence and decay telemetry' with a specific question it answers: 'how long has this edge existed and is it shrinking?' It distinguishes itself from the sibling 'polymarket_edges' by focusing on time-series analysis rather than raw snapshots.

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 when to use: differentiates fresh vs stale edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). Includes limits (60-day TTL, snapshot start). However, does not explicitly state when not to use it or contrast with all 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, already indicating a safe, read-only operation. The description adds valuable behavioral details: it walks the order book ladder, returns specific fields including verdict, and warns about forced directional risk in basket mode. 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 moderately long (~150 words) but well-structured with bold headings (REQUIRES, SINGLE-MARKET, BASKET) and bullet-like lists. It is front-loaded with the core purpose. Could be trimmed slightly, but the structure aids readability.

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

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

Despite having no output schema, the description thoroughly explains return values for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for singles; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg details, thin_legs, max_clean_notional_usd, forced_directional_risk for baskets. It also explains default behaviors and constraints (size clamp 10–1,000,000).

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

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

Schema description coverage is 100%, and the description enriches parameter meanings: e.g., for size_usd it clarifies interpretation for single-market vs basket, and for side it explains default logic in basket mode. This adds value beyond 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?

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly references sibling tools polymarket_arbitrage and polymarket_edges, indicating when to use this tool before 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?

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns about partial basket fills converting arb into directional position. It provides clear context but does not explicitly list alternatives beyond the 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?

The description discloses behavioral traits well beyond the annotations, including compatibility_warning cases, temporal alignment checks, and skipped cross-type/subtype counters. It highlights that real spreads are rare and explains the meaning of various response fields, adding significant transparency.

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

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

The description is well-structured, starting with the main purpose, then detailing two modes, response fields, and safety warnings. While it is somewhat verbose, every sentence adds meaningful information, and the organization aids readability.

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

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

Given the tool's complexity (three optional parameters, no output schema, and rich annotations), the description is highly complete. It explains the response structure, safety fields, temporal alignment, and limitations, covering all aspects an agent needs to correctly invoke and interpret 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?

Although the schema covers 100% of parameters, the description adds value by explaining the relationship between topic and explicit parameters, providing examples, and clarifying the override behavior. This aids in correct parameter selection 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?

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, specifying two modes and the response format. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison.

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

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

The description explains when to use each mode (topic shortcuts vs explicit pairings) and warns that most pre-mapped topics return a compatibility warning, implying that not all pairings yield tradeable spreads. It lacks explicit when-not-to-use guidance or direct alternatives but provides sufficient context for proper usage.

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

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

Annotations already indicate read-only and non-destructive. Description adds scoping detail ('Scoped to your identifier') and hints at efficiency ('without re-deriving from scratch'), providing beyond-annotation value.

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

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

Two sentences, front-loaded with main action, no wasted words. Covers functionality, usage, scoping, and relationships efficiently.

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 retrieval tool, the description is fully sufficient: purpose, usage, scope, and sibling relationships are covered. No output schema needed; return type is implicit.

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 includes a clear description. Description adds practical examples (ticker, address) but does not fundamentally extend parameter semantics 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?

Clearly states the verb 'Retrieve' or 'list all saved keys' and the resource is values saved via remember. Distinguishes from sibling tools 'remember' and 'forget' by referencing them explicitly.

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

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

Provides clear when-to-use context: 'look up context the agent stored earlier' with concrete examples. Implicitly covers when-not-to-use by focusing on retrieval only. Mentions scoping and pairing with remember/forget.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds significant behavioral context: it returns the most recent alerts with specific fields, mentions the side effect of mark_read (flagging events as read), and states that polls work fine. This goes well beyond the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, and each sentence adds meaningful detail without redundancy. It is efficiently structured for quick 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?

Given the moderate complexity (5 optional params, no output schema) and rich annotations, the description covers the return value fields, filtering, mark_read behavior, and even an alternative access method. It is complete enough for an agent to use the tool effectively, though an explicit return format description would push it to 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining 'type' with an example ('sec_8k'), clarifying 'since' as ISO timestamp, and describing the effect of 'mark_read'. However, it does not cover all parameters (e.g., limit, unread_only) as thoroughly as the schema, so it only marginally improves parameter understanding.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly specifying the verb (pull) and resource (subscription feed events). It details the fields returned (source, citation_uri, raw payload) and mentions filtering by type and since, making the tool's purpose very clear and distinct from siblings like 'recent_changes'.

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 usage context (filtering, mark_read to acknowledge, polling works) and even suggests an alternative access method (GET registry.pipeworx.io). However, it does not explicitly state when to use this tool versus others or when not to use it, so the guidance is implied but not exhaustive.

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 multiple behavioral traits beyond annotations: fans out to specific sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail), returns structured changes[] grouped by source with citation URIs, and explains fallback 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?

Dense but single paragraph, front-loaded with examples and clear structure. Very efficient, though could be slightly more scannable with bullet points.

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 structure (changes[] grouped by source + total_changes + citation URIs) and covers all sources, fallback behavior, and parameter semantics. No missing 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?

All 3 parameters have schema descriptions, and the description adds meaning: explains since format (ISO date or relative shorthand like '7d', '30d'), gives typical monitoring value, and clarifies value accepts ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company over a time window, fanning out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from sibling tool 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?

Provides explicit use-case examples ("What's new with X", "latest on Y"), parameter guidance ("Use '30d' or '1m' for typical monitoring"), and explicitly compares with entity_profile for when not to use this tool.

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

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

Description adds behavioral traits beyond annotations: key-value store scoped by identifier, persistence details (authenticated persistent, anonymous 24h). 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?

Concise, front-loaded with core purpose, every sentence adds value. No wasted words.

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

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

Description covers what the tool does, persistence, scope, and pairing. No output schema needed for a simple storage 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. Description adds little beyond schema for parameters, but examples are given in schema. Adequate.

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 'save data the agent will need to reuse later' with specific verb 'save' and resource 'data'. It distinguishes from siblings by mentioning pairing with 'recall' and 'forget'.

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

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

Explicitly says 'Use when you discover something worth carrying forward...' and mentions pairing with 'recall' and 'forget'. Could be more explicit about when not to use, but guidance is clear.

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

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

Annotations already provide safety profile (readOnlyHint, idempotentHint, destructiveHint) and description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. This provides valuable context about internal complexity and efficiency without contradicting annotations.

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

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

Description is well-structured, starting with example queries, then core purpose, usage guideline, and detailed type explanations. Every sentence adds value, though length could be slightly trimmed. It is front-loaded with the most critical information.

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

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

For a tool with 2 parameters and no output schema, the description is remarkably complete: it covers input formats, output details, internal behavior (cascading lookups), and provides concrete examples. No obvious gaps remain for an agent to effectively use 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%, but description adds extensive meaning: lists acceptable input formats for each type (ticker, CIK, name for company; brand/generic for drug), mentions auto-disambiguation for company, and details output fields (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). This greatly assists correct parameter formulation.

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 specific examples ('What's the ticker for…' / 'find the CIK for…') and clearly states the core purpose: resolve user-spoken NAME to canonical/official identifier. It uses the specific verb 'resolve' and resource 'entity', and differentiates from sibling tools which do not offer entity resolution.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID', which is a clear when-to-use directive. Describes supported types and their contexts. While no explicit 'when not to use', the context implies it is the primary tool for ID lookup and alternatives (like entity_profile) are for different purposes.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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 four sentences, front-loaded with the purpose, and each sentence adds value. No wasted words.

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

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

Despite no output schema, the description explicitly lists return fields (score, confidence, signal density). Parameter descriptions are complete, and the tool's complexity is well addressed.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining semantics: 'First entry treated as the subject for narrative; rest are competitors.' and clarifies models and _apiKey usage 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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description explicitly states it is 'useful for competitive AI-marketing audits' and provides a direct example question. It does not explicitly mention when not to use or provide alternative tool names, but the context is clear.

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

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

Annotations already declare safe hints (readOnlyHint, idempotentHint, destructiveHint=false). Description adds extra behavioral context: bundlephobia first measurement may take 5-30s, sources_failed lists timeouts, graceful degradation.

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 informative but somewhat lengthy with multiple clauses. Front-loaded with purpose, but could be more succinct. Still, every sentence adds value.

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

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

Given no output schema, description sufficiently explains return structure (summary block, advisory detail, links, alternative versions). Includes edge cases and provides a complete picture for a composite 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 detailed parameter descriptions. Tool description does not add further parameter information beyond what 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 composite check for npm packages combining deps.dev and bundlephobia. It distinguishes itself from sibling tools (no other dependency scanner present).

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 ('is X safe / popular / small' or 'what does adding lodash cost me') and notes limitations (NPM ecosystem only in v1, partial failures).

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 embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and a 200K char cap with truncation flagging. Annotations already indicate idempotent/read-only; description adds complementary technical details.

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

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

Four sentences, each adding value. Critical detail is front-loaded (semantic search inside record) with examples and constraints in later sentences. No redundancy.

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

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

Despite no output schema, description explains return format and behavior. Covers use case, limitations (char cap), and integration with sibling tool. Sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about output format (passages with offsets and similarity scores) and hints at query style, but doesn't substantially enrich parameter meaning 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?

Clearly states the tool performs semantic search inside a fetched record, with examples like SEC 10-K and articles. Distinguishes from sibling tools by focusing on intra-record search rather than external lookups or comparisons.

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

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

Explicitly tells when to use: when the record is too large for the prompt. Also pairs with ask_pipeworx_grounded, providing a clear workflow. No exclusion but context is sufficient.

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

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

The description discloses behavioral details beyond annotations: OAuth requirement, type-specific filters, delivery channel options with limits (SMS 10/day), webhook auto-disable, and phone verification. Annotations provide idempotentHint=true, but description says 'Creates' which may imply non-idempotent; however, no explicit contradiction. Adds significant behavioral context.

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

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

The description is front-loaded with the core purpose, then prerequisites, then types, then delivery options. Every sentence adds value. No fluff. Well-structured and efficiently communicates all key information.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers return value ('Returns the new subscription id'), types, delivery, and limits. Could be more explicit about the full response structure, but overall complete for a creation 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%. Description adds meaning beyond schema by explaining the semantics of each type (e.g., sec_8k items codes, polymarket_edge topic, fred_series series_id) and delivery fields (email pattern, SMS verification, webhook HMAC signing). This enriches parameter understanding.

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

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

The description clearly states the verb 'Create' and the resource 'a proactive monitoring subscription to a live-data event stream'. It lists specific subscription types and delivery channels, distinguishing it from sibling tools like 'list_subscriptions', 'unsubscribe', and 'recent_alerts'.

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 mentions the prerequisite of a Pipeworx OAuth account and explains that anonymous/BYO cannot persist subscriptions. It implies when to use this tool versus siblings (e.g., 'recent_alerts' for pulling feed), but does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds context that it returns category-bucketed example questions with tool+argument shapes from a live catalog, which is consistent and adds value beyond annotations.

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

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

The description is front-loaded with common user queries, packed with useful details (categories, tool+argument shapes), and every sentence serves a purpose without 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?

For an onboarding/discovery tool with no output schema, the description fully explains what is returned (category-bucketed example questions with tool+argument shape) and when to use it, making it self-contained.

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

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

Schema coverage is 100% with a clear description for the single parameter 'topic', but the description adds practical usage patterns and examples (no args vs. topic values) that enhance understanding beyond the schema.

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

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

The description clearly states the tool is an onboarding entry point that returns categorized example questions, and explicitly distinguishes from sibling tools like ask_pipeworx by advising to 'Use this FIRST when you do not yet know what Pipeworx can do'.

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

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

It gives explicit when-to-use guidance ('when you do not yet know what Pipeworx can do', 'to learn how to call the meta-tools'), usage patterns (no args for full spread, topic to focus), and provides specific topic examples.

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

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

Annotations provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds key behavioral traits: ownership enforcement, deactivation (not deletion), and historical events remaining. This enriches 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?

Two concise sentences. First sentence states action and constraint. Second sentence explains the consequence. Every word is purposeful, 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?

For a tool with one parameter, no output schema, and annotations covering idempotency and non-destructiveness, the description fully covers: the operation, constraints, effect, and link to historical data via 'recent_alerts'. Complete for selection and safe 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 only parameter 'id' is described in the schema as 'uuid'. The description adds context that the id comes from 'subscribe' and clarifies ownership enforcement. This adds value beyond the schema by tying the parameter to its source.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id'. It distinguishes from siblings like 'subscribe', 'list_subscriptions', and 'recent_alerts' by specifying ownership enforcement and deactivation behavior.

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

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

The description tells when to use: to cancel a subscription. Ownership enforcement provides a clear constraint. It does not explicitly state when not to use or mention alternatives, but the context of sibling tools and the ownership hint are sufficient for typical use.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds significant detail: it returns a verdict ('confirmed', 'refuted', etc.), uses exact math for financial claims, and falls through to a grounded pipeline for others. It also notes it replaces 4-6 sequential calls, adding performance context. 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 fairly long but packed with useful information. Every sentence adds value, but it could be more concise. The structure is good: begins with example queries, then usage, then behavioral details, then output. It earns its length but not perfectly 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 (two processing paths, structured output), the description covers input (claim and tolerance), process (financial vs. grounded), and output (verdict, value, citation, reasoning). It doesn't mention error handling or edge cases, but it is mostly complete for an agent's needs. No output schema exists, but description compensates.

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 both parameters (claim, tolerance_pct). The description adds semantic value: for 'claim', it gives natural-language examples and reinforces it's a factual claim. For 'tolerance_pct', it explains the default (implied by wording, capped at 5) and suggests use cases (1-2 for hallucination detection). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources. It provides specific example queries ("Is it true that…", "fact check") and distinguishes between company-financial and other claims, making it distinct from siblings.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two processing paths (financial vs. other), giving clear context on when to use this tool. It does not explicitly state when not to use it or list alternatives, but the guidance is strong enough.

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

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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds that the result is a centre point and bounding box, which gives the agent a clear expectation of the output shape without contradictions.

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

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

The description is a single sentence that conveys all necessary information without extraneous words. It is efficiently structured and front-loaded with the key 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?

For a simple tool with one parameter and an output schema, the description covers the essential purpose and output. Not explicitly mentioning the output schema is acceptable since it exists separately.

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

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

The input schema already provides 100% coverage for the single parameter 'words' with a description. The tool description does not add additional semantic details beyond what the schema states, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Convert' and the resource '3-word address', and specifies the output as 'lat/lon centre + 3m×3m bounding box'. It distinguishes from the sibling tool 'coords_to_words' by focusing on the direction from words to coordinates.

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

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

The description implies use when a three-word address is available and coordinates are needed. It does not explicitly list when not to use or mention alternatives, but the context of sibling tools is available for the agent to infer.

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