nominatim

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 description does not need to repeat safety traits. It adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b) being free, the requirement to pass `_apiKey` for Anthropic with 'you pay Anthropic directly for those calls,' and the return format (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations.

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

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

Three sentences, front-loaded with the core action and output. Each sentence earns its place: purpose and scoring, default model and optional Anthropic key, return structure and use cases. No fluff or redundant repetition of schema details.

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 4 parameters, one required, no output schema, and strong annotations, the description is substantially complete. It states what the tool does, the return structure (since no output schema exists), default behavior, optional model support, and typical use cases. It could mention error conditions or rate limits, but for a light-weight probe tool this is not a major gap.

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 schema already provides thorough descriptions for all parameters, including the 'free default' for models, the _apiKey's purpose ('Passed straight through to api.anthropic.com'), and context examples. The description adds only marginal nuance (e.g., cost implication for Anthropic) but does not significantly compensate beyond the schema, so it remains at baseline.

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 'Probe[s] one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb ('probe') with a defined resource (LLMs) and outcome (visibility scores). It distinguishes itself from siblings by focusing on per-model visibility scoring and mentioning default model behavior, which differs from tools like 'scan_competitor_ai_presence' that likely focus on competitors.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` (to also probe Anthropic) and the default model behavior. However, it does not explicitly name alternatives or state when not to use this tool (e.g., versus 'scan_competitor_ai_presence'), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context beyond this: it routes to many tools, fills arguments, returns 'stable pipeworx:// citation URIs', and 'works on every tier, one fast call.' No contradiction with annotations.

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

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

The description is long but front-loaded with the key directive 'PREFER OVER WEB SEARCH' and a clear list of covered domains. Some redundancy exists in repeated positioning ('default entry point') and trigger phrases, but overall the length is justified for a broad universal 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?

For a tool with no output schema, the description adequately explains the return type ('structured answer with stable pipeworx:// citation URIs'), offers diverse examples, specifies routing behavior, and covers when to escalate to sibling tools. The context is complete for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% with descriptions for all 6 parameters and an explanation that 'question' accepts query, q, prompt, text, input as aliases. The description provides example questions but no additional parameter-level detail beyond what the schema already states, so the baseline 3 applies.

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

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

The description clearly defines the tool as a question-routing engine: 'Routes the question to the right one of 5,564 tools across 1462 verified sources' and returns a structured answer with citations. It explicitly distinguishes itself from siblings by saying 'PREFER OVER WEB SEARCH' and naming ask_pipeworx_grounded and deep_research as alternatives for different use cases.

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

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

Provides explicit when-to-use guidance: 'Use whenever the user asks...' and 'START HERE for most questions — this is the default entry point.' It also explains when NOT to use it by directing users to ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the bar is lower. The description adds valuable behavioral context: candidate routing improvements are enabled live, results are compared to stable, and it is a full working router (not a fallback). This clarifies the experimental and state-dependent behavior 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 longer than strictly needed but every sentence earns its place: beta status, current active-candidate state, usage directive, and experimental nature are all covered. It's front-loaded with the core definition and maintains focus.

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 experimental alias of a known router, the description is quite complete: it covers what it is, current behavior, usage, and relationship to stable. It mentions 'same response shape' but doesn't describe the response format, which is a minor gap in the absence of an output schema. Overall, it provides enough context for an agent 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% and the description says 'same arguments' but adds no new parameter semantics beyond what the schema already provides. The schema documents question and its aliases, so the baseline 3 applies.

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

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

Clearly identifies itself as 'Beta version of ask_pipeworx: identical universal router' with specific details (same 5,564 tools, same arguments, same response shape). It distinguishes itself from siblings by explicitly framing it as the experimental edge of the stable ask_pipeworx.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It names the alternative (ask_pipeworx) but doesn't explicitly say 'use stable when you want reliability', so it's not a full when-not statement.

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

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

Beyond the annotations, the description discloses refusal behavior with specific refusal_reason values, the return shape including evidence as a verbatim quote, that it makes one extra LLM call versus ask_pipeworx, and that extraction uses only what the tool result contains. This substantially exceeds the information already provided by the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint 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 the core purpose in the first sentence, then gives behavioral detail, return format, refusal reasons, and usage guidance in a compact three-sentence structure. Every sentence earns its place and the length is justified by the tool's refusal semantics and high-stakes context.

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

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

There is no output schema, so the description appropriately explains the success return object and the full set of refusal reasons. It also provides cost/performance trade-offs, alternatives, and routing behavior, making the tool's behavior fully understandable for an agent without needing additional context.

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

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

The schema covers 100% of parameters by describing question and all five aliases, so the description does not need to add parameter-level meaning. The description adds no extra param detail beyond natural-language question handling, matching the baseline of 3 for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly explains that the tool routes like ask_pipeworx, fetches data, and extracts answers only from tool results, which distinguishes it from the sibling ask_pipeworx and ask_pipeworx_beta.

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

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

Explicit usage guidance is provided: use when an answer will be quoted, cited, or acted on and when facts must not be invented, with examples like financial verdicts and legal claims. It also names the alternative ask_pipeworx and states to prefer it for casual lookups, making the when-to-use vs. when-not-to-use distinction explicit.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses extensive behavioral traits: low-confidence resolution short-circuiting, closed-market handling, wide-spread illiquidity flags, resolution-rule risk parsing with refund_50_50 implications, and blocking routes. This adds substantial context well beyond the structured data.

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

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

The description is long but heavily structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY) and front-loads the core purpose. Every sentence conveys specific operational detail, though a leaner version might omit some examples; the organization earns a 4.

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

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

With no output schema, the description carries the burden of explaining response shapes, resolver contract, parent_event, news fields, and safety statuses — all are covered in detail. It also covers edge cases (cancellation rules, low-confidence matches) making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: concrete examples for market, depth's quick/thorough distinction with default, and include_raw's effect on response size (under ~20KB vs 50-500KB). This elevates it to 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 opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data'), and clearly separates this from siblings like polymarket_edges/arbitrage via the 'Use for' context. It also names the return structure (evidence packet + market-vs-model comparison), making the tool's function unmistakable.

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

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

The description explicitly lists the use cases ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"') and provides detailed fan-out examples. It does not explicitly name alternative tools to avoid, but the context makes the intended scenarios clear, so this is a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context beyond these: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), details exactly which metrics are pulled (revenue, net income, cash, long-term debt; adverse-event counts, approval counts, trial counts), handles off-calendar fiscal years (AAPL Sep, NVDA Jan), and notes results are sorted by primary metric. This fully discloses behavior 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?

Although the description is long, every sentence earns its place. It is front-loaded with trigger phrases and the core purpose, followed by structured details per type and output format. No fluff or redundancy; the length is justified by the richness of needed behavioral context. It is well-organized and easily 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 the tool's complexity (two entity types, multiple metrics, citation URIs, sorting) and the absence of an output schema, the description is remarkably complete. It covers inputs (how to specify values), behavior (data sources, metrics, fiscal handling), and outputs (paired data + pipeworx:// URIs, sorted by primary metric). No critical missing information for an agent 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?

The input schema already provides descriptions for both parameters (type enum with 'company'/'drug', and values array with min/max items and examples). The description complements this by explaining what each type actually does (company pulls 10-K financials, drug pulls regulatory/clinical counts) and gives formatting examples (tickers/CIKs vs. names). While schema coverage is 100%, the description adds meaningful semantic detail that helps the agent select valid values correctly, hence above baseline.

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

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

The description opens with explicit trigger phrases and clearly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It names the specific entities (companies/drugs) and the action (comparison), and distinguishes itself from sibling tools like lookup and entity_profile by emphasizing parallelism and breadth. This is a specific verb+resource definition with clear differentiation.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives concrete trigger examples and explains the tool replaces 8–15 sequential lookups. It implies alternatives (single-pack lookups) and sets a clear preference rule, making it easy for an agent to decide when to invoke this tool.

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

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

Adds extensive context beyond annotations: account requirements, open-world caveat (NOT open-web search), gap reporting ('never invented'), citation resolvability, semantic excerpting, hop field, contradictions[], and latency expectations. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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

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

The description is verbose but highly information-dense, with every sentence carrying functional value (features, limitations, alternatives, latency). It is front-loaded with critical account/usage warnings and structured in digestible chunks, though some redundancy exists with the schema's depth explanation.

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

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

Despite no output schema, the description fully specifies return packet contents (evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]) and covers account, latency, data scope, and alternates. This is complete for a complex orchestration 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 already provides 100% coverage for both parameters, but description enriches meaning with concrete examples for 'question' and behavior/paid-plan implications for 'depth'. The description clarifies depth semantics (standard vs thorough gap recovery/lead chasing) beyond the schema text.

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 grounded multi-source research across Pipeworx's structured data sources in one call, decomposing questions into facets and routing them in parallel. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx for single lookups and 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?

Extremely explicit guidance: 'Best for broad/multi-part questions over structured data' and explicit alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also covers account requirements and fallback behavior.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it returns top-N tools with full input schemas and curated examples, eliminating the need for a second schema lookup. It also advises calling it first, giving the agent a clear procedural expectation. This exceeds what annotations alone convey.

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

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

The description is front-loaded with the core purpose in the first sentence and each subsequent sentence adds distinct value: the domain list, the return format, and the 'call first' guidance. It is compact, well-organized, and free of filler. The use of a colon-separated domain list is efficient and 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?

There is no output schema, so the description correctly explains what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' This fully addresses the return value question. Given the tool's simplicity and strong annotations, the description covers all necessary behavioral and output context.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including the query alias system. The description does not add parameter-level detail beyond what the schema provides; it only mentions 'query' indirectly. Baseline 3 is appropriate when the schema does the heavy lifting, and the description does not compensate further.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes from siblings by positioning itself as the discovery tool, listing the many domains it covers (SEC filings, financials, FDA drugs, etc.) and stating it returns relevant tools ready to call. This makes the purpose unambiguous and differentiated.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it does not name specific alternative tools or give a direct 'when not to use,' the 'not just one answer' clause implies a contrast with direct single-purpose tool calls. This is strong usage guidance but lacks explicit exclusions.

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

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

Discloses multiple behavioral traits beyond annotations: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; notes the USPTO PatentsView API sunset and soft-fail behavior; mentions GDELT→GNews fallback; describes return fields. This adds significant context beyond the readOnly/idempotent hints.

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

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

The description is lengthy but densely informative, front-loaded with examples and the core purpose. It includes all necessary context without irrelevant fluff, though it could be slightly more structured with bullet points or line breaks.

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 enumerates return values (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and covers edge cases (patent sunset, name resolution, zero-padded CIK). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, with both parameters fully documented including ticker/CIK format and names-not-supported rule. The description echoes these details but adds no substantive meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly identifies the tool as a comprehensive cross-source profile generator for US public companies, using specific verb phrases like 'full cross-source profile' and concrete user intent examples ('Tell me about X', 'research Acme'). It distinguishes from siblings by explicitly stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'.

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

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

The description explicitly states when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides an alternative for names: 'use resolve_entity first if you only have a name.' This gives clear context and 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds context about memory persistence and uses, but doesn't disclose additional behaviors like irreversibility or behavior on missing keys beyond what annotations imply.

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 ('Delete...'), followed immediately by usage guidance. Every sentence provides value, with no filler or repetition.

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 full schema coverage and informative annotations, the description sufficiently covers the tool's purpose and usage context. The pairing with remember and recall rounds out the ecosystem understanding, and no return format is needed for a delete operation.

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 description 'Memory key to delete'. The tool description's 'by key' simply confirms the schema without adding new meaning, so it meets the baseline for well-covered schemas.

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, which is a specific verb+resource combination. It also distinguishes from sibling tools like remember and recall by explicitly pairing with them, indicating deletion versus storage/retrieval.

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

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

The description provides explicit when-to-use conditions: stale context, task done, or clearing sensitive data. It does not give when-not-to-use or explicitly name alternatives, but the pairing with remember and recall implies complementary 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by detailing the internal steps: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This gives the agent a clear mental model of what happens, beyond what annotations provide. It does not mention edge cases or failure modes, but the annotations lower the burden.

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

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

The description is three sentences long and highly efficient. It front-loads the main action, then explains the process, and ends with practical use cases. Every sentence adds value with no redundancy or filler. The structure is ideal for quick comprehension by an AI agent.

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

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

For a simple two-parameter tool with no output schema, the description covers the essential context: what it does, how it works, what the output looks like, and when to use it. Annotations fill in the safety profile. It lacks explicit error-handling details or rate-limit information, but those are not critical for this kind of read-only, idempotent tool. It is complete enough for most use cases.

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 covers both parameters with clear descriptions (url as the site to summarize, max_links with default and maximum). Since schema description coverage is 100%, the description's role is minimal. The description does add context about the output ('single text blob ready to drop at site-root/llms.txt'), but it does not add significantly to the parameter meanings. 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 core function: generating a production-ready llms.txt file for any URL. It specifies the verb 'Generate', the resource 'llms.txt', and the scope 'for any URL', distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence. The use cases further clarify its unique purpose.

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 concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, auditing how an AI crawler would see a competitor'), which clearly imply when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds value by specifying the scope ('caller's active subscriptions') and exact response fields, which are useful 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 two sentences: the first states purpose and output, the second gives usage guidance. No filler or redundancy.

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

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

For a simple list tool with one optional parameter, the description covers purpose, output fields, and usage context. Sibling differentiation and annotations fill any remaining gaps.

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

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

Schema coverage is 100%, with include_inactive documented in the schema. The description adds no additional parameter details, so it earns the baseline score for schema-covered parameters.

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 'List the caller's active subscriptions' with a specific verb and resource, and enumerates returned fields. This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

It explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing concrete use cases relative to subscribe and unsubscribe.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, so the description's burden is lower. It adds context by specifying the return content (coordinates, names, metadata) and clarifying the ID format. This is useful beyond the annotations and shows 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 two sentences, front-loaded with the action, and contains zero filler. Each clause contributes either the purpose, the ID format, or the output expectations.

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 lookup tool with one well-documented parameter, strong annotations, and an output schema, the description is fully sufficient. It covers input format and scope, and the output schema handles return-value details. Nothing important is missing.

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

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

The schema covers the single 'ids' parameter thoroughly with an explanation and examples, achieving 100% coverage. The description doesn't add significant parameter-level meaning beyond the schema—it mostly restates the format. 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 uses a specific verb and resource: 'Get details for OpenStreetMap locations by ID', with clear examples of N/W/R prefixes. This clearly distinguishes it from sibling tools like reverse_geocode or search_address, which operate on different input types.

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

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

The description clearly implies the intended use case: when you have OSM IDs and need their details. It provides examples of valid ID formats, making the input expectations explicit. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a 5.

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

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

Annotations only set all hints to false (not read-only, not idempotent, etc.), leaving behavioral nuance to the description. The description discloses key behaviors: filing without an account returns a claim_token, later passing it back reads resolution status, rate limit of 5 per identifier per day, free usage, and that team reads digests daily affecting roadmap. This goes well beyond annotations.

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

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

Though longer than typical, every sentence earns its place: purpose, when-to-use, exclusions, claim_token flow, rate limit, and roadmap impact. Information is front-loaded with the core definition first, then usage guidance, then operational details. 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?

The tool has nuanced behavior (conditional token flow, scope restrictions, rate limits, non-quota usage) but the description covers all of it. Without an output schema, it still explains what responses look like (claim_token, status, changes). Given the complexity, this description is remarkably complete.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds extra semantics for claim_token by explaining the full workflow: returns a token, pass it back later to check status and changes. It also clarifies the type enum values (bug/feature/data_gap/praise) with concrete examples, reinforcing 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback types (bug, feature/data_gap, praise) and clearly distinguishes from sibling tools like ask_pipeworx, which answer queries rather than accept feedback.

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

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

Explicitly states when to use: for bug reports, feature/data gap requests, or praise. Provides exclusions: 'ONLY for tools served by this Pipeworx connection' and instructs to file elsewhere for other MCP servers. Also gives a heuristic: 'Not sure? Pipeworx tool names are the ones this connection lists.'

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, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it reveals the data source ('derived from CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h depending on window'). This gives the agent a clear picture of what to expect without overclaiming.

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

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

The description is compact yet information-dense. It opens with the core purpose, then provides a bullet-style list of use cases, and closes with technical details. No wasted words; every sentence earns its place.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It explains the return value, use cases, data provenance, privacy, and caching. The annotations cover safety, so nothing critical is missing.

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

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

The input schema already provides 100% coverage for the 'window' parameter, including the enum values and semantic explanation ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description only repeats the window options without adding new meaning, 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's function: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It uses a specific verb and resource, and the use cases listed distinguish it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming a canonical tool choice, and checking alignment with other agents' needs. While it doesn't explicitly mention alternatives or exclusions, the guidance is clear and actionable for an agent deciding when to invoke this tool.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses key behaviors: the >3pp BUY/SELL trigger, fill check caveat (realizable_edge_pp ≤ 0 means do not trade), skipped_low_similarity counter, and the partition filter with placeholder handling. These are valuable operational details not implied by 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 long but densely informative, using clear signposts (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loading the purpose. Every sentence adds value—there is no padding or repetition.

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

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

With no output schema, the description compensates by detailing the response structure (opportunities[], partition_check, skipped_low_similarity) and covering edge cases (fill check, placeholder filter). Given the complexity of the tool, it is complete enough for an agent to invoke and interpret results 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?

While the schema covers both parameters at 100%, the description adds crucial meaning: event accepts slugs or full URLs and walks child markets; topic accepts seed questions and searches related events. It provides concrete examples for each and clarifies that neither argument is required for the trending scan.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by explaining its unique approach.

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

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

Explicit guidance is provided: 'Call with NO args' for a trending scan, 'event (recommended for a specific market)', and 'topic (for cross-event scanning)' with example inputs. It also names an alternative tool ('For custom sizing use polymarket_fill_risk') and explains when one mode catches patterns another misses.

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 revealing caching behavior ('Cached 1h at the KV level'), response structure (by_segment, diagnostics), algorithm details (model families, edge calculation), and caveats like the Fed signal unreliability. It also explains how slippage is subtracted and what the 24h-move warning means, providing rich behavioral context beyond the read-only/idempotent hints.

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

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

The description is very long and dense, as a single paragraph with extensive algorithm details and parameter rationale. It is front-loaded with purpose, but the length and lack of visual breaks make it harder to parse. Every sentence is informative, yet the overall size is borderline for 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?

With no output schema, the description thoroughly documents the response top-level structure (by_segment, fed_candidates, _diagnostics) and explains the purpose of each segment and diagnostic. It also covers parameter effects, edge cases (placeholder-slug filter), and even transient behavior (1h cache), making it complete for a complex tool.

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

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

Despite the schema having 100% description coverage, the description adds relational meaning: it explains that min_kelly never filters partition arbs (they always return kelly_fraction_half=0) and gives rationale for slippage_pp ('zero trading fees but 20-50bp typical'). This helps the agent understand how parameters interact, exceeding baseline.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This uses a specific verb ('Scan') and resource ('Polymarket markets'), and the tagline 'what should I bet on today' distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 ('what should I bet on today') and explains when to adjust knobs (e.g., 'Set to 2 to require tight books'). However, it does not explicitly mention when not to use this tool or name alternatives, though sibling tools exist.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial non-obvious behavior: the response shape (tracked[], expired[], snapshot_dates[]), the cache-miss-based snapshot writing causing gaps, the 60-day TTL bound, and the fact that decay is computed from daily closes (not intraday). All of this goes well beyond what annotations convey.

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

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

The description is dense but well-organized into purpose, args, response, and limits. Every sentence carries operational information, especially valuable given there is no output schema. It is several sentences long, but all are necessary to explain the tool's complexity. It is not needlessly verbose.

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

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

For a tool with no output schema, the description thoroughly documents the response structure (tracked[] with trend and decay, expired[] with lifespan_days, snapshot_dates[]) and provides limits (TTL, daily-closes, snapshot gaps). It covers edge cases and expected anomalous behavior, making it exceptionally complete.

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

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

The input schema already covers both parameters with meaningful descriptions (days: lookback with default and clamp; window: which polymarket_edges window family). The description restates these (days default 14, max 30; window default '1wk') and adds slight color like 'snapshot family,' but no genuinely new semantic beyond the schema. With 100% schema coverage, 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 opens with a specific, discriminating purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers a trading question and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series behavior ('how long has this edge existed and is it shrinking?').

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

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

The description clearly frames when to use this tool: when persistence or decay matters, as in 'a fresh wide edge and a 3-week-old wide edge are different trades.' It implies the alternative is using a raw current-edge tool, but it does not explicitly name a sibling tool or state 'use this when X, use that when Y.' This is more than implied context but lacks an explicit exclusion clause.

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 only indicate read-only, open-world, idempotent, non-destructive. The description goes far beyond: it explains the walk-depth behavior, interpretation of size_usd for buys vs sells and for basket settlement notional, the verdict outcome (clean|degraded|cannot_fill), and the critical risk that 'partial basket fills convert an arb into an unhedged directional position' — a nontrivial behavioral caveat not derivable from the schema or 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 and slightly long, but every sentence earns its place by covering mode selection, parameter semantics, output fields, and a concrete usage warning. It is front-loaded with the core purpose, and the risk warning at the end is essential. A slightly more structured layout (e.g., labeling SINGLE-MARKET and BASKET) would improve scannability, but it remains economically worded.

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

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

This tool has two distinct modes and no output schema, yet the description enumerates all major return fields for both modes (e.g., theoretical_sum, realizable_sum, capture_ratio, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also provides the necessary context of when to use it as a pre-trade check for other tools. The description is fully self-contained despite the tool's complexity.

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

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

Even though schema coverage is 100%, the description enriches every parameter. It clarifies that `market` and `event` are mutually exclusive modes, explains that `side` has mode-specific allowed values and defaults (including auto-detection for baskets), and defines `size_usd` as spend for buys, target proceeds for sells, and settlement notional for baskets. It also mentions clamping ranges (10–1,000,000). This is far beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket/partition modes, and names concrete return fields (top_of_book, vwap_fill_price, slippage_pp, etc.). This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides mode-selection rules: 'REQUIRES one of market (single-market mode) or event (basket/partition mode).' This both clarifies when to invoke and implies when to avoid (e.g., for small trades or when only theoretical edge matters).

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses behavior in detail: how spreads are computed, what compatibility_warning means in two distinct cases, the role of temporal_alignment, and the skipped_cross_type/subtype counters. It also warns about the rarity of real cross-venue spreads. This is far more transparent than the annotations alone, and there is 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 long but well-structured, with uppercase section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and a purpose-opening sentence. Every sentence carries meaning, covering modes, output, warnings, and caveats. It is not as terse as the TDQS high example, but the complexity of the tool justifies the length and 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?

With no output schema, the description fully specifies return values: leg-by-leg prices, matched spread top_spreads_pp, compatibility_warning, temporal_alignment, and skip counters. It explains edge cases and failure modes, making the tool usable without further documentation. The context signals confirm this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the interplay between topic and explicit parameters (override semantics) and provides examples like 'KXFED-26OCT' and 'fed-decision-in-june-825'. It also elaborates on the topic enum and how each mode affects the comparison, going beyond the schema's bare 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: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by emphasizing the two-venue comparison and the compatibility checks, setting it apart from tools like polymarket_arbitrage. The description also explains both modes (topic shortcuts and explicit tickers), making the scope 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 clear usage context by explaining the two modes (topic and explicit) and the override behavior of parameters. It also includes important cautions, such as 'pre-mapped ≠ tradeable' and the conditions under which compatibility_warning fires, guiding when results are meaningful. However, it does not explicitly name alternatives or state when not to use the tool, though this is partially implied by the safety field explanations.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the list-all behavior when the key is omitted, going beyond the structured annotations.

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

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

The description is three sentences, front-loaded with the core action and immediately useful context. Every sentence earns its place: the action, the use case, the scoping, and the companion tools. 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?

For a simple tool with one optional parameter and no output schema, the description covers the essential aspects: what it retrieves, how to list all keys, the intended use case, scoping, and relationship to remember/forget. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the schema already describes the 'key' parameter as 'Memory key to retrieve (omit to list all keys)'. The description repeats this behavior without adding new semantic details, so it meets the baseline but does not exceed it.

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

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

The description opens with a specific verb+resource pair: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from sibling tools by referencing 'remember' and 'forget' as complementary actions, making the tool's role in the memory workflow explicit.

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

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

It states when to use the tool ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and points to related tools ('Pair with remember to save, forget to delete'). It lacks an explicit 'when not to use' exclusion, but the context is clear enough for a simple lookup tool.

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

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

The annotation declares readOnlyHint:true, but the description explicitly says 'Set mark_read:true to flag returned events read', which is a state-mutating behavior. This directly contradicts the read-only annotation, so the description fails to align with structured metadata.

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

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

The description is three sentences, front-loaded with the main action. Each sentence adds unique value: return payload/filters/mark_read/polling/alternative endpoint. No redundant or filler text.

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

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

Without an output schema, the description compensates by explaining the return item fields (source, citation_uri, raw payload), filters, the mark_read side-effect, and polling feasibility. It also covers an alternative access method, making the description complete for practical use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by giving a concrete example for type ('sec_8k'), clarifying that 'since' is an ISO timestamp, and explaining the semantic effect of mark_read on subsequent calls.

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

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

The description clearly states the tool 'Pull fired events from your subscription feed' and specifies it returns recent alerts with source, citation_uri, and raw payload. This distinguishes it from sibling tools like recent_changes or list_subscriptions by focusing on subscription 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 provides clear context: polling is fine, and an alternative HTTP endpoint is mentioned for scripts/dashboards. However, it does not explicitly exclude sibling tools or state when not to use this tool, so it lacks full when-not 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?

Goes well beyond the annotations by disclosing multi-source fan-out to SEC EDGAR, GDELT→GNews fallback due to rate limits, USPTO soft-fail due to API sunset, and return structure with grouped changes and pipeworx:// citations.

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

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

The description is long but front-loaded with user intents and every clause contributes essential information (sources, fallback, return shape, alternative). It could be trimmed slightly but remains efficient for its complexity.

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

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

Without an output schema, the description explicitly states returns: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also explains fallback behavior, soft-fail, and input formats, fully covering the tool's contract.

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

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

Schema coverage is 100% with clear descriptions for all three parameters and an enum for type. The description repeats the `since` formats already present in the schema and adds no new parameter semantics, so the baseline 3 applies.

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

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

The description explicitly defines the tool as a 'change feed for a company in the last N days/weeks/months' with a specific verb and resource. It distinguishes itself from sibling entity_profile by stating 'Use entity_profile instead when you want the static profile'.

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

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

Provides clear when-to-use context with natural-language triggers ('What's new with X', 'latest on Y') and explicitly directs users to entity_profile for static profiles, covering both use and alternative 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 declare idempotentHint=true and readOnlyHint=false, but description adds valuable context: key-value scoping by identifier, persistence differences for authenticated vs anonymous users (24-hour retention), and the relationship with recall/forget. This goes well beyond the structured annotations.

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

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

Three sentences; the first is front-loaded with the primary action, and each subsequent sentence adds meaningful detail without redundancy.

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

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

For a simple two-parameter tool, the description covers purpose, when to use, persistence behavior, scoping, and sibling tool relationships. No output schema is needed for a store operation, so nothing essential is missing.

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

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

Schema coverage is 100% with detailed parameter descriptions and examples. The description does not add new parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool saves data for reuse, with a specific verb ('Save') and resource (data needed later). It distinguishes from siblings by mentioning pairing with recall/forget and the scope of use.

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

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

Provides explicit when-to-use guidance with concrete examples (ticker, address, preference, research subject). Does not explicitly state when not to use or name alternative tools, but the 'so you don't have to look it up again' hints at avoiding repeated lookups.

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

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

Discloses cascading internal calls, graceful degradation (e.g., 'if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and output format details (identifiers labeled by source, unresolved values explicitly listed). Adds significant value beyond annotations which already declare readOnly and idempotent.

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

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

The description is dense but well-structured: example queries, then purpose, then detailed type explanations. Every sentence adds value. Could be slightly tightened but is not wasteful and front-loads 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?

Given the complexity (cascading lookups, multiple identifier types) and lack of output schema, the description explains return format (labeled identifiers, unresolved list) and degradation behavior. Lacks explicit output structure, but provides enough for an agent to understand what to expect.

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

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

With 100% schema coverage, the description still adds rich context: for type 'company' explains cross-source identity spine, for 'value' details accepted inputs (ticker, CIK, ISIN, name) and how ISIN resolves via GLEIF. Schema only gives basic examples; description provides operational meaning.

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

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

The description starts with concrete example queries and clearly states it resolves user-spoken names to canonical identifiers required by other tools. It distinguishes itself by being a composite lookup that replaces 2-3 manual lookups, separating it from sibling tools like entity_profile or compare_entities.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID.' Provides clear context on when to invoke. Does not explicitly mention when not to use or name alternative tools, but the guidance is strong enough for most agent decisions.

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, and non-destructive behavior. The description adds context by stating the return value includes the nearest address, place name, and administrative boundaries. This provides useful behavioral detail beyond the annotations, though it does not cover error cases or edge conditions.

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 primary purpose, and every clause adds value. It avoids redundancy with the schema and annotations.

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

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

The tool is simple with two well-documented parameters, a clear output schema, and annotations covering safety and repeatability. The description sufficiently conveys the tool's purpose and expected results without increasing complexity.

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

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

The input schema covers 100% of the parameter descriptions, including examples and units for lat/lon. The description does not add further parameter-level meaning, so the 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 precisely states the tool's function: converting lat/lon coordinates to a human-readable address. It distinguishes itself from sibling tools like search_address by explicitly mentioning the direction of conversion (coordinates to address) and the specific outputs (address, place name, administrative boundaries).

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

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

The description clearly implies usage when coordinates are available and an address is needed, but it does not explicitly discuss when not to use this tool or mention alternatives. The context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral detail: it internally calls ai_visibility_check per entity, ranks by score, and returns score/confidence/signal density. This goes beyond the annotations without contradicting them.

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

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

Three sentences, front-loaded with the main action, followed by an illustrative example and a concise list of return fields. Every sentence earns its place with no filler or repetition.

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

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

With no output schema, the description compensates by specifying the return format (ranked list with score, confidence, signal density) and the use case. It also mentions the internal probe mechanism. Given the tool's orchestrated multi-entity nature, this is quite complete, though it could optionally mention model-dependent behavior (already in schema).

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

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

Schema coverage is 100%, so the schema already documents all four parameters clearly. The description reinforces that the first entity is the subject and the rest are competitors, but that detail is already in the schema. No additional parameter-specific meaning is provided, 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 uses a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), clearly distinguishing it from the single-entity sibling tool ai_visibility_check. It explicitly states it probes, ranks, and surfaces most/least recognized, leaving no ambiguity about its function.

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

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

It provides a clear use case ('competitive AI-marketing audits') with an example question, implying this tool is for multi-entity comparisons rather than a single check. However, it does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. 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 focused paragraph with a logical flow: purpose, usage, return fields, limitations, and failure behavior. Every sentence adds value, though it is dense and could benefit from bullet points for scannability. Still well-structured for the complexity.

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

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

Given no output schema, the description explains return values in detail (summary fields, advisories, links, alternatives), covers ecosystem scope, and clarifies partial failure behavior. It is complete for a composite tool with multiple data sources and edge cases.

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

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

Schema coverage is 100%, with both package and version already described. The description adds minimal new parameter meaning—it mentions 'is_latest' and defaults to latest, but the schema already states that version defaults to latest. Baseline of 3 is appropriate.

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

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

The description opens with a clear verb + resource: a composite check for whether to add an npm package, fanning out to deps.dev and bundlephobia. It distinguishes from sibling tools by explicitly targeting npm dependency evaluation, while siblings like scan_competitor_ai_presence cover different domains.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and states NPM-only in v1, directing other ecosystems to deps.dev:version. This provides clear when-to-use and an alternative for non-NPM 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=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is fully disclosed. The description adds that it returns specific fields, but since an output schema exists, this is somewhat redundant. It does not mention any rate limits, data limitations, or other behavioral constraints, but with annotations present, the additional burden is minimal.

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 of 18 words, front-loaded with the action 'Search' and immediately specifying the input and output. Every word contributes to understanding the tool's purpose. There is no fluff or redundancy.

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

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

For a simple two-parameter read-only tool with full schema descriptions, examples, and comprehensive annotations, the description is sufficient. It clearly conveys the core function and output. It does not explicitly mention the alternative reverse_geocode, but the sibling naming and tool name make this implicit, and the return fields are already documented in the output schema, so no critical context is missing.

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

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

The input schema provides complete descriptions for both parameters: 'query' (free-form address or place name) and 'limit' (maximum results, default 5, max 50). The tool description does not add any parameter-specific details beyond what the schema already states, so schema coverage is 100% and the description adds no extra value in this dimension.

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

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

The description clearly identifies the tool as a forward geocoder: 'Search for coordinates of an address or place name.' It specifies the resource (coordinates for an address/place name) and lists the return fields (latitude, longitude, display name, place type). This distinguishes it from the sibling 'reverse_geocode' tool, which does the opposite.

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

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

The description provides clear context: use this tool when you have an address or place name and need coordinates. It does not explicitly mention when not to use it or name alternative tools, but the sibling list includes 'reverse_geocode,' and the phrasing implies this is for forward geocoding. This is clear context without explicit exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses concrete behavior: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and truncates inputs above 200K chars with a flag. This gives the agent an accurate mental model of how the tool behaves.

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

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

The description is information-dense but every sentence earns its place: purpose, return format, use case, sibling pairing, and algorithm details. It is front-loaded with the core function, and the length is justified given the complexity of the tool. 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?

Without an output schema, the description explains the return shape (top-N passages, offsets, scores) and the truncation behavior. It covers enough for an agent to select and invoke the tool confidently, including a realistic example of query phrasing. No critical gaps remain.

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

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

Schema coverage is 100%, with each parameter already described clearly. The description adds no new parameter-specific semantics; it only mentions the 200K cap for text (already in schema) and doesn't elaborate on limit beyond the schema's 'Max passages to return.' Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes itself from siblings by explaining that it searches within already-fetched text rather than over the whole document, and it explicitly names a sibling (ask_pipeworx_grounded) to show how they differ.

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

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

The description gives an explicit use case: 'Use when the record is too big to cram into the prompt.' It also provides a pairing strategy with ask_pipeworx_grounded, telling the agent when and how to combine tools. This is direct, actionable guidance with no ambiguity.

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

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

Beyond the annotations (mutation, non-destructive, idempotent), the description discloses critical behavior: OAuth-only persistence, feed always on, SMS phone verification and daily cap, webhook HMAC signing secret returned only once, and auto-disable after 10 consecutive failures. This is rich, non-obvious 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 long but dense and well-front-loaded. It starts with a one-sentence core purpose, then logically organizes requirements, supported types, and delivery channels with inline examples. Every clause adds operational detail — no filler or repetition of the schema.

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

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

For a tool with 3 parameters, nested objects, 5 enum types, and no output schema, the description covers: return values (subscription id, one-time webhook secret), auth requirements, per-type parameter structures, delivery channel options with constraints, and failure behavior. This is fully sufficient for an agent to invoke correctly.

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

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

The schema already describes parameters at 100% coverage, but the description adds valuable examples and semantics: specific item codes for sec_8k, topic:'fed' for polymarket_edge, series_id for fred_series, and detailed webhook delivery behavior. It goes well beyond the schema by explaining how each type maps to its params object.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb, resource, and purpose. It also notes it returns the subscription id, and the title 'Subscribe to Alerts' reinforces the action. This clearly differentiates it from sibling tools like list_subscriptions 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 gives clear context: it requires a Pipeworx OAuth account, states which types are supported, and describes delivery channels and constraints (verified phone, 10/day cap, webhook auto-disable). It does not explicitly name alternative tools for when to use list_subscriptions vs unsubscribe, but the prerequisites and supported types make appropriate use fairly obvious.

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, openWorld, idempotent, and non-destructive behavior; the description adds valuable context beyond that by disclosing the return structure (category-bucketed example questions with tool+argument shapes), the live-catalog source, and the optional topic-filter behavior. No contradictions with annotations are present.

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

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

The description is long and front-loaded with user-phrasing examples, but every part serves a purpose: scoping the tool, listing coverage areas, explaining the output, and specifying parameter behavior. It is somewhat dense and could be split into clearer sentences, but it avoids fluff and repetition.

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 simple complexity (one optional parameter, no output schema), the description is complete: it covers what the tool returns, how to invoke it with or without a topic, and when to use it. No important behavioral or usage aspects are missing.

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

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

The input schema already fully documents the single optional 'topic' parameter at 100% coverage. The description adds practical examples like 'finance', 'pharma', 'betting' and clarifies that omitting the parameter yields a cross-category spread, which meaningfully supplements the schema.

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

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

The description clearly identifies this as an onboarding tool for discovering what Pipeworx can do, returning category-bucketed example questions. It distinguishes itself from sibling tools like ask_pipeworx by explicitly positioning itself as the first-stop meta-tool that points users to exact tools and argument shapes.

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 provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains the no-arguments vs. topic-filtered call pattern. However, it doesn't explicitly name when-not-to-use alternatives such as ask_pipeworx, so it stops short of a full exclusionary guideline.

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 that the operation enforces ownership and performs a soft delete (deactivation) rather than a hard delete. This adds concrete behavioral detail beyond the annotations (e.g., destructiveHint=false) and informs the agent about the tool's side effects. The reference to historical events remaining available via recent_alerts is additional useful 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 two sentences, front-loaded with the action and followed by key behavioral constraints. Every sentence provides essential information without redundancy, making it highly concise and well-structured.

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

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

For a single-parameter tool with no output schema, the description covers the essential context: what it does, the ownership restriction, and the non-destructive effect with a pointer to related historical data. This is complete for the tool's complexity, and the annotations already cover idempotency and non-destructiveness.

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 a complete description for 'id' ('Subscription id (uuid) returned by subscribe'), so the description adds little parameter-specific semantic value. Since schema coverage is 100%, the baseline of 3 is appropriate—the description only reiterates that cancellation is by id without adding new constraints.

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

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

The description opens with 'Cancel a subscription by id,' using a specific verb and resource with the method. This clearly distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions.' The title reinforces the alert context.

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

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

The description explains the ownership constraint ('you can only cancel your own subscriptions'), giving clear context on when this tool applies. It also mentions the deactivation behavior and points to 'recent_alerts' for historical events, which helps with follow-up actions. However, it doesn't explicitly state alternatives or cases when not to use it, so it's not a perfect 5.

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

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

Goes well beyond the annotations by explaining the meaning of each verdict, especially the critical caveat that could_not_verify means the check did not happen and must not be presented as evidence. Also discloses the two verification pipelines, the percent-delta math, citation behavior, and the semantics of 'unsupported.' 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 front-loaded with trigger phrases, then logically organized into purpose, usage, return values, and an important caveat. Every sentence earns its place—no fluff—and the IMPORTANT warning is clearly highlighted. Length is justified by the tool's complexity.

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

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

Given there is no output schema, the description fully explains return values (verdicts, actual value with citation, reasoning) and handles edge cases (could_not_verify vs. unsupported). It also covers the two distinct execution paths and the efficiency benefit, making it complete for a complex tool.

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

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

Schema description coverage is 100% and both parameters already include detailed descriptions (e.g., tolerance_pct gives range, override semantics, and default). The tool description itself adds no additional parameter-specific meaning, so a baseline of 3 is appropriate.

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

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

The description uses a specific verb ('verify') and resource ('claim'), explicitly listing natural-language trigger phrases. It clearly distinguishes itself from siblings by describing the company-financial SEC EDGAR fast path versus the grounded pipeline for all other claims, and notes it replaces sequential calls. This makes the tool's purpose unambiguous and differentiated.

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 an explicit usage trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing (financial vs. other claims). However, it does not explicitly name alternative tools or state when not to use it (e.g., for general questions), so it falls short of a 5.

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