Design Feeds

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. Description adds behavioral context: default model is free, Anthropic requires own key, and return structure includes per-model {score, confidence, signals, raw_response} plus combined view. No contradictions. This additional info helps an agent understand side effects (none) and key requirements.

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

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

Description is concise (two dense sentences plus a list) with no wasted words. It front-loads the core action and then adds parameter details and use cases efficiently.

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

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

Given the tool's complexity (4 parameters, no output schema), the description fully explains its purpose, parameters, return structure, and typical use cases. It provides enough information for correct invocation without additional context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful guidance: explains that 'models' default to workers-ai, that '_apiKey' is only needed for Anthropic, and that 'context' disambiguates common names. This goes beyond schema descriptions and helps correct parameter usage.

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

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

Description clearly specifies the verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100) per model'. It distinguishes from sibling tools by focusing on brand visibility across multiple models, not Pipeworx-specific or entity profile tools. Use cases are explicitly listed: AI-marketing audits, pre-launch brand checks, competitive monitoring.

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

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

Description states when to use this tool via listed use cases. It does not explicitly mention when not to use or provide alternatives, but the purpose and scope are clear enough for an agent to infer appropriate contexts.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: tool routes the question, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. No contradiction with annotations; it supplements them with routing and citation behavior.

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

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

The description is front-loaded with the most important guidance but becomes lengthy and somewhat garbled in the middle, especially the section starting 'default entry point, works on every tier, one fast call...'. It contains valuable detail but would benefit from tighter organization and cleaner transitions.

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

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

The description is complete for the tool's role as a general factual-question router: it covers scope, examples, alternatives, return format, and citation behavior. Without an output schema, the description still tells the agent what to expect. Minor vagueness about exact response formatting prevents a 5.

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

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

Schema description coverage is 100%, and every parameter is an alias for the same natural-language question field. The description does not need to explain parameter semantics further since the schema already documents the question/aliases. The description's examples reinforce usage but add little 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 that ask_pipeworx routes factual questions to one of 5,798 tools across 1,517 verified sources and returns structured answers with citation URIs. It names a specific verb, resource, and scope, and it distinguishes itself from web search and 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?

The description explicitly says to prefer this tool over web search for authoritative structured data, lists trigger phrases and concrete examples, and states when to step up to ask_pipeworx_grounded or deep_research. This gives an agent clear routing rules and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely valuable behavioral context beyond that: candidate improvements are 'enabled live whenever one is under test,' no candidate is currently active (retired 2026-07-26, so it matches ask_pipeworx), results feed merge decisions against the stable router, and it 'falls back to nothing' — it is a full working router. This is exactly the experimental-context disclosure a beta tool needs.

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

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

Four sentences, front-loaded with identity and current state before usage guidance. Each sentence carries distinct content — identity, live-candidate status, usage condition, and no-fallback guarantee. The parenthetical '2026-07-26' date and the 5,798-tool enumeration add specificity but make it slightly denser than strictly necessary.

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

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

For a single-required-parameter router with rich annotations and no output schema, the description covers identity, current operational state, when to use it, and its relationship to the stable router. The output question is resolved by pointing to 'same response shape' as the resolvable sibling ask_pipeworx, and the biggest gotcha — live-testing of candidates — is explicitly disclosed.

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 question and its five aliases fully documented in the schema. The description only cross-references 'same arguments' as ask_pipeworx, which marginally confirms alias parity but adds no substantive parameter semantics beyond the high-coverage baseline.

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

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

The description states a specific resource and behavior: it is a beta universal router with 'the same 5,798 tools, same arguments, same response shape' as ask_pipeworx, plus experimental routing. It distinguishes itself from siblings by naming ask_pipeworx and contrasting with the 'stable router.' An agent can immediately tell what this tool does and how it relates to its sibling.

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?

'Use it exactly like ask_pipeworx when you want the newest routing' gives an explicit selection condition and names the primary alternative. However, it does not spell out explicit exclusions (e.g., prefer the stable router when reproducibility matters) or mention the grounded sibling variant, leaving some counterfactual inference to the agent.

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

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

Beyond the annotations, the description richly discloses behavior: it only answers from tool results, returns an evidence verbatim quote, and refuses with specific reason codes when data doesn't directly answer. This gives the agent an accurate model of the tool's guarantees and failure modes.

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 every sentence earns its place: core behavior, routing, return contract, refusal reasons, use cases, and cost tradeoff are all covered. It is front-loaded with the key purpose and does not waste 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?

With no output schema, the description fully compensates by spelling out the success return shape and all refusal reasons. It also covers cost, when to prefer the sibling tool, and the high-stakes context, 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%, with all parameters documented as aliases for 'question.' The description adds general usage context but not parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: it is a 'hallucination-resistant answer mode for high-stakes reads' that routes to tools and extracts answers. It explicitly distinguishes itself from ask_pipeworx by emphasizing grounded extraction and refusal behavior, so an agent can tell them apart.

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 explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also provides a clear alternative and exclusion: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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

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

The description goes far beyond annotations by explaining internal mechanics: resolver contract, parent event extractor, news fallback, safety short-circuits, resolution-rule risk, and tradeability. No contradictions with annotations (readOnlyHint=true, etc.).

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

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

The description is very thorough but overly long (500+ words). While front-loaded with purpose, the excessive detail in sections like RESOLVER CONTRACT and RESOLUTION-RULE RISK could be streamlined without losing essential guidance.

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

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

Given the complexity of the tool and no output schema, the description covers all essential aspects: input formats, processing logic, output structure (response shapes), error states (low_confidence_match, market_closed_or_inactive), and safety warnings. It is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for the 'depth' parameter (quick vs thorough fan-out) and 'include_raw' (payload size control), which enhances understanding beyond the schema definitions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb 'Research' and resource 'Polymarket bet'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by explicitly stating use cases ('should I bet on X', etc.) and providing detailed fan-out examples.

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

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

The description provides extensive usage guidance, including when to use the tool, how inputs are resolved, fan-out behavior, and when to inspect fields like market_match_confidence. It also covers edge cases like low-confidence matches, closed markets, and wide spreads.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 a single efficient paragraph, front-loaded with trigger phrases and key functionality. Every sentence adds value, though it could be slightly more structured (e.g., separate bullet points for types). Still, it is concise and informative.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description covers return format (paired data + citation URIs), sorting behavior, data sources, and edge cases (off-calendar fiscal years). The parameter schema is well-documented, making the description complete for agent usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains what 'company' and 'drug' types retrieve (financial vs. adverse events data), provides examples for 'values' (tickers vs. drug names), and clarifies the count bounds.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific trigger phrases like 'compare X and Y' and 'rank these companies'. It distinguishes from sibling tools by noting it replaces 8-15 sequential lookups and is preferred over single-pack 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?

Explicit when-to-use cues are given (natural language patterns like 'X vs Y'). It also states 'ALWAYS PREFER over sequential single-pack lookups' and specifies entity count limits (2-5), guiding proper invocation.

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

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

The description goes well beyond the readOnly/idempotent annotations, disclosing source scope, parallel facet decomposition, gap[] reporting with no invented answers, contradiction scans, resolvable citation URIs, semantic excerpting, account/paid-plan requirements, and latency. There is no contradiction with the annotations.

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

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

The description is dense and front-loaded with the account prerequisite, but its long parenthetical style and prose repetition of depth/schema details make it heavier than needed. The content is valuable, but it is not as concise or streamlined as it could be.

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 covers the return shape (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), preconditions, exclusions, depth behavior, and latency. An agent has everything needed to decide whether and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by tying depth:'thorough' to a paid plan, explaining hop behavior in prose, and noting latency differences by depth. Some depth details duplicate the schema, but the added constraints are meaningful.

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: grounded multi-source research across Pipeworx's structured data sources in one call, explicitly distinguishing it from open-web search. It also provides concrete example questions and identifies ask_pipeworx as the alternative for single lookups, so an agent can tell it apart 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?

Usage conditions are explicit: use ask_pipeworx if not signed in or for a single lookup, and use deep_research for broad/multi-part questions over structured data. This gives clear routing guidance relative to sibling tools.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds value by noting returns are ready to call directly with full schemas and examples, no second lookup needed.

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 purpose, then domains, then return details. It is slightly long but each sentence adds value. Could be trimmed slightly but remains clear.

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

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

No output schema, but the description fully explains what is returned (top-N tools with names, descriptions, schemas, examples, call-ready). Covers aliases and usage guidance. Complete for this tool.

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

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

Schema description coverage is 100%. The description mentions natural language query and aliases, but the schema already describes these. No additional meaning beyond schema.

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

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

The description clearly states the tool finds tools by describing data or task, listing many domains. It distinguishes from sibling tools which are specific tools, making this the discovery gateway.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use and implied when-not-to-use.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the bar is high — and the description clears it easily. It discloses the fan-out behavior across 8+ sources, the GDELT→GNews fallback chain, and crucially the interpretation semantics: 'sources_used/sources_failed ... an empty section is a real no data, not a bug', the FDA small-molecule expectation ('will show none here, that is expected, not a failure'), and the private-company behavior (resolved:false with explicit notes rather than a bare failure). These prevent the most likely agent misjudgments.

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 purpose statement is well front-loaded, and nearly every clause earns its place given the tool's complexity and missing output schema. However, it is one dense, semicolon-heavy run-on paragraph that is genuinely hard to scan — the return-structure section crams cik, company_name, resolved_from/to, recent_filings, fundamentals, patents, contracts, FDA, hiring, news, and LEI into a single breathless sentence. Bulleted structure would dramatically improve readability at the same 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 carries the full burden of documenting return values — and it does so extensively: the complete return shape, pipeworx:// URI format, interpretation of sources_used/sources_failed, all input variants, and every major edge case. Nothing an agent needs to call this tool correctly or interpret its response 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 description coverage is 100% — the schema already explains type interchangeability and the accepted value shapes (ticker, CIK, company name). The description adds concrete examples ('AAPL', '0000320193', 'Moderna') and reinforces the zero-padding requirement, but these are marginal additions over the schema. Baseline 3 is appropriate since the schema carries the semantic weight.

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

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

The description states a specific purpose — 'full cross-source profile of a US public company in ONE parallel call' — with a clear verb (profile/brief), resource (US public company), and execution model (single parallel call). The opening query examples ('tell me about X', 'brief me on Tesla') make the intent instantly recognizable, and the explicit scope (US public company) distinguishes it from siblings like compare_entities and resolve_entity.

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?

'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' is explicit when-to-use guidance. The private-company edge case (resolved:false + notes) and the 'person/place coming soon' note in the schema imply when it is NOT suitable. However, it never names sibling tools as alternatives (e.g., resolve_entity for bare entity resolution, deep_research for open-ended research), leaving some routing decisions to inference.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds value by revealing normalization behavior and a proxy fallback mechanism for blocked sources. No contradictions or missing critical behavioral context.

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

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

Two sentences, no filler. The first sentence covers core purpose and normalization; the second adds robustness and usage guidance. Front-loaded and efficient.

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

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

For a simple fetch tool with well-documented parameters and good annotations, the description covers key aspects: what it fetches, normalization, proxy fallback, and guidance. Lack of output schema is mitigated by the tool's simplicity, but a brief note on return format would improve completeness.

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

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

Schema coverage is 100%, with each parameter already described clearly. The description does not add additional semantic nuance beyond what is in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb (fetch) and resource (RSS/Atom/RDF feed by URL), and distinguishes from siblings by specifying normalization and the suggestion to use list_feeds for curated sources. It covers feed types and proxy fallback, making the tool's scope unambiguous.

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

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

Explicitly advises to 'Use list_feeds first for curated sources,' which provides clear context for when this tool is appropriate versus siblings. However, it does not explicitly state when not to use it or mention alternatives beyond list_feeds.

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 aligns with annotations (destructiveHint=true, readOnlyHint=false) by stating it deletes a memory. It adds useful behavioral context about why you might delete (stale data, sensitivity), which annotations alone do not provide.

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

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

The description is three sentences with no wasted words. The purpose is front-loaded, followed by usage guidance and sibling references. Every sentence earns its place.

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

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

Given the simple tool (one required param, no output schema), the description fully covers purpose, usage, and behavioral context. No gaps remain for an agent to invoke it correctly.

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

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

Schema coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The tool description does not add additional semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key', making the tool's purpose unambiguous. It distinguishes from sibling tools 'remember' and 'recall', which are for creating and retrieving memories.

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 the tool (stale context, task done, clear sensitive data) and pairs it with related tools 'remember' and 'recall'. This provides clear guidance on selection and context.

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

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

Discloses that the tool fetches the page, extracts title/description/key links, and outputs standard markdown. Annotations already declare read-only and idempotent; description adds fetch and extraction behavior, though could note potential network issues.

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

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

Two concise sentences plus bullet list of use cases. No filler; main purpose and output format 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?

Explains output format and contents sufficiently given no output schema. Covers extraction detail and deployment location. Could mention error handling for unreachable URLs, but adequate for typical use.

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

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

Both parameters are fully described in the input schema (100% coverage). Description adds no new meaning beyond schema descriptions, 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?

Specific verb ('generate'), resource ('llms.txt file'), and context ('for any URL so AI crawlers can index the site cleanly'). Clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' which focus on analysis rather than 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?

Explicitly lists three use cases: getting client site indexed, drafting own llms.txt, auditing competitor. Does not provide when-not-to-use or alternative tool guidance, but context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about curated feeds and returned fields but no behavioral traits beyond annotations, which is acceptable as annotations cover safety.

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 with no wasted words. First sentence defines scope and output, second sentence covers options and alternative 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?

Tool is simple with 2 optional params and no output schema. Description mentions returned fields, which is sufficient. No mention of pagination/limits, but not critical for this tool.

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

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

Schema coverage is 100%, but description adds the allowed category values ('design, photography') not present as enums in schema, enhancing semantic 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?

Clearly states 'List the curated design & photography feeds' with specific fields returned, and distinguishes from sibling read_feed by noting 'Pass an id to read_feed'.

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

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

Provides guidance on optional filters and directs to read_feed for a specific feed. Could be more explicit about when not to use, but adequate for a simple list tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds details about returned fields, but lacks info on pagination limits. Score high as annotations carry the burden.

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

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

Three sentences, no redundancy. Every sentence adds value: purpose, return fields, and usage guidance.

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

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

Given single optional parameter, rich annotations, and no output schema, the description fully covers what an agent needs: purpose, return fields, and usage context.

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

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

Schema coverage is 100% with description for the only parameter. The tool description adds no further parameter detail, meeting baseline but not exceeding.

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 action 'List the caller's active subscriptions' and lists specific return fields (id, type, params, etc.). This differentiates it from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This helps the agent decide between this and alternatives.

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

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

The description discloses several behaviors beyond annotations: the claim_token mechanism (returned when filing without an account, usable later to check status), a rate limit of 5 per identifier per day, and that it is free and does not count against the tool-call quota. This is substantial context that annotations (all false hints) 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 information-dense but every sentence earns its place: it moves from purpose, to usage, to exclusions, to mechanics, to rate limits. There is no filler or redundancy; it is long but appropriately structured for the tool's complexity.

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

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

For a feedback tool with no output schema, the description fully covers what an agent needs: when to use, what to avoid, how to track a report, rate limits, and cost. The claim_token explanation ensures the agent knows what to expect as a return value and how to use it later.

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

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

While schema coverage is 100%, the description adds significant parameter semantics: it explains the claim_token round-trip with exact syntax, constrains message content to Pipeworx tools/packs, and elaborates on the type parameter's use cases beyond the enum descriptions. This goes well 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 begins with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately differentiates this feedback tool from sibling tools like ask_pipeworx or discover_tools by focusing on reporting issues/praise about Pipeworx tools themselves.

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 explicit when-to-use triggers: bug (wrong/stale data), feature/data_gap (tool not in catalog), and praise. It explicitly excludes tools from other MCP servers, instructing to file with that server instead, and clarifies how to frame feedback (in terms of Pipeworx tools/packs, not user prompts).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context: data is derived from CF analytics-engine, no PII, just counts; caching behavior (5min-1h depending on window). No contradictions.

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

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

Description is front-loaded with the core output, followed by bullet-point use cases, then technical details. Every sentence earns its place; no redundancy. Efficient and well-structured.

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

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

Despite no output schema, the description explains return contents (top tools, top packs, total call volume) and caching behavior. This is complete for a simple, read-only tool with excellent annotations and a single parameter.

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

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

Schema coverage is 100% for the single parameter 'window', with enum and description. The description reinforces the intent (shorter windows for hot trends, longer for steady-state demand) but does not add substantive meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns top tools, packs, and total call volume over a configurable window. It lists three specific use cases, distinguishing it from siblings like discover_tools or ask_pipeworx. The verb 'returns' identifies the action, and the resource is clearly the trending usage data.

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

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

Three explicit use cases are given: discovering hot data sources, confirming canonical tool choice, and aligning use case with agent needs. While it doesn't explicitly state when not to use, the scenarios cover appropriate contexts well. No alternative or exclusion guidance is provided, but the description's clarity suffices.

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

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

The description goes far beyond annotations by detailing internal logic: partition_sum checks with >3pp deviation, Jaccard similarity threshold of 0.30, placeholder filtering, fill check against CLOB depth, and response structure. It adds significant behavioral context without contradicting the readOnlyHint, openWorldHint, or idempotentHint annotations.

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

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

The description is well-structured, starting with the core purpose, then detailing modes, followed by technical details. It is somewhat lengthy but every sentence adds value. Minor redundancy (e.g., explaining partition_check twice) slightly reduces conciseness, but overall it is efficient for the complexity involved.

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

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

Given no output schema, the description thoroughly covers response fields (opportunities array, partition_check details), behavior for each mode, constraints (similarity threshold, placeholder filter), and cross-references to sibling tools for additional functionality (fill risk). It is complete for an analysis tool of this complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds substantial meaning: it explains that `event` accepts slugs or full URLs and is recommended for specific markets, while `topic` is a seed question for cross-event scanning, and it also describes the default behavior with no arguments. This enriches the 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by detailing unique methods and 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 explicitly specifies when to call with no args (trending scan), with `event` (single-event partition check), or with `topic` (cross-event scan). It explains the benefits of each mode and refers to polymarket_fill_risk for custom sizing, providing clear alternative guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, which the description reinforces. It adds extensive behavioral details: cache behavior ('Cached 1h at the KV level'), model specifics (FRED log-returns, GDELT, partition_overround with per-sport α), edge calculation (edge_pp_net after slippage, kelly capped at 0.25, 24h-move warning), and diagnostic sections. 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 a dense block of text but logically organized: purpose, three segments, per-opportunity fields, tradeable-edge knobs, response top-level. While informative, it could be broken into sections or bullet points for readability. Each sentence is meaningful, but length slightly hurts scannability.

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 9 parameters, no output schema, the description fully explains the response structure (by_segment, fed_note, _diagnostics) and details every field (edge_pp_net, kelly_fraction, market.liquidity, etc.). It covers cache behavior, model assumptions, and knob effects. No obvious gaps remain for an agent to understand inputs and outputs.

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

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

All 9 parameters are described in the schema (100% coverage), and the description adds rich context beyond name/type. For example, min_kelly explains 'Minimum half-Kelly fraction... Skips opportunities that are too small to bet sensibly even if the edge is large.' Slippage_pp discusses execution cost and Polymarket's zero fees. Every parameter gets practical 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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan, return), resource (Polymarket markets), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on broad opportunity discovery.

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 'Built for "what should I bet on today"' and explains the three segments and their use cases (e.g., concentrated_longshot is rare-by-design). It does not directly state when not to use it, but the context and sibling names imply its role as a discovery tool versus analysis tools.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context: data from daily snapshots, 60-day TTL, response structure, and that decay is based on daily closes, not intraday. 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 well-structured with clear sections and front-loaded with purpose. While somewhat long, every sentence adds value, explaining response fields and limits without unnecessary fluff.

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

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

Given no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]), including field meanings and sign interpretation. It also covers limits like TTL and gap handling, making it comprehensive.

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 schema descriptions are already detailed. The tool description adds context by explaining the purpose of days and window, but largely repeats schema info, so only marginal added value.

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

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

The description clearly defines the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age and trends. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking.

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

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

The description explains what the tool answers and includes limits, but does not explicitly state when to use or not use it compared to alternatives. The context is clear enough for an AI to infer appropriate usage.

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

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

Annotations already declare readOnlyHint and idempotentHint, making the tool safe and non-destructive. The description adds valuable behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap, slippage, etc.), and warns about forced directional risk. No contradictions.

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

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

The description is relatively long but well-structured with headings (SINGLE-MARKET, BASKET) and bullet lists. Every sentence provides necessary detail; the length is justified by the complexity of the two modes. It is front-loaded with 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 has no output schema, the description fully covers all return fields for both modes (e.g., shares_filled, max_fillable_usd, profit_usd, thin_legs). It also explains edge cases like partial basket fills creating directional risk, making it complete for an agent to understand behavior.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond parameter descriptions: it explains the default for side (auto based on partition sum), the interpretation of size_usd for buys vs sells (max spend vs target proceeds), and the dual behavior of market vs event parameters. This helps the agent select correct parameters.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating it is a prerequisite before acting on their signals.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books is not capturable, partial fills lead to directional risk). This provides clear when-to-use and rationale for exclusion.

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 extensive behavioral context beyond the readOnly/openWorld/idempotent/non-destructive annotations: it explains the token-overlap matching algorithm, that unknown metric_type or match_subtype legs are never paired, that compatibility flags can be non-empty even when pairs are returned, and that spreads are gross of Kalshi fees. There is no contradiction with the annotations.

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

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

The description is long, but every block earns its place: purpose and modes come first, then response shape, safety fields, fee disclosure, and skipped-pair counters. It could be tightened, especially around the safety-code enumeration, but the structure is logical and 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: raw probabilities, top_spreads_pp with per-entry flags, compatibility_codes, temporal_alignment semantics, skipped_unclassified, low_confidence_pairs, skipped counters, and the fees caveat. An agent has enough information to invoke the tool and interpret results safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful mode semantics and examples for topic, kalshi_event_ticker, and polymarket_event_slug, plus the warning that explicit pairings run the same matcher. There is slight ambiguity about whether the two explicit parameters must be used together or can individually override one side of a topic mapping.

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, unambiguous purpose: it computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It then names the two operating modes and scopes the tool to equivalent bet shapes, which distinguishes it from generic arbitrage or single-venue pricing 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 gives clear routing guidance between the 10 pre-mapped topic shortcuts and explicit ticker/slug pairings, and explicitly says both modes run the same matcher with the same disclosures. It also warns that pre-mapped topics frequently return compatibility_warning, so an agent won't mistake shortcuts for tradeable opportunities. It doesn't explicitly name sibling alternatives like polymarket_arbitrage, so the when-not-to-use guidance is incomplete.

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 the tool is read-only, idempotent, and non-destructive. The description adds context about the output format ('Returns normalized items including title, link, published, summary') and optional keyword filtering, which are useful 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 two sentences long, front-loads the main purpose, and contains no superfluous information. Every clause adds value.

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

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

For a simple read tool with good annotations and thorough schema, the description covers the key aspects: what it does, input prerequisite, output fields, and filtering option. It lacks details on pagination or rate limits but is mostly complete given the tool's complexity.

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

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

Schema coverage is 100%, with each parameter described. The description adds minimal extra meaning: it explains the feed id comes from list_feeds and mentions optional keyword filtering. This is adequate but does not significantly surpass the schema descriptions.

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

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

The description uses a specific verb ('Read') and resource ('a curated design & photography feed by its id'), clearly stating the tool's action and scope. It also notes the prerequisite ('from list_feeds'), which helps differentiate from similar tools like fetch_feed.

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

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

The description implies that the feed id should come from list_feeds, but it does not explicitly state when to use this tool versus alternatives like fetch_feed or search_within. No exclusion criteria or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: it retrieves values, is scoped to an identifier, and pairs with remember/forget. 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 well-structured and front-loaded with the main action. It is concise but covers all necessary points. Slightly verbose, but no unnecessary information.

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

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

Given the low complexity (one optional parameter, no output schema), the description is complete. It explains use cases, scoping, and integration with other tools.

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

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

The description adds meaning beyond the input schema by explaining that omitting the key lists all keys. Schema coverage is 100%, but the description enhances 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: retrieve a value saved via remember, or list all saved keys. It uses specific verbs ('retrieve', 'list') and identifies the resource ('saved keys'). It distinguishes from sibling tools like remember and forget.

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

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

The description explains when to use the tool (look up context stored earlier, avoid re-deriving) and how (omit key to list all). It mentions scoping and pairing with remember/forget, but could be more explicit about when not to use it or alternatives.

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

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

The description adds behavioral context beyond the annotations, such as the effect of mark_read on subsequent calls and the structure of returned alerts (source, citation_uri, raw payload). Since annotations already declare readOnly and idempotent, the description appropriately complements 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 concise (5 sentences) and well-structured, front-loading the core purpose and progressively adding details on return fields, filtering, and usage notes. Every sentence serves a 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 complete schema coverage and rich annotations, the description adds sufficient context about the tool's behavior, including return fields and the mark_read feature. It is fully adequate 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?

All 5 parameters have schema descriptions (100% coverage), and the description adds examples (e.g., 'sec_8k') and clarifies the mark_read behavior. The description enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and distinguishes itself from sibling tools like fetch_feed or read_feed by specifying it returns the most recent alerts from the persisted feed.

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

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

The description provides usage guidance by mentioning polling works fine and that the same feed is available via a REST endpoint for scripts/dashboards. However, it does not explicitly state when to use this tool over alternative feed-related tools like fetch_feed or read_feed.

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

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

Beyond annotations (readOnlyHint, etc.), the description details multiple data sources (SEC EDGAR, GDELT, GNews, USPTO), fallback behavior, and current USPTO status. This adds significant behavioral context.

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

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

The description is information-dense but somewhat long. It front-loads purpose with example queries, then details sources and param guidance. Slightly more structured formatting could improve scanability, but overall efficient.

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

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

With 3 required params and no output schema, the description covers input format, data sources, return structure (changes[], total_changes, URIs), and limitations (USPTO soft-fail). It is fully adequate for an agent to use correctly.

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

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

Despite 100% schema coverage, the description adds practical context: notes that type only supports 'company', explains since format with examples, and mentions ticker vs CIK for value. This meaningfully supplements the schema.

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

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

The description clearly defines the tool as a change feed for a company in a recent window, using phrases like 'what's new with X'. It distinguishes from the sibling entity_profile by stating when to use that instead.

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

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

The description provides explicit usage scenarios ('What's new with X') and an explicit alternative: 'Use entity_profile instead when you want the static profile'. It also clarifies the since parameter options.

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

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

Annotations already indicate idempotentHint (true) and destructiveHint (false). Description adds valuable behavioral context: key-value scoping by identifier, retention durations for authenticated vs anonymous sessions. 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?

Three sentences, front-loaded with purpose, then usage, then technical details. Every sentence serves a purpose, no fluff.

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

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

For a simple write tool with no output schema, the description covers purpose, behavior, usage, and even mentions related tools. It is fully adequate 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?

Schema coverage is 100% with clear descriptions. Description adds context about scoping by agent identifier and the nature of key-value storage, which is helpful but not strictly required given schema completeness.

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

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

The description clearly states the tool saves data for reuse, specifying the verb 'save' and resource 'data'. It distinguishes from siblings by naming 'recall' and 'forget' as direct companions.

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

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

Explicit guidance on when to use (discovering something worth carrying forward) and when to use alternatives (pair with recall/forget). Also notes authentication and session retention details.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior, so the bar is lower, but the description still adds substantial behavioral context: ambiguous matches return figi_candidates rather than asserting a result, unresolved identifiers are explicitly listed under `unresolved`, and LEI/FIGI enrichment degrades gracefully if external sources are unavailable. No contradiction with annotations.

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

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

The description is long but front-loaded with example queries, the core purpose, and the direct 'Use FIRST' instruction. Later dense paragraphs on company resolution are lengthy but earned given the tool's complexity, and the SUPPORTED TYPES structure aids scanning. A few parenthetical asides make it slightly harder to skim.

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

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

Because there is no output schema, the description carries the full burden of explaining return behavior, and it does so well: it covers resolved/unresolved field semantics, ambiguous multi-match behavior, fallback behavior when external lookups fail, and the range of accepted inputs. For a tool with two required parameters, the description is complete enough 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?

Schema coverage is 100%, so the baseline is 3, but the description adds critical parameter meaning beyond the schema. It clarifies that `value` accepts ticker, CIK, ISIN, or name, and includes the important warning to pass the issuer name exactly as printed without trailing security-class words. This is exactly the kind of disambiguation an agent needs and it is absent from 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 job: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It then enumerates the supported entity types (company and drug) and the specific identifiers returned, making it easy to distinguish from sibling lookup tools like entity_profile or validate_claim.

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

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

The description gives an explicit usage trigger: 'Use FIRST whenever you have a name but need an ID.' It also notes that other tools require these identifiers as input, which clarifies context. However, it does not name sibling tools or state when not to use this tool, so it stops short of fully explicit alternative routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it internally calls ai_visibility_check for each entity, ranks results by score, and surfaces most/least recognized. It also describes the output format (ranked list with score, confidence, signal density), which 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 four sentences with no fluff. It front-loads the main purpose, then explains the mechanism, use case, and output. Every sentence adds value and is efficiently structured.

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

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

Despite lacking an output schema, the description sufficiently explains the tool's behavior, parameters, and return type. It covers internal steps (probe, rank, surface) and output fields (score, confidence, signal density). For a ranking tool with good annotations, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that the first entity in 'entities' is treated as the 'subject' for narrative and that omitting 'models' defaults to 'workers-ai'. This extra context improves understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using the verb 'Compare' and specifying the resource. It distinguishes itself from sibling tools like ai_visibility_check (singular) and compare_entities (generic) by focusing on AI presence and competitive audit.

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 'Useful for competitive AI-marketing audits' and gives an example query. It implies when to use (multi-entity comparison) but does not explicitly exclude single-entity use, which is covered by ai_visibility_check. Still provides clear context.

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

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

Discloses that it fans out across two external services, that bundlephobia's first measurement can take 5-30s, and that partial failures degrade gracefully with sources_failed listed. This adds context beyond annotations like readOnlyHint and idempotentHint.

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

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

Description is relatively long but packed with essential information. It front-loads the core purpose and then details behavior, timing, and limitations. Could be slightly trimmed but remains efficient.

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

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

For a tool with no output schema, the description provides a comprehensive list of return fields and explains partial failure behavior. It covers all necessary context for an agent to understand inputs, behavior, and outputs.

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

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

Both parameters are described in schema (100% coverage) and the description adds that version defaults to latest published, which is not in schema. This adds meaning beyond the schema.

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

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

The description clearly states it performs a composite check for adding npm packages, combining deps.dev and bundlephobia data. It distinguishes from siblings like 'validate_claim' or 'scan_competitor_ai_presence' 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?

Explicitly states when to use: when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies NPM-only and directs other ecosystems to deps.dev:version, providing clear 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?

Description adds substantial behavioral info beyond annotations: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), char cap (200K) and truncation behavior. This makes the tool's inner workings transparent.

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 tightly packed paragraphs with zero wasted words. Front-loaded with purpose, then use case, then technical details. Every sentence earns its place.

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

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

Even without an output schema, the description informs the agent of return format (top-N passages with offsets and scores). Also covers pairing with another tool and truncation. Fully sufficient for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. Description enhances meaning by explaining query as 'natural-language query', giving examples, and noting limit defaults. Adds practical usage hints beyond 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?

Purpose is crystal clear: 'Semantic search INSIDE a fetched record.' It specifies verb (search), resource (a fetched record), and distinguishes from sibling tools like ask_pipeworx_grounded by describing its pairing role.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Describes context-saving benefit and pairing with another tool. Lacks explicit 'when not to use', but context is clear enough.

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

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

The annotations declare write behavior (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds significant context: OAuth requirement, supported event types with specific examples, delivery channels (feed, email, SMS, webhook) with constraints (SMS 10/day cap, webhook auto-disable after 10 failures), and the fact that the subscription persists. 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 well-structured: starting with the core action, then auth requirement, then supported types, then delivery options. It is informative without being verbose, though it could be slightly condensed (e.g., some type details are repeated in the schema). Still, every sentence adds value.

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

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

Given the tool's moderate complexity (3 parameters, nested objects, no output schema), the description covers all necessary aspects: purpose, auth, types, delivery channels, constraints, and return value. It provides enough detail for an agent to correctly invoke the tool, especially with the sibling tools 'list_subscriptions' and 'unsubscribe' available.

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 goes beyond the schema by providing type-specific examples (e.g., 'items:["5.02"]' for sec_8k) and detailed delivery channel behavior (e.g., webhook signing and auto-disable). This adds practical understanding for parameter usage.

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 begins with 'Create a proactive monitoring subscription to a live-data event stream,' which clearly specifies the verb (create), resource (subscription), and scope (proactive monitoring). It also mentions returning the subscription id. This distinguishes it from sibling tools like 'unsubscribe' and 'list_subscriptions.'

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

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

The description states a key prerequisite ('Requires a Pipeworx OAuth account') and lists supported subscription types with examples. It does not explicitly exclude alternatives, but the context signals (sibling tools) imply that this is the only creation tool. The mention of phone verification and rate limits provides helpful constraints.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns categorized example questions with tool usage details, 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?

Packed with useful info, front-loaded purpose. Slightly long but each sentence adds value. Could be trimmed slightly but acceptable.

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

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

For a simple tool with one optional param and no output schema, the description covers purpose, usage, and behavioral context well. No gaps given the tool's nature.

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 describes the topic parameter and lists possible values. Description adds that omitting gives cross-category spread, reinforcing usage. Schema coverage is 100%.

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 the onboarding entry point for new agents, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes from siblings like discover_tools.

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

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

Explicitly says to use this FIRST when you don't know what Pipeworx can do, and explains when to pass topic vs no arguments. No explicit when-not, but context is clear.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false; description adds that the row is deactivated (not deleted) and ownership is enforced. This context beyond annotations justifies a 4.

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

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

Three concise sentences, no redundancy. Front-loaded with the core action, then details. Every sentence adds value.

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

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

Tool is simple (1 param, no output schema), and description covers the key behavioral aspects (ownership, deactivation). Annotations complete the safety profile. No gaps remain.

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

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

Schema has 100% coverage with a clear description of the 'id' parameter. The description restates the parameter usage but adds a link to the 'subscribe' tool for provenance, which is helpful but not essential. Baseline 3 applies.

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

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

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

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and notes that deactivated rows keep historical events accessible via recent_alerts. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes well beyond these by detailing the return verdict set (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), explaining the critical distinction between 'could_not_verify' (check did not happen, carries verification_error) and 'unsupported' (no source found), and revealing the internal routing logic between structured SEC EDGAR/XBRL and the grounded pipeline. This is substantial behavioral context.

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

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

The description is longer than average but information-dense and well-structured. It is front-loaded with user intents and core purpose, then details routing, return values, caveats, and the efficiency benefit. No sentence is wasted, though the closing 'Replaces 4–6 sequential calls' is a nice-to-have rather than essential. Slightly verbose for a 2-param tool, but justifiably so given 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?

Without an output schema, the description fully carries the burden of explaining return values. It specifies the verdict enum, mentions the actual value with pipeworx:// citation, and explains reasoning. It also covers both financial and non-financial claim handling, including the error semantics of could_not_verify and verification_error. For a tool with two distinct pipelines and nuanced output states, this description is comprehensive.

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 both parameters (claim, tolerance_pct) already well-described. The tool description does not add additional parameter-level detail beyond what the schema provides, such as examples of tolerance_pct semantics or formatting requirements. Since the schema carries the full parameter burden, the baseline of 3 is appropriate.

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

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

The description opens with explicit intent phrases ('fact check', 'verify the claim that…') and clearly states the tool performs 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by describing two processing paths (SEC EDGAR/XBRL for financial claims, grounded pipeline for all others) and notes it replaces 4–6 sequential calls, making the tool's scope and value 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear guidance. It also differentiates how financial vs. non-financial claims are handled, implying comprehensive coverage of factual claims. However, it does not name alternative tools or state when not to use it, so it stops short of full exclusion guidance.

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