Packagist

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by specifying the default model (Workers AI Llama-3.3-70b, free), BYO key for Anthropic, and the return structure (per-model score, confidence, signals, raw_response, combined view). No contradictions.

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

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

A single, well-structured paragraph that front-loads the core function, then flows naturally into model defaults, API key usage, and return format. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains the return structure (per-model score, confidence, signals, raw_response, combined view) sufficiently. All parameters are documented, and the tool's read-only, idempotent nature is clear. Complete for its complexity.

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

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

Schema description coverage is 100% with good descriptions for entity, models, _apiKey, and context. The description adds extra meaning beyond schema, e.g., 'Default model is Workers AI Llama-3.3-70b (free)' for models parameter and 'BYO key' for _apiKey, enhancing 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 probes LLMs for brand visibility and scores it (0-100) per model, with specific verb 'Probe' and resource 'LLMs'. It differentiates from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring and model-specific results.

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

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

The description lists use cases (AI-marketing audits, brand checks, competitive monitoring) and explains when to use _apiKey for Anthropic. It does not explicitly state when not to use the tool or compare to alternative siblings, but the context is clear.

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

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

Annotations already declare read-only and non-destructive, so the description does not need to repeat that. It adds value by disclosing internal routing behavior (5,529 tools, fills arguments), output format (structured answer with pipeworx:// citation URIs), and performance ('one fast call'). This goes beyond annotations, though it doesn't discuss failure modes or rate limits, which are less critical for a read-only tool.

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

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

The description is long but front-loaded with the key 'PREFER OVER WEB SEARCH' and structured into clear segments: scope, mechanism, trigger phrases, examples, and escalation guidance. While a few sentences could be tightened, the length is justified by the tool's complexity and the need to route between alternatives.

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

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

Without an output schema, the description compensates by explaining the return format (structured answer with citation URIs) and mentions connectivity across tiers. It covers the tool's broad domain scope, provides examples, and names specific sibling tools for escalation, making it complete for an agent to decide when and how to invoke correctly.

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

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

The schema provides 100% coverage for the 'question' parameter and its aliases, so baseline is 3. The description enhances this by giving concrete example queries (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and explicitly stating the parameter accepts natural language, helping the agent form appropriate input beyond the schema's minimal description.

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

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

The description clearly defines the tool as a question-answering router that queries verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, and specifies the scope (current/historical data, factual questions). This is a specific verb+resource+scope with explicit differentiation.

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

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

The description explicitly states to prefer this over web search for factual queries, declares it as the default entry point, and gives clear conditions for stepping up to ask_pipeworx_grounded or deep_research. It also clarifies that breaking news is already handled, providing both when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations, the description discloses key behavioral traits: live activation of candidate routing improvements, the current no-candidate state with a specific retirement date, and that results are compared against the stable router. It also clarifies that it is a full working router, not a fallback, providing valuable context beyond what annotations offer.

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 each sentence serving a distinct purpose: identity, current status, usage guidance, and functional guarantee. It is front-loaded with the most critical information, and there is no filler or redundancy; every sentence earns its place.

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

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

For a beta router with a single required parameter and no output schema, the description covers the essential context: what it is, how it relates to the stable version, when to use it, and its current behavior. It relies on the response shape being the same as ask_pipeworx, which is sufficient given the sibling tool's presence in the toolset.

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

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

The input schema fully covers the question parameter and its five aliases with 100% coverage. The description only references 'same arguments' as ask_pipeworx, adding no additional meaning or usage nuance beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description explicitly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It clearly distinguishes itself from the stable ask_pipeworx by its experimental edge and live candidate routing improvements, making the purpose specific and well-differentiated.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and states results are compared to the stable router. It clarifies the current state (matches ask_pipeworx exactly) but does not explicitly mention when not to use it or compare it to ask_pipeworx_grounded, leaving some alternative-usage gaps.

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 substantial behavioral context beyond the annotations, including the exact return shape on success, explicit refusal reasons on failure, and the extra LLM call cost. It is consistent with readOnlyHint=true and all other annotations, with no contradiction.

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

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

The description is dense with information but well-structured, starting with the core purpose, then mechanism, output, usage guidance, and cost consideration. Every sentence contributes value, with no redundancy or 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?

Since there is no output schema, the description thoroughly covers return values for both success and refusal cases, including specific refusal reasons. It also addresses routing, cost, and usage context, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% with the 'question' parameter and five aliases all documented as natural language questions. The description adds no parameter-specific details beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, explaining how it routes to the appropriate tool, fetches data, and extracts answers only from the tool result. It distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded, evidence-based approach.

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

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

Explicitly states when to use: whenever an answer will be quoted, cited, or acted on, and where hallucination is unacceptable (financial verdicts, legal claims, medical lookups, public statements). Also provides exclusion: prefer ask_pipeworx for casual lookups due to the extra LLM call cost.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds extensive behavioral details: data sources, response shapes, safety mechanisms, resolver contract, parent event extractor, news fields, and resolution-rule 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 very long and dense, covering many details. While informative, it could be more concise. The purpose is front-loaded but the extensive detail may overwhelm.

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

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

Given the complexity (3 params, no output schema), the description is extremely thorough: covers response shapes, error handling, safety, resolution risks, and field semantics. Adequately compensates for missing output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing examples (slug, URL, question text) and clarifying defaults (depth='thorough'). Also explains 'include_raw' 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 clearly states it researches a Polymarket bet by pulling Pipeworx data. It gives specific use cases and examples, but does not explicitly differentiate from sibling tools like polymarket_arbitrage.

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

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

Provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Includes examples but lacks explicit 'when not to use' guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true. The description adds rich behavioral context: data sources (SEC EDGAR, FAERS), fiscal year handling, 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 compact yet comprehensive, with natural language triggers front-loaded. Every sentence serves a purpose, and the structure flows logically from usage examples to data specifics.

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 covers return format (paired data + citation URIs), entity count limits, data sources, and sorting. It is fully sufficient for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description significantly adds meaning: explains what each entity type returns (company: financials, drug: adverse events) and the expected format for values (tickers for company, generic names for drug).

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

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

The description clearly states the tool's purpose with specific verbs like 'compare', 'rank', and natural language triggers. It distinguishes from siblings by advising preference over sequential lookups, though explicit sibling differentiation is slightly indirect.

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

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

The description provides explicit when-to-use guidance with natural language examples and a strong directive to prefer this over sequential lookups. It lacks explicit exclusions for single-entity queries, but the context strongly implies those should use other 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?

Beyond the annotations (readOnly=true, openWorld=true, idempotent=true), the description adds significant behavioral context: it explains the parallel decomposition behavior, gap[] handling for unanswered facets (never invented), hop fields, citation_uri resolution, contradictions[] for standard/thorough, semantic excerpting instead of head-truncation, and expected latency (15-60s, up to ~90s for thorough). It also discloses the account/payment requirement, which is critical for usage.

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 (about 250 words) but densely packed with high-value information. It front-loads the critical account requirement and alternative tool usage at the start. Each sentence earns its place: examples, limitations, behavior, latency. It could be slightly trimmed (e.g., the parenthetical URL example), but given the tool's complexity and many behavioral nuances, the length is justified.

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 (5,529 tools routed, three depth levels, multiple output components like gaps[], contradictions[], hop fields, citation URIs, latency), the description covers all major aspects an agent needs: when to use, when not, account requirements, output format, behavior on unanswered facets, and timing. There's no output schema, so the description's detailed explanation of return values (findings packet, verbatim evidence, confidence, source, fetched_at, citation) is essential and well done.

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 both parameters have descriptions. The description adds semantic meaning by explaining the depth tiers ('quick=3, standard=5, thorough=8') which mirrors but enriches the schema enum text, and clarifies that question accepts broad/multi-part natural language since decomposition is the point. It doesn't add syntax details beyond schema, but the schema descriptions are already thorough, so a 4 is appropriate.

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

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

The description clearly states the tool's purpose: grounded multi-source research across Pipeworx's structured data sources in one call, decomposing questions into facets and routing to parallel tools. It distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also gives clear when-not-to-use alternatives: for single lookups use ask_pipeworx, and for breaking/current news prefer ask_pipeworx because deep_research returns empty gaps. It also explains depth tiers and account requirements.

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

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

Annotations indicate read and idempotent. Description adds that results include full input schemas with curated examples, ready to call directly, no second lookup needed. Consistent with annotations.

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

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

Description is packed with useful information and front-loaded with the main action. Slightly lengthy but each sentence adds value.

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

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

Given high schema coverage and no output schema, description adequately explains what to expect: top-N tools with names, descriptions, schemas, examples, ready to call. Covers main use case.

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

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

Schema coverage 100%. Description explains query parameter aliases (task, q, search, description) and limit default/max, adding meaning beyond the schema.

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

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

Description clearly states 'Find tools by describing the data or task' and provides extensive domain examples. It distinguishes this meta-tool from sibling search tools by emphasizing it returns ready-to-call tool schemas.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use, though no explicit 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds substantial context: fans out across multiple sources, returns specific fields, patents soft-fail until May 2025, and uses fallback mechanisms. 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?

Well-structured with front-loaded example queries, then detailed breakdown of sources and outputs. Each sentence serves a purpose, though slightly verbose. Efficiently conveys all needed information without redundancy.

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

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

Given no output schema and two parameters, the description thoroughly explains input requirements, output fields (cik, filings, fundamentals, patents, news, LEI), sources, failure modes, and limitations. Leaves no critical gaps for an AI agent to understand tool 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 has 100% coverage with descriptions for both parameters. Description reiterates constraints (type only 'company', value ticker or zero-padded CIK) and adds usage guidance (names not supported, zero-padding required). Also mentions future types. Adds meaningful context 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 provides a 'full cross-source profile of a US public company in ONE parallel call', listing example queries and distinguishing it from chaining single-pack lookups. It specifies the resources (SEC, XBRL, USPTO, news, GLEIF) and outputs, making purpose 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 tells when to use (holistic view, 'Tell me about X') and when not to (names not supported). Recommends resolve_entity as alternative for names. Also notes patent data soft-failure. Provides clear context for decision-making.

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 signal destructiveness; the description adds context by explicitly mentioning deletion of memories, which is consistent and adds value.

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

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

Two concise sentences with front-loaded action verb and no superfluous content.

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

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

For a simple one-parameter tool with annotations and no output schema, the description plus schema provide complete context for 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% and describes the 'key' parameter adequately; the description does not add extra parameter details, so baseline 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 specific verb 'Delete' and resource 'memory by key', and the purpose is distinct from sibling tools like 'remember' and 'recall'.

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

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

Explicitly provides when to use (stale context, task done, clear sensitive data) and suggests pairing with sibling tools, aiding selection.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions.

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

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

Three sentences, front-loaded with main purpose. Each sentence adds value: what it does, how it works, and use cases. No wasted text.

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

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

For a simple generation tool with comprehensive annotations, description adequately covers input, process, and output format. Could benefit from noting that output is plain text, but overall 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. Description mentions url and max_links implicitly through the process but adds no additional semantic meaning beyond what schema provides.

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

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

Description clearly states it generates a production-ready llms.txt file for AI crawlers, with specific verb ('generate') and resource ('llms.txt file'). Distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than visibility scanning or analysis.

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

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

Provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. Lacks explicit when-not-to-use or alternatives, but the context makes usage 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, openWorldHint, idempotentHint, and destructiveHint false, so the description does not need to restate safety. It adds valuable behavioral context by detailing the breadth of information returned, including every published version and its requires, autoload, and dist details, giving the agent a concrete expectation of the tool's output beyond the structured fields.

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 exactly two sentences. The first sentence front-loads the core purpose and input format with an example; the second enumerates the return fields in a compact list. Every word is functional, and there is no redundant or vague filler.

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

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

For a one-parameter, read-only tool with a rich output schema and strong annotations, the description provides all necessary context: input format with example, output contents, and the questions it answers. It leaves no material gaps in understanding how to invoke or what to expect from the tool.

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

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

Schema coverage is 100% with the parameter 'name' described as 'Package name in "vendor/package" form'. The description repeats this format and adds an example, but does not introduce new semantic meaning beyond what the schema already provides. This matches the baseline for high schema coverage.

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

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

The description clearly states the tool retrieves the full Packagist registry record for a single PHP/Composer package in vendor/package format, with an explicit example (symfony/console). It enumerates the exact data returned (description, repository URL, maintainers, license, type, downloads, favers, and all published versions with requires/autoload/dist details), making its purpose distinct from sibling tools like list_versions or package_stats.

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

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

The description gives clear context for when to use this tool: when you need a comprehensive registry record for one package and answers to questions about what the package is, who maintains it, and what each release declares. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous and sufficient for an agent to choose it over more targeted 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds behavioral details like default returning only active subscriptions and the optional include_inactive parameter. The additional info about returned fields further aids transparency.

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

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

Two concise sentences, front-loaded with the core action, followed by usage guidance. Every sentence serves a purpose without redundancy.

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

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

Despite no output schema, the description enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count), effectively completing the context. Annotations cover safety, and the tool is simple with only one optional 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?

Input schema has one parameter (include_inactive) with a clear description. Schema description coverage is 100%, so the baseline is 3. The tool description does not add extra 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?

Description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe/unsubscribe and lists returned fields, making the purpose unmistakable.

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

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

Explicitly advises using this tool to review subscriptions before adding more or to find IDs to cancel, providing clear usage context. Lacks explicit exclusion of alternatives but is 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 readOnlyHint=true and idempotentHint=true, and the description does not contradict these. It adds useful behavioral context by detailing the exact return structure (every version string paired with timestamp plus total count), which goes beyond the annotations.

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

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

The description is three sentences, each earning its place: first states the resource and scope, second details the output, third answers the key use case. It is front-loaded and free of 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 tool with one parameter, an output schema, and read-only/idempotent annotations, the description is complete. It explains the input, output, and purpose without redundancy. No further context appears necessary.

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 'name' parameter is described as 'vendor/package'), so the baseline is 3. The description adds a concrete example (symfony/console) and reinforces the format with 'given a vendor/package name', providing a small but meaningful boost 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 a specific verb ('returns') and resource ('release history of one PHP/Composer package on the Packagist registry'), and it specifies the output (every version string with release timestamp and total count). It distinguishes itself from sibling tools like get_package or package_stats by focusing solely on version history.

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

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

The description gives clear context on when to use the tool ('Answers which versions of a Composer package exist and when the latest one shipped') and provides an example input format. However, it does not explicitly mention exclusions or alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that the tool retrieves counts but does not disclose any additional behavioral traits beyond what annotations 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 a single sentence that is front-loaded and efficient. It earns its place without fluff, though it could be slightly more structured (e.g., listing each metric explicitly).

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

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

For a simple tool with one parameter and an output schema, the description adequately summarizes the return data. It could be improved by stating that it provides historical download statistics, but the output schema likely covers this.

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 'name' described as 'vendor/package'. The description does not add extra semantic meaning beyond the schema; it merely reinforces that the parameter refers to a package. Baseline 3 applies.

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

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

The description clearly states the tool returns download counts and dependents count for a package. It uses a specific verb-resource combination, but does not explicitly differentiate from sibling tools like 'get_package'.

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?

No guidance on when to use this tool vs alternatives like 'get_package', 'list_versions', or 'scan_dependency'. The context signals list many sibling tools, but the description offers no selection criteria.

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

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

Annotations are minimal (all false hints), so the description carries the burden. It discloses several behavioral traits: filing without an account returns a claim_token; passing it back later allows reading the status; rate-limited to 5 per identifier per day; free and doesn't count against tool-call quota; team reads digests daily. It also describes the conditional behavior of claim_token (read vs. file mode). This goes well beyond what annotations convey.

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

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

The description is a single dense paragraph that front-loads the core purpose and gives concrete use cases. Every sentence earns its place, but it is slightly long and could be broken into shorter sentences or bullets for scannability. It is still concise relative to the amount of behavioral information conveyed.

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 and minimal annotations, the description is remarkably complete: it covers filing types, exclusions, claim_token return/read flow, rate limits, quota accounting, and team response cadence. It also warns against pasting end-user prompts. The nested context object is optional and well-described in the schema. No critical gaps remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the claim_token flow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and clarifies that claim_token can be used standalone with 'no other arguments.' It also explains the rate limit context. It doesn't fully compensate for the nested context object's semantics, but the schema already describes each field well.

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

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

The description states a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from siblings by framing it as feedback about Pipeworx tools specifically, not a generic query or research tool. It also names the output behavior (returns claim_token) and the types of feedback accepted.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or for praise. It also provides an explicit exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is strong differentiation from 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 provide safety/idempotency hints; description adds caching behavior, data source ('CF analytics-engine'), and privacy statement ('no PII'), which go beyond annotations without contradiction.

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

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

Five concise sentences with bulleted use cases, no redundant words, and core information front-loaded.

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

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

For a simple read-only tool with one parameter and existing annotations, the description provides full context: return structure, window options, use cases, source, caching, and privacy.

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

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

Schema covers 100% with enum description. The tool description adds the insight that shorter windows show hot trends and longer windows show steady-state demand, enriching the semantics.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' based on recent AI agent activity, with specific use cases that distinguish it 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 lists three useful scenarios, but does not directly state when not to use or name alternative tools. The context is clear enough for typical usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes beyond by detailing internal logic: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slug detection, >20% placeholder fraction returns null), and fill check that prices against live order book, warning not to trade if not realizable. This provides comprehensive behavioral transparency.

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

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

The description is long but well-structured, starting with a clear purpose, then detailing modes, internal filters, fill check, and return structure. Every paragraph adds valuable information, though some internal details could be condensed. Overall, it is appropriately detailed 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?

Despite lacking an output schema, the description thoroughly explains the response format (opportunities array with fields, partition_check object, fill check results) and edge cases (null signals when placeholder fraction too high). It also mentions the return of 'skipped_low_similarity' and 'thin_legs[]'. This makes the tool's behavior fully predictable.

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 have 100% schema description coverage, but the description adds significant context: examples of values (e.g., 'fed-decision-may-2026' for event, seed questions for topic), explanation of how each parameter affects scanning behavior, and internal logic like semantic anchor and partition filter. This exceeds the schema's basic descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between modes (no args, event, topic) and explains what each mode does, making it easy for an agent to understand the tool's purpose relative to siblings like polymarket_edges or polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each parameter (event for a specific market, topic for cross-event scans) and recommends defaults. It explains the difference between modes and when cross-event scanning catches patterns single-event misses. Also mentions custom sizing via polymarket_fill_risk, giving clear usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds extensive behavioral context: caching at KV level, response structure (by_segment, fed_candidates, diagnostics), and detailed model family explanations. 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 relatively long but well-structured with clear sections (model families, knobs, response). It front-loads the purpose. Some details like exact formulas could be considered verbose but are relevant and organized.

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

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

Given the complexity (9 parameters, no output schema), the description covers all necessary aspects: response structure, caching, diagnostics, and why Fed bets are excluded. It provides sufficient detail for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond the schema for several parameters (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly explains its behavior). This provides additional value.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and elaborates on three model families. It distinguishes from siblings like 'polymarket_arbitrage' by focusing on Pipeworx data discrepancy.

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

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

The description explicitly states it's built for 'what should I bet on today' and mentions that it avoids paging hundreds of markets. While it doesn't explicitly list when not to use, the context among siblings provides implicit guidance. The phrase 'Built for' indicates intended use.

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

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

Annotations already declare readOnlyHint=true, idempotent, etc. The description adds significant context: it reads from daily snapshots with a 60-day TTL, decay computed from daily closes (not intraday), and explains the trend and decay fields. No contradiction with annotations.

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

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

The description is somewhat long but well-structured with a clear opening sentence and organized details about response fields and limitations. Every sentence adds value, though it could be slightly tighter without losing information.

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

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

For a tool with two simple parameters and no output schema, the description covers all necessary aspects: purpose, parameters, response structure (tracked[], expired[], snapshot_dates[]), limitations (TTL, snapshot gaps, decay nature), and behavioral notes. It is fully complete for an agent to understand 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% with adequate descriptions. The description restates the defaults and constraints (days default 14, max 30; window default '1wk') but adds no new semantic 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's purpose: edge persistence and decay telemetry from daily snapshots, answering how long an edge exists and whether it's shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description explicitly contrasts fresh vs old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying when to use this for historical context. It doesn't explicitly state when not to use, but the context is clear. It also details the response structure, guiding the agent on what to expect.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and warns about partial basket fills leading to directional risk. 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 lengthy but well-organized with clear headers (SINGLE-MARKET, BASKET) and bullet-point-like details. Every sentence adds value, though a slight reduction is due to the overall length—some trimming could improve readability without losing information.

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

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

Despite lacking an output schema, the description comprehensively lists all return fields for both modes, including edge cases like thin_legs[] and forced_directional_risk. It covers crucial warnings about partial fills and directional risk, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema: it explains how size_usd is interpreted differently in single-market vs. basket modes, provides defaults for side and size_usd, and clarifies that event is for basket mode and market for single-market. This extensive context raises the score.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and the specific verb 'check' and resource 'order-book depth' make the purpose unambiguous. This effectively differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly tells when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround on thin books is not capturable, partial basket fills convert arb to unhedged directional position). However, it doesn't explicitly state when not to use it or list alternatives, so it loses one point.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: compatibility_warning with two cases, temporal_alignment, skipped counters, and a caution that real spreads are rare. This goes well beyond annotations.

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

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

The description is longer than average but each sentence earns its place. It front-loads the core purpose, then details modes, response, and safety fields. A slightly more structured format could improve 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?

Given the complexity of cross-venue spread computation with two modes, the description is highly complete. It covers response structure, safety fields, temporal alignment, and limitations without an output schema. The warnings about pre-mapped topics provide critical context.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description adds value by explaining the interplay between topic and explicit parameters, including that explicit overrides the topic-mapped side.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like 'polymarket_arbitrage'. It specifies two modes (topic and explicit) and the precise function.

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

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

The description explains when to use the tool (cross-venue comparison) and provides warnings about pre-mapped topics often returning compatibility warnings, implying when not to rely on results. However, it lacks an explicit statement of when not to use it.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details beyond annotations: scoping to identifier (anonymous IP, key hash, account ID) and the dual behavior of omitting key. 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 two sentences, front-loaded with the primary action, and every sentence adds value. No redundant or extraneous content.

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

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

Despite no output schema, the description adequately explains what the tool returns (a value or list of keys). It covers inputs, behavior, scoping, and relationships with sibling tools. Complete for a read-only lookup tool.

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

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

Schema coverage is 100% and the description adds meaning by explaining that omitting the key lists all keys, while providing a key retrieves a specific value. It clarifies the parameter's role beyond the schema's basic string description.

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

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

The description uses specific verb 'Retrieve' and resource 'memory key', clearly stating two modes: retrieve a value by key or list all keys by omitting the argument. It implicitly distinguishes from siblings ('remember', 'forget') by contrasting actions.

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

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

The description provides clear context: look up stored context without re-deriving. It gives concrete examples (ticker, address, notes) and mentions pairing with remember/forget. It does not explicitly state when not to use it or name alternative tools for retrieval, but the usage scenario is well-defined.

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 states that mark_read:true flags events as read, implying a state change. This contradicts the readOnlyHint annotation which declares no side effects. This is a significant inconsistency that misrepresents the tool's 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 succinct, using five sentences that each serve a distinct purpose: purpose, return content, filtering, behavior, and alternative access. No redundant information.

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

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

Despite lacking an output schema, the description details return values (source, citation_uri, raw payload) and explains key behaviors like mark_read and polling suitability. It covers all necessary context for an agent to use the tool effectively.

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 parameters are described in the schema with 100% coverage. The description adds value by providing examples (e.g., 'sec_8k' for type) and explaining that mark_read affects future calls, which goes beyond the schema description.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns the most recent alerts. It specifies returned fields like source, citation_uri, and raw event payload, which distinguishes it from sibling tools like 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 provides clear guidance on filtering by type and since, using mark_read, and polling. It mentions an alternative API endpoint, but lacks explicit exclusions for when not to use this tool.

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

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

Annotations already indicate read-only, open-world, and idempotent behaviors. The description adds significant context: fan-out to multiple sources, fallback from GDELT to GNews, PatentsView sunset soft-fail, and the output structure. 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 query examples first, then details on data sources and parameters. It is relatively long but every sentence adds value. Minor reduction could be made, but effective overall.

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

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

Despite no output schema, the description explains the return format (changes grouped by source, total_changes, citation URIs). All three parameters have clear descriptions and examples. The tool's scope and limitations are fully covered.

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

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

Schema coverage is 100%, but the description adds valuable usage examples: 'since' accepts ISO dates or relative shorthand (e.g., '30d'), 'value' can be ticker or CIK, and 'type' is limited to 'company'. It also suggests typical monitoring windows like '30d' or '1m'.

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

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

The description clearly states it provides a change feed for a company, combining SEC filings, news, and patents in one call. It gives specific query examples and distinguishes from the sibling tool 'entity_profile', which is for static profiles.

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

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

Explicit use cases are provided ('What's new with X', 'latest on Y', etc.), along with when to use an alternative ('Use entity_profile instead when you want the static profile'). It also details fallback behavior and soft-failures.

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

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

Annotations indicate idempotent, non-destructive writes. The description adds critical context: memory is scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradiction with annotations.

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

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

Three sentences front-load the purpose, usage context, and behavioral details. Every sentence is specific and informative with no repetition or filler.

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

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

The description fully explains the tool's purpose, usage pattern, data scope, and retention policy. Given no output schema, it sufficiently covers what the agent needs to know 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 covers both parameters with descriptions. The description adds example formats for keys and values, but this is minimal extra value given the high schema coverage.

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

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

The description clearly states the tool saves data for later reuse, specifying key-value storage and giving concrete examples (resolved ticker, target address, etc.). It distinguishes from sibling tools like recall and forget.

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

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

The description explicitly advises using when discovering something worth carrying forward to avoid re-lookup, and pairs with recall and forget. It does not explicitly mention when not to use, but the positive guidance is strong.

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

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

The description goes well beyond the annotations by disclosing internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and the behavior that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted. It also details return contents per type (CIK, LEI, FIGI, RxCUI, etc.). No contradictions with annotations.

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

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

The description is longer than typical but well-structured: examples first, then purpose, usage, and type details. Every sentence provides useful information, though the repeated example queries could be trimmed. It remains informative without being wasteful.

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

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

Despite lacking an output schema, the description thoroughly explains what is returned for each entity type, including identifiers, ownership data, source labelling, and handling of unresolved IDs. It also covers edge cases (degradation) and the benefit of reducing manual lookups, making it complete for an AI agent.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description adds valuable context about accepted input formats (e.g., examples like 'AAPL', 'ozempic') and elaborates on what each entity type yields, but it doesn't fundamentally change parameter meaning beyond the schema. 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 the tool resolves user-spoken names to canonical/official identifiers, with specific verbs and resources. It gives examples of inputs ('ticker for...', 'CIK for...') and explicitly mentions the supported types (company, drug), making the purpose unmistakable.

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

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

Provides an explicit directive: 'Use FIRST whenever you have a name but need an ID.' This gives clear when-to-use context. However, it does not mention specific alternative tools or when not to use it, so it lacks explicit exclusions or named 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 indicate read-only, idempotent, non-destructive behavior. The description adds context: it probes each entity with ai_visibility_check, ranks results, and surfaces most/least recognized. It also describes the return format (score, confidence, signal density), going beyond annotations.

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

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

The description is concise (4 sentences) and well-structured: purpose first, then mechanism, use case, and return format. 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). Parameters are fully documented in schema. The tool's behavior of calling ai_visibility_check is transparent. Complete for its 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%, so baseline is 3. The description adds value by clarifying that models defaults to 'workers-ai' if omitted and that an API key is needed for 'anthropic' model. This provides context not in the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'compare' and resource 'AI visibility', and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use this over ai_visibility_check but does not explicitly list when not to use or other 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?

Description adds key behavioral details beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. Annotations already indicate readOnly, idempotent, etc., but description supplements with real-world 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?

Concise yet dense: front-loads purpose, then usage, then behavioral details. No wasted words; every sentence provides 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?

No output schema, but description thoroughly lists what is returned (summary block with fields, per-advisory detail, links, alternative versions). Covers failure modes, ecosystem scope, and composite 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 covers 100% of parameters, and description adds context: scoped packages are accepted, version defaults to latest if omitted. This enhances clarity beyond schema alone.

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

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

Description clearly states it is a composite check for deciding whether to add an npm package, listing specific aspects (license, advisories, bundle size, etc.). Distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on package safety and size.

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

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

Explicitly says when to use: when agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also notes that PyPI/Maven/Cargo/Go should use deps.dev:version directly, providing clear 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 destructiveHint as false, covering safety and idempotency. The description adds behavioral context by specifying the return fields (names, descriptions, download counts, latest versions) and filter options, which go beyond the annotations.

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

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

The description is a single, well-structured sentence that front-loads the action and resource. It is concise with no wasted words.

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

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

Given the simple nature of the tool and the presence of an output schema, the description adequately covers the tool's purpose and return format. It could mention pagination parameters but the schema handles that. No major gaps.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description adds minimal extra meaning beyond mentioning optional type and tag filters, which are also covered in the schema. Baseline score of 3 applies.

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

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

The description clearly states the verb 'Search', the resource 'Packagist PHP/Composer registry', and the scope 'by free text with optional type and tag filters'. It differentiates from sibling tools like 'get_package' (specific package) and 'list_versions' (version listing) by emphasizing free-text and filter capabilities.

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 no guidance on when to use this tool versus alternatives (e.g., 'get_package' for exact package lookup, 'list_versions' for version details). It lacks context on prerequisites or typical use cases.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds specific behavioral details: BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, a 200K char cap with truncation flag, and that every passage includes an offset for verification. 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?

Two short paragraphs, first sentence immediately conveys the main purpose. Every sentence adds useful information (usage guidance, technical details, pairing). Zero fluff or repetition of schema details.

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

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

Given no output schema, the description covers return value contents (passages with offsets, similarity scores) and explains the internal mechanism (BGE-based, windowing). It also mentions limits and truncation behavior, and pairs with a sibling tool for grounding. Complete for agent understanding.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the embedding technique and that query is natural-language. It also reiterates character limits and default values. This extra context justifies a 4.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It specifies the action (search), resource (text inside a record), and output (top-N passages with offsets and scores). It distinguishes from siblings by contrasting with fetching whole documents and noting pairing with ask_pipeworx_grounded.

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

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

The description explicitly tells when to use the tool: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also mentions a companion tool, ask_pipeworx_grounded, for grounding. Lacks explicit 'when not to use' statements, but implied by 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?

The description extensively details behavioral traits: requires OAuth, returns subscription id, supports multiple types with examples, delivery channels with constraints (e.g., SMS cap, webhook auto-disable after 10 failures), and webhook signing process. This goes well beyond the annotation hints.

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

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

The description is relatively long but front-loaded with the main purpose. Every sentence provides useful context for an AI agent, though it could be slightly more streamlined without losing critical details.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers all necessary aspects: purpose, types with examples, delivery options, prerequisites, return value, and failure modes (webhook disable). It is thorough and leaves little ambiguity.

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 substantial meaning with concrete examples for each type and delivery field, explaining the semantics of items, topics, and webhook verification. The value-add justifies a score above baseline.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream. It distinguishes itself from sibling tools like list_subscriptions and recent_alerts by focusing on creation.

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 specifies the prerequisite of a Pipeworx OAuth account and mentions that the feed is always on and can be pulled via recent_alerts. However, it does not explicitly list situations where this tool should not be used or compare with alternatives like list_subscriptions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds behavioral context about returning category-bucketed examples and explaining the purpose as an onboarding entry point.

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 common questions and uses a structured list of categories. It is comprehensive but slightly long; a bit more conciseness could improve it.

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

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

Given no output schema, the description adequately describes return structure (category-bucketed example questions with tool+argument shapes) and covers all necessary context for an onboarding 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% for the single optional parameter. Description adds meaningful usage examples (e.g., 'finance', 'pharma') and clarifies that omitting topic gives a cross-category spread.

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 category-bucketed example questions and explicitly lists query examples, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

Provides explicit when-to-use: 'Use this FIRST when you do not yet know what Pipeworx can do for you,' and usage patterns: call with no arguments for full spread or pass topic to focus.

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

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

The description discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts, adding behavioral context beyond annotations which already indicate non-destructive, idempotent modification.

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 wasted words, with the primary action and key behavioral notes front-loaded. Highly 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 single-parameter tool with no output schema and well-covered annotations, the description fully explains the effect (cancel, deactivate), ownership constraint, and side effect on history. Complete.

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

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

The schema already has 100% coverage with a clear description of the 'id' parameter. The description does not add further semantics, so a 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 uses a specific verb-resource pair ('Cancel a subscription by id') and clearly distinguishes the tool from siblings like 'subscribe' 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?

It states that ownership is enforced and only own subscriptions can be canceled, providing clear context for when to use it. However, it does not explicitly mention when not to use it or substitute 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 readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: explains was replaced, defines edge-case verdicts (could_not_verify vs unsupported), clarifies that could_not_verify is not evidence, mentions verification_error fields, and describes citation and reasoning. No contradictions with annotations.

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

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

The description is a dense paragraph but every sentence contributes useful information: trigger phrases, routing, return values, caller warnings, and efficiency claim. It is longer than ideal but appropriately sized for the tool's complexity. The front-loaded trigger phrases aid recognition.

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 pipelines, six verdicts, error semantics) and the lack of an output schema, the description provides a comprehensive mental model. It covers the return structure, edge cases, and even caller guidance on how to interpret could_not_verify. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with detailed descriptions for both 'claim' and 'tolerance_pct', including examples and bounds. The tool description itself does not discuss parameters further, but the schema already carries the burden, so the baseline 3 applies. No additional meaning is added beyond the schema.

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

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

The description opens with natural-language trigger phrases and explicitly states the tool's function: verification of factual claims against authoritative sources. It clearly differentiates from siblings like ask_pipeworx by focusing on verification with a defined verdict set and mentions the two distinct processing paths (SEC EDGAR structured vs. grounded pipeline).

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

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

The description provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It outlines the two routing paths and notes the tool replaces 4–6 sequential calls, implying efficiency. However, it doesn't explicitly name alternative tools or state when not to use it, so a small gap remains.

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