Seo Competitors

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 valuable context beyond annotations: the default model is Workers AI Llama-3.3-70b (free), Anthropic calls are BYO key and you pay directly, and the return structure is per-model {score, confidence, signals, raw_response} plus a combined view. No contradictions.

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

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

The description is three sentences, front-loaded with the main purpose, then details on model options and cost, ending with use cases. Every sentence contributes valuable information with no redundancy.

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

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

With no output schema, the description partially compensates by outlining the return structure (per-model score, confidence, signals, raw_response and a combined view). It also covers use cases and parameter nuances. It lacks details on how to interpret confidence or signals, but more is not necessary given the tool's scope.

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 semantic value by specifying the default model name (Workers AI Llama-3.3-70b) and the cost implication of using _apiKey (you pay Anthropic directly). This goes beyond the schema's basic parameter 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 probes LLMs for knowledge about an entity and scores visibility 0-100 per model. It uses specific verbs (probe, score) and identifies the resource (LLMs' knowledge). However, it does not explicitly distinguish from the sibling 'scan_competitor_ai_presence', which may overlap in use case.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains the default model and how to enable Anthropic via _apiKey. It does not mention when not to use the tool or name alternatives, but the usage context is clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: routing across 5,439 tools, returning stable pipeworx:// citation URIs, working on every tier, and making one fast call. 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?

The description is somewhat lengthy but well-structured; it leads with the key directive 'PREFER OVER WEB SEARCH' and organizes information into usage, alternatives, and examples. While it could be trimmed slightly, every section adds value and the flow is logical.

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

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

For a complex routing tool with no output schema, the description is impressively complete: it explains when to use, what it returns (structured answers with citations), how it handles broader questions, and gives multiple examples. An agent has sufficient context 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?

The input schema fully documents all 6 parameters with descriptions and aliases, achieving 100% coverage. The description provides examples of queries but adds no additional parameter-level guidance beyond what the schema already offers, 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 clearly states the tool's purpose: it answers factual questions by routing to a large set of specialized tools and returns structured answers with citations. It explicitly distinguishes itself as the default entry point from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

It provides explicit guidance on when to use this tool over web search, listing trigger phrases ('what is', 'look up', 'get the latest') and concrete examples. It also names specific alternatives (ask_pipeworx_grounded, deep_research) and conditions for stepping up, making usage guidelines exceptionally clear.

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

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

Beyond the readOnly/idempotent hints, the description adds key behavioral context: it is a beta with 'candidate routing improvements enabled live' when under test, currently no candidate is active (matching ask_pipeworx exactly), and it 'is a full working router' with no fallback. This clarifies variability, temporal state, and scope, adding significant value over 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 compact (four sentences) and front-loaded with 'Beta version of ask_pipeworx'. Each sentence contributes uniquely: beta status, current no-candidate state, usage instruction, and refutation of fallback misconception, with no wasted words.

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

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

Given no output schema, the description provides strong context about the tool's nature (beta, full router), current state, and usage, referencing 'same response shape' as ask_pipeworx. It does not explicitly state what the router returns, but relies on ask_pipeworx's existing documentation and the 'identical' claim, which is adequate for this experimental variant.

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%: all six parameters are aliases, and the 'question' parameter has a thorough description explaining they are interchangeable. The tool description adds no parameter-specific semantics ('same arguments' only), 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 this is the beta version of ask_pipeworx, an 'identical universal router' with experimental routing improvements. It distinguishes itself from the stable ask_pipeworx and other siblings by being the experimental edge, making its purpose and differentiation 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?

The description instructs to 'use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared to the stable router. It does not explicitly mention when not to use it or name an alternate stable tool, though the sibling list and 'stable router' reference imply the alternative.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses the internal workflow (picks tool, fetches data, extracts), the exact return shape including refusal_reason enum, and the failure/refusal conditions. This adds substantial context 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?

The description is front-loaded with the core value proposition, then details output format, usage guidance, and cost trade-off. Every sentence adds meaningful information—no filler. The length is justified by the tool's complexity, and the structure is logical 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?

With no output schema present, the description fully explains return values (answer, evidence, confidence, source, etc.) and refusal reasons. It also covers when to use, cost, and relationship to the sibling tool, making it self-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 input schema already documents all six parameters as aliases for the single 'question' parameter with clear descriptions (100% coverage). The description doesn't add parameter-specific details beyond the schema, but the baseline of 3 is appropriate since the schema carries the semantic load.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' that routes tool calls and extracts answers using only the tool result. It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing groundedness and the explicit refusal mechanism. The verb+resource is specific: it returns a grounded answer with evidence.

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: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' Also names the alternative and highlights the cost trade-off ('costs one extra LLM call'), providing clear decision guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds far more: fan-out patterns, response shapes, resolver contract (match confidence, alternatives), safety short-circuit for low-confidence matches, closed/inactive market handling, illiquidity flags, and cancellation-rule parsing. This exceeds annotation coverage and provides the agent with essential operational details.

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

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

The description is long and dense, but it uses all-caps section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) to preserve scannability. The core purpose is front-loaded in the first sentence. It still could be tightened with bullet points or a brief summary, so it doesn't earn a 5.

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

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

With no output schema, the description fully specifies return structures (result.market, result.analysis, result.evidence), status flags, resolver match confidence, parent_event extraction, and news fallback fields. It also covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules, making it exceptionally complete for a complex research tool.

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

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

Schema coverage is 100% and all parameters are documented, but the description adds valuable nuance beyond the schema: it explains the practical effect of 'depth' with fan-out examples, and for 'include_raw' it quantifies the trade-off (summarized evidence under ~20KB vs. full payloads 50KB-500KB). This helps the agent decide when to set the flag.

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+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by focusing on Polymarket bet research and explicitly lists accepted input formats (slug, URL, question text).

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

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

Explicitly tells when to use the tool with 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples and warns to check cancellation rules before sizing sports bets. However, it does not explicitly name alternative tools or define when-not-to-use, so it falls slightly 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?

The description adds rich behavioral context beyond the safe-read annotations: it discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, output format (paired data + citation URIs), and performance benefit (replaces 8–15 sequential lookups). 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 longer than average but every sentence is informative: trigger phrases, use-case priority, data sources, sorting, output, and performance impact. It is front-loaded with usage examples and structured logically. A slight trim could help, but the complexity justifies the length.

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 complex (two entity types, multiple data sources, no output schema) and the description covers all key aspects: what data is pulled, how results are sorted, what output to expect (paired data + URIs), and when to prefer it. It gives enough context for an agent to select and invoke it correctly without needing additional details.

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

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

Schema coverage is 100% with descriptions for both parameters, providing a baseline of 3. The description adds extra meaning: it explains what each type pulls (financial metrics for 'company', adverse-event counts for 'drug') and gives examples for values (tickers/CIKs, drug names). This exceeds the schema's basic enum and array descriptions, enhancing parameter understanding.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in a single call. It provides explicit trigger phrases like 'Compare X and Y' and 'rank these companies', and distinguishes itself from sequential single-pack lookups, likely sibling tools like entity_profile.

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

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

The description explicitly states when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups' and provides concrete query examples. It implies when-not-to-use (when not comparing entities) but does not name specific alternative tools, though 'sequential single-pack lookups' is a clear contrast.

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 auth requirements (free sign-in, paid for thorough), parallel decomposition behavior, return packet contents (verbatim evidence, confidence, source, fetched_at, stable citation), explicit gaps[] with no fabrication, contradictions[] scan, semantic excerpting of large records, and expected latency. No contradiction with readOnly/openWorld/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 long but dense with critical information, front-loaded with the account requirement and alternative routing. Every sentence adds value, though some depth parameter details are redundant with the schema; the length is justified by tool 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 the tool's complexity and lack of an output schema, the description thoroughly covers what to expect, when to use it, limitations, fallback paths, and advanced depth behavior. It fully equips an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'question' can be broad/multi-part and that 'depth' includes hop behavior, gap recovery, contradiction scan, and latency implications beyond the schema's enum descriptions.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources in one call, with specific verbs and resource scope. It also distinguishes itself from siblings by explicitly noting it is NOT open-web search and comparing itself to 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 when-to-use guidance: use ask_pipeworx for single lookups, for breaking/colloquial current news, or when signed out. It also explains the depth tiers for multi-step questions, giving clear alternative and exclusion scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral details: it returns names, descriptions, and full input schemas with curated examples, and says no second schema lookup is needed. It does not mention rate limits or error handling, but for a read-only discovery tool the added return-format context is valuable.

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

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

The description is three sentences, each with a distinct purpose: defining the core purpose, listing supported domains, and explaining the return value with usage positioning. The domain list is somewhat lengthy but serves the tool's discovery function. It is front-loaded with the most important information, so it earns a 4 rather than a 5.

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

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

Despite lacking an output schema, the description explicitly states what the tool returns (top-N tools, names, descriptions, schemas) and that results are directly callable. It also gives usage context (call first when many tools available). With 100% parameter schema coverage and strong annotations, the description is complete and self-sufficient.

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

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

Schema coverage is 100%, and the schema already explains the 'query' parameter as a natural language description and documents all aliases (q, task, search, description) and the 'limit' parameter. The description does not add additional semantic meaning beyond what the schema provides; it simply reinforces that queries describe data or tasks. 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 'Find tools by describing the data or task', which clearly states the verb (find), the resource (tools), and the mechanism (describing data/task). It lists many domains (SEC filings, FDA drugs, etc.), making the tool's scope concrete. It is clearly distinct from siblings like deep_research or entity_profile because it is a meta-tool for discovering other tools.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' — a clear when-to-use. It also states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', which provides both a strong trigger and an implicit when-not (avoid if you need a single direct answer). It even clarifies that returned tools are ready to call directly, supporting the workflow.

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 reveals behavioral details beyond the readOnlyHint/idempotentHint annotations, such as fanning out across multiple sources (SEC, XBRL, USPTO, GDELT→GNews, GLEIF), the patents API sunset soft-fail, and the exact output structure. No contradictions with annotations.

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

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

The description is dense but well-organized: it front-loads example queries, then explains scope, return fields, and constraints. Slightly long, but each clause adds necessary context for this complex tool.

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

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

Given the lack of an output schema, the description thoroughly details every returned component (CIK, company name, filings with URIs, fundamentals, patents, news, LEI) and specifies input limitations (US public company, ticker/CIK only). This is complete for a profile tool.

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

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

The input schema already describes both parameters with examples and format constraints (ticker vs CIK, names not supported). The description essentially repeats the same information, so it adds no additional semantic value beyond the schema.

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

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

The description clearly defines the tool's purpose: generating a 'full cross-source profile of a US public company'. It uses specific example queries and explicitly distinguishes itself from sibling tools by 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?

Provides explicit trigger phrases like 'Tell me about X' and 'research Acme', and states when not to use it: 'names not supported (use resolve_entity first if you only have a name)'. It also contrasts with alternative single-pack lookups, offering clear usage direction.

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 readOnlyHint=false, so the description doesn't need to restate basic safety. It adds context that deletion is intended for stale or sensitive data, which helps the agent reason about consequences. No contradiction with annotations, but it could explicitly state permanence or error behavior for non-existent keys.

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

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

Two sentences, front-loaded with the primary action. The first sentence states the function, the second gives usage guidance. No wasted words, perfectly sized for this simple 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?

The description covers what the tool does, when to use it, and complements the single required parameter. Annotations handle safety flags (destructive, idempotent), and no output schema is needed. For a one-parameter memory deletion tool, this is complete and well-contextualized.

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 'key' described as 'Memory key to delete'. The description only says 'by key', adding no additional meaning about key format or behavior beyond the schema. Baseline 3 applies since the schema fully documents the parameter.

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. The verb 'delete' and resource 'memory' are specific, and the use of 'previously stored' distinguishes it from create/read operations of sibling tools, implying a distinct action from remember and recall.

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 gives conditions for use: stale context, task done, or clearing sensitive data. It also mentions pairing with remember and recall, providing clear context without naming alternative tools but implying 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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by explaining that it fetches the page, extracts specific elements, and returns a single text blob in standard llms.txt markdown format, which goes beyond the annotation-only safety profile.

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 well-structured sentences: first states the purpose, second describes the process, third gives the output format and use cases. No wasted words, and the key information is front-loaded.

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 two parameters and no output schema, the description covers purpose, process, output format, and typical use cases. It does not address error handling or edge cases, but the annotations and schema adequately cover the remaining 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 input schema already provides full descriptions for both parameters (url and max_links), so the baseline is 3. The description mentions extracting key links, which indirectly relates to max_links, but does not add explicit parameter semantics beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the exact process (fetches page, extracts title/description/key links, emits markdown). This distinguishes it from siblings like scan_competitor_ai_presence or seo_domain_ranked_keywords by focusing specifically on llms.txt generation.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing competitor AI visibility. It gives clear context for when to use the tool but does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing safe read behavior. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and the default filtering to active subscriptions, which gives the agent concrete expectations beyond annotation hints.

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

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

Two sentences, front-loaded with purpose and immediately followed by return fields and usage guidance. Every sentence contributes meaning, with no redundancy or filler. This is exemplary 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?

The tool is simple (1 optional param, no output schema), and the description covers purpose, return fields, and usage context. Annotations handle safety traits, and sibling tools (subscribe/unsubscribe) provide surrounding context. The description is sufficient 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?

The input schema covers the sole parameter (include_inactive) with 100% clarity, so the description doesn't need to explain it. The phrase 'active subscriptions' does implicitly align with the default false of include_inactive, but this is marginal added value over the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb ('List') and resource ('subscriptions') with an explicit scope ('caller's active'). It distinguishes from sibling tools like subscribe and unsubscribe by being the listing counterpart.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke it relative to subscribe/unsubscribe actions. However, it doesn't explicitly name alternative tools or state when not to use it, 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?

The description discloses rate limits (5 per identifier per day), that it is free and does not count against quota, that the team reads digests daily, and that signal affects roadmap. These behavioral details go far beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false. 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 detailed yet every sentence earns its place: purpose, use cases, exclusion, identification method, style guideline, team impact, and rate limit. It is front-loaded with the core action and uses bold/uppercase for critical constraints, making it scannable. No redundancy.

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

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

For a feedback tool with 3 parameters, no output schema, and no complex return values, the description is fully complete. It covers what, when, why, how, and operational constraints. It also addresses likely confusion (which tools qualify) and sets expectations about digest processing. 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?

Schema coverage is 100%, so the parameters are well-documented. The description adds valuable semantics on how to write the message (don't paste user prompts, be specific about tool/error/data gap), which goes beyond the schema. It does not repeat schema descriptions but enriches the 'message' parameter guidance. A slight deduction because the context object's schema is already self-explanatory.

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: telling the Pipeworx team about broken, missing, or desired functionality. It enumerates specific feedback types (bug, feature, data_gap, praise) and explicitly scopes to Pipeworx tools, distinguishing it from all sibling tools. The verb 'tell' and resource 'Pipeworx team' make the action 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?

Usage guidance is exemplary: it specifies when to use (bug, feature gap, praise), when NOT to use (tools from other MCP servers), and what to do instead (file with that server). It also instructs on how to frame feedback (in terms of Pipeworx tools/packs, not user prompts), providing complete decision-making criteria.

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

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

The description adds caching behavior ('Cached 5min-1h depending on window'), data provenance ('derived from CF analytics-engine, no PII'), and aggregation characteristics ('Self-aggregating signal'). These go beyond the readOnlyHint/idempotentHint annotations, though it does not disclose rate limits or auth requirements (not applicable given read-only nature).

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

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

The description is four sentences, each with a clear purpose: what it returns, when to use it, data source, and caching. It's front-loaded with the main purpose and contains no redundant phrases.

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

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

Despite lacking an output schema, the description covers what is returned (top tools, top packs, total call volume, and record shape as pack/tool/count). Combined with comprehensive annotations and the single optional parameter, the description fully equips the agent to invoke and interpret the tool.

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

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

The window parameter is fully documented in the schema (enum with default and guidance on short vs long windows). The tool description merely restates the window values without adding new meaning, so it doesn't elevate beyond the baseline for 100% 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 first sentence clearly states what it does: 'Returns the top tools, top packs, and total call volume over a recent window.' It distinguishes itself from siblings by focusing on aggregate call trends from other AI agents, which is unique among the listed 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 concrete use cases ('Useful for: ...') that indicate when to use the tool, but does not explicitly name alternatives or exclusion criteria. It explains the value for current events, canonical tool selection, and alignment checking, which gives clear context for usage.

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

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

Annotations already mark readOnlyHint/idempotentHint; description adds deep behavioral context: explains partition_check sums, Jaccard similarity threshold, placeholder filters, fill check with realizable vs theoretical edge, and instructs 'do not trade it' when realizable edge ≤ 0. No contradictions.

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

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

Long but structured: purpose, modes, internal checks, response, fill check. Each section adds operational detail, though slightly redundant in repeating partition_check 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?

No output schema, but description enumerates response fields and fill check behavior, compensates fully. Covers modes, filters, similarity thresholds, and actionable trading guidance.

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 documents 100% of parameters with descriptive text; description enhances with concrete examples (event slugs, seed questions) and clarifies mode-specific behavior. Since schema coverage is high, a score of 4 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?

States 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' — a specific verb+resource+method. It also distinguishes modes (event/topic/trending) and mentions alternative for custom sizing (polymarket_fill_risk), clearly separating from siblings.

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

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

Provides explicit mode selection: no args for trending_scan, event for a specific market, topic for cross-event scanning. Recommends event for specific market and outlines cross-event use cases. Also states 'For custom sizing use polymarket_fill_risk', an alternative tool.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description goes well beyond by disclosing caching behavior ('Cached 1h at the KV level'), response segmentation, diagnostics for empty segments, the 24h-move warning, and the logic behind tradeable-edge knobs. This adds substantial context that annotations do not cover.

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

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

The description is well-structured with thematic sections, but it is overly long and includes implementation-specific details (e.g., per-sport alphas, 'Run 8' thresholds) that may not be essential for tool selection. It is adequately organized but wordy, making it less concise than ideal.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), edge calculations, filters, and caveats. It provides enough information for an agent to understand what results to expect and how to interpret them, leaving no major 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 detailed parameter descriptions, and the tool description additionally explains how parameters interact, e.g., the relationship between min_kelly and min_partition_leg_kelly for partition arbs, slippage_pp context, and the tradeable-edge filter semantics. This enriches parameter understanding beyond the schema.

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

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

The first sentence clearly states the verb ('Scan top Polymarket markets') and resource ('return opportunities where Pipeworx data disagrees with market price'), establishing a specific, differentiated purpose. The detailed segmentation further distinguishes it from sibling tools like polymarket_arbitrage.

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

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

Explicitly describes the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains why certain candidates (Fed bets) are excluded from ranking, providing clear context. However, it does not explicitly mention alternative tools or when not to use this one.

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

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

The annotations already declare readOnly, idempotent, openWorld, and non-destructive traits. The description adds substantial behavioral context beyond that: history depth bounded by 60-day snapshot TTL, snapshots written only on cache-miss (explaining gaps), decay computed from daily closes of edge_pp_net (net of slippage) rather than intraday, and the interpretation of expired[] opportunities. These are valuable specifics that the annotations do not 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 moderately long but well-structured into clear sections: purpose, args, response, and limits. Every sentence adds value, explaining not just what but why (e.g., 'the median lifespan is your competition clock'). It is front-loaded with the core question and then details. The length is justified by the complexity of the tool, though it could be slightly tightened without losing meaning.

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

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

Given that there is no output schema, the description thoroughly covers the return structure (tracked[], expired[], snapshot_dates[]) with field names and meanings. It also explains data caveats (TTL, snapshot gaps, daily vs intraday) and how to interpret expired opportunities. The tool has only 2 parameters, and the description and schema together fully cover its usage and behavior, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% (both days and window have descriptions). The description reiterates the parameters (days lookback, default 14, max 30; window family default '1wk') but adds little new semantic meaning beyond what the schema provides. It does clarify that window refers to a 'snapshot family', but that is also in the schema. The baseline of 3 is appropriate since the schema already documents the parameters well.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling tool polymarket_edges by focusing on time-series persistence rather than current edge values. The verb 'tracker' and resource 'edge persistence/decay' make the purpose specific and unambiguous.

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

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

The description provides clear context for when to use the tool: when you need to know an edge's lifespan and decay. It contrasts a fresh wide edge with a 3-week-old one, implying this tool is for evaluating edge longevity. However, it does not explicitly name alternative tools or state when NOT to use it, which would warrant a 5. Still, the context is sufficiently clear.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds extensive behavioral context: it walks the order-book ladder, returns specific metrics (vwap_fill_price, slippage_pp, shares_filled), warns about partial fills and strand risk, and details basket-mode settlement notional. This goes far beyond the annotation hints and provides real operational transparency.

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

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

The single dense paragraph is front-loaded with the core purpose, then clearly partitions SINGLE-MARKET and BASKET modes. Every sentence carries specific information: defaults, output fields, risk caveats, and use-case trigger. There is no padding; the 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 the tool has two modes, no output schema, and 4 parameters, the description enumerates all relevant return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs[], forced_directional_risk, etc.), explains the risk model, and specifies the ~$500 threshold. This is a complete operational picture for an agent.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the dual mode of `market` vs `event`, the default and permuted meanings of `side` per mode, and the nuanced interpretation of `size_usd` (max spend on buys, target proceeds on sells, settlement notional for baskets). This provides semantic richness beyond the schema's brief property descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates between single-market and basket modes, and the title+use case distinguishes it from siblings like polymarket_arbitrage, polymarket_edges, and polymarket_kalshi_spread.

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 tool explicitly instructs when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert an arb into unhedged directional position). This is exemplary usage guidance with alternatives and rationale.

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 readOnlyHint, openWorldHint, and idempotentHint, the description discloses rich behavioral detail: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the statement that aligned:false makes spreads 'mathematically meaningless.' This far exceeds what annotations already provide.

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

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

The description is long but densely packed and logically structured with labels like TWO MODES, RESPONSE, SAFETY FIELDS, and temporal_alignment. Every sentence contributes new information, and the opening sentence front-loads the core purpose.

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

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

Given the tool's complexity, the absence of an output schema, and optional parameters, the description is remarkably complete. It covers return values, safety warnings, edge cases, and interpretation caveats, making it self-sufficient for correct invocation.

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

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

Although schema coverage is 100%, the description adds significant parameter semantics by explaining the two-mode interaction: topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug overrides. It also provides concrete examples and clarifies that pre-mapped does not guarantee tradeability.

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 immediately defines the tool as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource combination. It also distinguishes this from sibling tools like polymarket_arbitrage by focusing on the dual-venue comparison and explicitly outlining two operation modes.

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

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

The description provides clear when-to-use context: it explains that the spread is a real signal only when bet shapes are equivalent, and explicitly warns via compatibility_warning when shapes are non-equivalent or temporally misaligned. It does not name alternative tools directly, but the mode guidance and tradeability caveat give strong usage direction.

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 and non-destructive behavior. The description adds useful context about scope ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual modes (retrieve vs. list). It does not elaborate on return formatting or missing-key behavior, but that is acceptable for a simple retrieval tool.

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 function, followed by usage context and sibling pairing. Every sentence adds value with no redundancy.

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

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

For a tool with a single optional parameter and no output schema, the description covers purpose, usage, and scope. It could mention return behavior for missing keys, but the 'list all saved keys' mode implicitly covers that. The description is nearly complete for the tool's simplicity.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The description goes further by giving concrete examples of what keys may contain (target ticker, address, prior research notes), enriching the semantic understanding beyond the schema.

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

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

The description opens with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and also identifies the alternative mode ('list all saved keys'). It clearly distinguishes the tool from sibling tools like 'remember' and 'forget' by name.

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?

States explicitly when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and provides pairing guidance ('Pair with remember to save, forget to delete'). Also notes the optional key argument for listing keys.

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

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

Annotations already indicate readOnlyHint and idempotentHint, so the description's extra detail about mark_read side effects and the persisted feed adds valuable context. The description is transparent about the optional write behavior (mark_read) and the feed's persistence. No contradiction with annotations is found.

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 sentence adds value (return payload, filtering, mark_read, polling/alternative endpoint). No redundant or filler content.

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

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

Despite no output schema, the description explains the return structure (source, citation_uri, payload), filtering options, mark_read behavior, and even provides a fallback HTTP endpoint. For a tool with 5 optional parameters and no nested objects, this is a fully complete description.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds an example for type (e.g., 'sec_8k') and clarifies the semantics of mark_read. This goes slightly beyond the schema descriptions, improving parameter understanding for the agent.

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: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts the evaluator has written to your persisted feed.' It specifies the resource (subscription feed) and mentions key data fields (source, citation_uri, payload), distinguishing it from siblings like recent_changes or list_subscriptions.

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

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

The description gives clear context for use, such as filtering by type and since, and explains mark_read behavior for polling. It also mentions the HTTP endpoint as an alternative for scripts/dashboards, which is a form of alternative guidance. However, it does not explicitly name sibling tools or state when not to use this tool, stopping short of a perfect score.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses important behavior: fans out to multiple sources, GDELT preferred with GNews fallback on rate limiting or 5xx, and the PatentsView API sunset causing USPTO to soft-fail until reactivated. It also states the return structure and citation URIs, adding substantive transparency about 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 well-structured and front-loaded: begin with user-intent phrases, then a one-line definition, followed by source details, parameter examples, return format, and an alternative tool. Every sentence adds value and the length is appropriate for a tool with multiple data sources and fallback behavior.

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 responsibly explains the return shape ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers input nuances, fallback behavior, and the relevant alternative, making the tool fully usable without needing to infer details beyond annotations and schema.

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

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

The schema already documents all three parameters (100% coverage), so the baseline is 3. The description adds practical value by giving explicit examples of the `since` parameter ('2026-04-01', '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring, clarifying how the parameter maps to the source windows.

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 intent-matching paraphrases and then clearly states it is a 'change feed for a company in the last N days/weeks/months' that fans out to SEC EDGAR, GDELT/GNews, and USPTO. This specific verb+resource definition distinguishes it from the sibling tool entity_profile, which is explicitly called out as the alternative for static profiles.

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

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

The description provides explicit when-to-use context through example queries and states 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This directly guides tool selection and names the alternative, exceeding the baseline for usage guidance.

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

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

The description adds meaningful behavior beyond annotations: persistence details (authenticated vs anonymous sessions, 24-hour retention) and scoping by identifier. This complements the idempotentHint and destructiveHint annotations without contradiction, informing the agent about memory lifetime and visibility.

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: the first sentence states core purpose, followed by usage criteria, storage format, persistence details, and companion tools. Every sentence earns its place with no redundancy.

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

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

For a simple two-parameter write operation, the description covers purpose, key-value structure, retention behavior, scoping, and relationship to recall/forget. No output schema is needed for a store operation, and annotations cover safety traits. The tool is fully contextualized.

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 offers examples of key-value content (e.g., 'resolved ticker', 'user preference') that reinforce the schema's parameter descriptions but do not add substantial new semantics beyond what the schema already provides.

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

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

The description clearly states the tool saves data for later reuse across conversations or sessions, using a specific verb ('Save') and resource ('data... key-value pair'). It distinguishes itself from siblings by pairing with 'recall' and 'forget' and giving concrete use cases like resolved tickers or user preferences.

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 when you discover something worth carrying forward' and provides example triggers. It also names complementary tools ('Pair with recall to retrieve later, forget to delete'), giving clear context on when this tool is appropriate relative to alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context about return fields (ticker, CIK, RxCUI, etc.), citation URIs, auto-disambiguation, and internal cascading of multiple lookups, which goes beyond basic safety 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 densely packed with useful information in a compact space. It starts with example queries, then clearly states the purpose and usage, and efficiently breaks down supported types. No wasted words.

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

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

Given the tool complexity (two entity types, distinct outputs, no output schema), the description fully covers return values for both types, cites internal behavior, and explains how it fits into the broader tool ecosystem. It is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, but the description adds extra meaning by detailing what each type returns and the accepted input forms (e.g., ticker/CIK/name for company, brand/generic for drug). This enhances the schema's basic descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers required by other tools, with specific verbs and resource. It distinguishes from siblings by explicitly noting it provides identifiers other tools need, and gives concrete example queries.

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

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

Provides explicit when-to-use guidance via 'Use FIRST whenever you have a name but need an ID.' It does not name specific alternatives or state when not to use, but the context is clear and implies if you already have an ID, this tool is unnecessary.

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 meaningful behavior beyond that: it is a composite tool that probes each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. This conveys the multi-step, aggregative behavior not present in 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 focused sentences: what it does, how it does it, and what it returns. Every sentence adds value, no fluff, and the purpose is front-loaded. The use-case question is a nice touch without adding length.

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

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

With no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It explains the composite behavior and the expected inputs conceptually. It could go deeper on interpreting confidence or signal density, but overall is complete enough for a tool of this moderate 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 description coverage is 100%, so all parameters have detailed descriptions (entities, models, _apiKey, context). The tool description adds no new parameter-level meaning beyond what the schema already provides, such as explaining the 'subject/competitors' distinction already covered in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This is a specific verb+resource outcome and differentiates from sibling tools like the singular ai_visibility_check or generic 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 names the use case ('competitive AI-marketing audits') and provides a concrete example question. It implies the tool is for multi-entity comparison and references ai_visibility_check as the underlying probe, but does not explicitly state when NOT to use it (e.g., single-entity checks). This is clear context, but lacks formal 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 flag readOnly, idempotent, etc., but the description goes further by disclosing timeout behavior (bundlephobia first measurement 5-30s), graceful degradation, and the sources_failed field. This adds meaningful behavioral context beyond the annotations, with 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 well-structured and front-loaded with the core purpose. Every sentence earns its place: it covers purpose, usage triggering, ecosystem scope, output contents, and failure handling without fluff. Despite length, it's appropriately dense for a composite tool.

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

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

Given there is no output schema, the description details the return fields (summary block, per-advisory detail, links, recent versions) and notes partial failures. It also covers ecosystem limitations and performance characteristics, 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?

The input schema already has 100% coverage with descriptions for both package and version. The description does not add significant new parameter meaning, only restating what the schema already conveys. Baseline of 3 is appropriate given the 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+resource: 'Composite should I add this npm package to my project check in ONE call' and details the data sources (deps.dev, bundlephobia). This clearly distinguishes it from sibling tools like deep_research or validate_claim by focusing on npm dependency evaluation.

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 the tool ('Use whenever an agent asks...') and names alternatives for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This gives clear guidance on tool selection versus alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent; description adds embedding model details (BGE-base-en, cosine, 500-char windows), the 200K char cap with truncation flag, and the guarantee that passages carry offsets for verbatim quote verification. 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?

Four well-organized sentences; each clause adds value: purpose, use-case, pairing, and technical limits. No filler words; front-loaded with the core function.

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 (semantic search, windowing, truncation, pairing), the description covers return format (passages, offsets, similarity), max input size, usage context, and relationship to sibling tools. Complete despite no output schema.

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

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

Schema covers all three parameters with descriptions (100% coverage). Description reinforces with query examples and contextual hints, but adds no major new parameter semantics beyond the schema's existing 'max ~200K chars' and 'natural-language query' definitions.

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

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

Description states 'Semantic search INSIDE a fetched record' with explicit verb+resource, and describes passing text plus query to get passages. It distinguishes from siblings by framing as operating on already-fetched text rather than querying a database.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains the pairwise workflow with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages'). This clearly identifies when to use and an alternative integration pattern.

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

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

With annotations declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds value by specifying the exact return fields (search volume, current rank, ranking URL). It also provides a usage example, offering practical insight 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 compact and front-loaded with the purpose. It uses a clear question-answer format, includes a labeled example, and every sentence contributes meaning. No redundant information.

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

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

The tool is a read-only list query with all parameters documented in schema and annotations covering safety. No output schema exists, but the description explicitly states the return fields, making the tool's behavior fully understandable. The example further enhances completeness.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description's example illustrates parameter usage but adds little semantic meaning beyond the schema. Baseline of 3 is appropriate; no additional parameter explanations are provided.

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 with a specific verb ('returns') and resource ('keywords a domain ranks for in Google organic'). It includes output details (search volume, current rank, ranking URL) and a concrete example, making it distinct from sibling tools like entity_profile or scan_competitor_ai_presence.

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

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

The description provides clear usage context ('Competitor SEO intelligence') and an example call. It implicitly signals when to use the tool (for analyzing domain keyword rankings) but does not explicitly list alternative tools or exclusions. Thus it is clear on context but lacks explicit comparisons.

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 meaningful behavioral context beyond annotations: OAuth requirement, phone verification, 10/day SMS cap, and persistent feed retrieval path. Annotations already indicate mutation (readOnlyHint=false) and idempotency, and the description does not contradict these. It lacks side-effect warnings like subscription limits but covers key operational constraints.

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, using lists for subscription types and delivery channels. It front-loads the purpose and return value, then details prerequisites and options. Every sentence contributes, though some redundancy with the schema is present (e.g., delivery email/sms examples).

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 (5 types, multiple delivery channels, auth requirements) and a rich schema covering webhook details, the description covers the primary aspects: purpose, return, auth, key parameters, and feed retrieval. It omits webhook specifics and some type details, but the schema fills those gaps, making it complete enough 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 baseline is 3. The description adds value by explaining example parameter shapes (items:['5.02']=officer change, topic:'fed', series_id:'UNRATE') and clarifies delivery channel semantics, enriching the schema's type-specific guidance.

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

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

The description clearly states the verb 'Create a proactive monitoring subscription to a live-data event stream' and identifies the returned value (subscription id). It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and provisioning of alert channels.

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

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

Provides clear context on when to use (requires OAuth account, anonymous/BYO cannot persist) and elaborates on subscription types with examples. The description contrasts the always-on feed with optional email/sms channels, and mentions retrieval via recent_alerts, giving practical usage direction. However, it does not explicitly name alternative tools like list_subscriptions for viewing existing subscriptions.

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

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

Annotations already provide read-only, open-world, idempotent, and non-destructive hints, so the bar is lower. The description adds meaningful behavioral context beyond annotations: it explains the return structure (category-bucketed examples with tool+argument shapes), that results are drawn from a live catalog, and that the tool is an onboarding entry point. This is more substantial than typical read-only descriptions, though it doesn't cover edge cases like invalid topics or response format limits.

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 minimal examples, every clause earns its place: it front-loads with user-style queries, explains the return value, gives parameter guidance, and includes usage context. The structure is a compact paragraph that packs all essential information without redundancy.

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

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

Given a single optional parameter, rich annotations, and no output schema, the description fully covers the tool's purpose, return content, parameter semantics, and when to use it. It also contextualizes the tool within the broader catalog by referencing meta-tools. 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%, so the baseline is 3. The description mentions topic with examples ('finance', 'pharma', 'betting') and says omitting it gives a cross-category spread, but the schema itself already describes the same focus areas and the omit behavior. Thus the description adds little meaning beyond what the schema provides.

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

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

The description clearly states what the tool does: it is the onboarding entry point for an agent that wants to know what to ask Pipeworx, returning category-bucketed example questions with exact tool and argument shapes. It also lists natural-language triggers (e.g., 'what can I ask Pipeworx?') and distinguishes its role from other tools by mentioning how to learn to call meta-tools.

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

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

The description explicitly says to use this FIRST when the agent doesn't know what Pipeworx can do or needs to learn meta-tool usage. It provides clear call guidance (no args for full spread, pass topic to focus) and names alternative/related tools (ask_pipeworx, entity_profile, compare_entities), giving strong contextual direction for when this tool is appropriate.

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

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

The description adds key behavior beyond the annotations: ownership enforcement and deactivation-not-deletion. It also ties to recent_alerts for historical events, which is valuable context. Annotations already indicate non-read-only and non-destructive, and the description aligns without contradiction.

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

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

Two sentences, front-loaded with the action verb, then a concise explanation of side effects. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers the purpose, side effects, and ownership constraint. It is sufficient for an agent to decide invocation and anticipate the outcome.

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 fully covers the single 'id' parameter with its description 'Subscription id (uuid) returned by subscribe.' The description only says 'by id,' adding no new meaning beyond the schema. 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 uses the specific verb 'Cancel' with the resource 'subscription', clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. It also clarifies the deactivation behavior, further differentiating the effect.

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

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

The description implies the use case of stopping alerts for a subscription you own. It mentions ownership enforcement and the deactivation behavior, providing clear context for when to use it. However, it doesn't explicitly name alternative tools or exclusion scenarios, 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=true and destructiveHint=false. The description adds valuable behavioral context: the verdict values (confirmed, approximately_correct, refuted, inconclusive, unsupported), the inclusion of the actual value with a citation, and reasoning. It also mentions replacing 4–6 sequential calls, which is a performance trait not captured 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 a dense paragraph of four sentences, each addressing a distinct aspect: triggering phrases, usage context, routing logic, and output/benefit. It's front-loaded and well-organized, but slightly longer than necessary; it could be tightened without losing information.

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

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

The description covers the tool's purpose, usage, routing, output contract (verdict types and citation), and performance advantage. Given there is no output schema, it provides sufficient detail for an agent to invoke correctly. It doesn't elaborate on error edge cases, but the verdict values including 'inconclusive' and 'unsupported' cover the main scenarios.

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

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

Schema description coverage is 100% with detailed descriptions for both parameters, including tolerance_pct's override behavior and range. The tool description adds context about the 'exact percent-delta math' but doesn't meaningfully extend parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, returning a verdict. It distinguishes from siblings by focusing specifically on fact-checking with verdict outcomes, rather than open-ended research or entity lookup.

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 provides a when-to-use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delineates two routing paths (company-financial vs. other claims). It doesn't explicitly name alternatives or exclusions, but the context is clear for an agent to choose this over broader research tools.

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