Conceptnet

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

Annotations declared readOnlyHint, openWorldHint, idempotentHint, destructiveHint – so safety is clear. The description adds behavioral context: default model is free, Anthropic requires BYO key, return structure includes 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?

Three sentences: core function + scoring, model/cost detail, and return/usages. Front-loaded with key info, no redundancy, 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?

Despite no output schema, the description details return structure (score, confidence, signals, raw_response + combined view). Parameters are fully described in schema (100% coverage). The description is 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 description coverage is 100% – each parameter already has a clear description. The description adds minimal extra meaning (e.g., scoring range 0-100, purpose of context). Baseline 3 is appropriate as schema covers parameters adequately.

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 0-100 per model. It distinguishes from sibling tools like ask_pipeworx (general Q&A) and scan_competitor_ai_presence (similar but sibling name suggests broader scan), making its specific purpose evident.

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 identifies use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It mentions default vs BYO key for Anthropic, but does not explicitly contrast with sibling alternatives or say when not to use it, leaving some ambiguity.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits. The description adds useful behavior beyond those: it acts as a router, fills arguments automatically, draws on 5,798 tools across 1,517 verified sources, and returns stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with the key preference and purpose, which is good. However, it is verbose and repeats the 'even if web search could also answer it' point and the 'START HERE for most questions' call to action after examples have already been given, making it less tight than it could be.

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

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

For a tool with one essential parameter and no output schema, the description provides enough invocation context: scope of data sources, routing behavior, output form with stable citation URIs, trigger phrases, and six representative examples. It does not cover latency or failure modes, but those are not essential 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?

The input schema already describes all six parameters and clearly documents that q, text, input, query, and prompt are aliases for question. The description adds illustrative example questions but no parameter semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a clear, specific job: it takes a natural-language question, routes it to one of 5,798 data tools, and returns a structured answer with citation URIs. It is not a tautology and is easy to distinguish from generic web search or lookup, but it does not explicitly differentiate itself from sibling ask_pipeworx_* variants.

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

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

It gives strong when-to-use guidance: prefer over web search for factual, current, or historical questions, with explicit trigger phrases and concrete examples. However, it does not discuss when to choose sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, nor does it provide exclusions.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already signal safety. The description adds valuable transparency about its experimental nature: currently matches ask_pipeworx exactly, may change when candidates are tested, and falls back to nothing (a full working router). This context goes beyond what annotations can convey, though it doesn't describe the actual routing behavior or response format.

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

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

The description is dense but every sentence earns its place: sets the beta context, provides exactly-matching current state, gives usage instruction, and explains the fallback behavior. It is well-structured with front-loaded identity and usage guidance.

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

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

For a universal router with a single required parameter, the description is nearly complete. It covers the experimental status, current parity, usage, and fallback. It could be improved by mentioning the response shape or how an agent might know when a candidate is active, though 'same response shape' as ask_pipeworx covers the former. The output schema absence is mitigated by referencing the stable version.

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

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

Schema coverage is 100% and the schema documents the question parameter and its aliases clearly. The description doesn't add much beyond 'same arguments as ask_pipeworx,' which is appropriate since the schema already covers everything. Baseline 3 is correct; the description doesn't need to compensate.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router that takes a question and routes it. It distinguishes itself from the stable sibling ask_pipeworx by noting it is the experimental edge with candidate routing improvements. The verb 'ask' plus resource is clear, though it depends on the sibling name for full 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?

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. This gives the agent an explicit when-to-use directive and explains the experimental context. No alternative is recommended over it, but the condition 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?

Even with readOnlyHint and idempotentHint present, the description adds substantial behavioral detail: success and refusal shapes, exact refusal_reason enum values, the 'ONLY what the tool result contains' constraint, and the extra LLM call cost. Nothing contradicts 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 front-loaded with purpose, then provides the return contract, refusal reasons, use cases, and cost comparison. Every sentence earns its place; it is dense but appropriately sized for a high-stakes grounded answer tool.

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

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

There is no output schema, so the description compensates by fully specifying the success response fields and the refusal response enum. It also covers cost/performance trade-offs and typical high-stakes scenarios, making the tool self-contained enough to invoke correctly.

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

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

Schema description coverage is 100%: all six aliases (question, q, text, input, query, prompt) are documented as aliases for a natural-language question. The description adds no parameter-specific detail, but none is needed; the schema already carries the semantic burden, so 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 first sentence clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, and it explicitly distinguishes itself from ask_pipeworx by naming the same routing but a stricter extract-and-ground step. The sibling tool name ask_pipeworx is referenced, so an agent can tell them apart.

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

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

The description gives explicit when-to-use guidance: use whenever the answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete domains listed. It also states the alternative preference: prefer ask_pipeworx for casual lookups, which is clear routing among siblings.

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

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

Disclosures go far beyond annotations: resolver contract (match confidence, alternatives), parent event extractor, news fallback fields, safety short-circuits, closed market handling, wide spread illiquidity, and resolution-rule risk. No contradiction with annotations (readOnlyHint: true, openWorldHint: true, idempotentHint: true, destructiveHint: false).

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 every section adds unique information: core purpose, classifiers, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety, and resolution rules. It is well-structured with clear headings, justifying its length for a complex tool.

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

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

Covers all aspects: input format, output shape (with key fields), edge cases (closed markets, low confidence, wide spreads, resolution rules), and behavioral details. No output schema exists, but response shapes are described in sufficient detail.

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

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

With 100% schema coverage, the description adds meaning: explains how 'market' interprets slug/URL/question text, how 'depth' controls quick vs thorough fan-out, and how 'include_raw' affects response size. This is valuable context beyond the schema.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, accepts multiple input formats (slug, URL, question text), and returns an evidence packet with comparison. It distinguishes itself from sibling research tools by focusing on Polymarket bets and mentioning Pipeworx.

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

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

Provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and detailed examples of fan-outs. Does not explicitly list when not to use or alternatives, but the guidance is strong and contextually rich.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safe, repeatable behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS, FDA, ClinicalTrials), specific financial metrics, handling of off-calendar fiscal years, sorting by primary metric, and citation URI format. 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 single paragraph that packs extensive information. It is front-loaded with example queries and includes necessary details. While dense, it is still relatively concise for the complexity, though minor restructuring could improve readability.

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

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

Given the tool's complexity (two entity types, diverse data sources, sorting, citations) and the lack of an output schema, the description is remarkably complete. It covers return format (paired data + citation URIs), sorting behavior, and edge cases (off-calendar fiscal years), leaving no major gaps.

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

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

Schema coverage is 100%, but the description adds richness beyond the schema: for 'type', it explains data sources and metrics; for 'values', it gives concrete examples (tickers/CIKs, drug names) and constraints. This significantly aids parameter understanding.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs. It provides example queries like 'Compare X and Y' and explicitly distinguishes from sequential lookups, making the 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?

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving strong usage guidance. It also details when to use each type (company vs drug) and what data to expect, though it doesn't mention when not to use or alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses account and paid-plan requirements, parallel decomposition across 5,798 tools, the return packet shape, explicit gaps[] with no invented answers, contradictions[] on deeper depths, resolvable pipeworx:// citation URIs, semantic excerpting, and latency expectations. There is no contradiction with the annotations.

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

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

The description is long, but it earns its length for a complex tool: every sentence contributes useful context and the account constraint is front-loaded. A slight redundancy with the schema's depth explanations and the dense parenthetical style keeps it from a 5.

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

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

This is a complex tool with no output schema, yet the description covers authentication, alternatives, depth semantics, output fields, citation resolvability, gap behavior, contradictions, and expected latency. An agent has almost everything needed to call it correctly and interpret the results.

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

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

The input schema already describes both parameters completely, including the depth enum and what each level does, so this is at the baseline of 3. The description adds some operational context, such as example research questions and timing ranges, but it does not change or deepen the core meaning of the parameters.

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

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

The description opens with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call. It also explicitly distinguishes itself from open-web search and names ask_pipeworx as the sibling alternative, so an agent can tell it apart without opening the schema.

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: best for broad/multi-part questions over structured data, with concrete examples. It also gives clear exclusions: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead.' It further warns that this is NOT open-web search, preventing a common mis-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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which are consistent with a discovery tool. The description adds that results are 'ready to call directly, no second schema lookup needed,' providing useful behavioral detail 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 a single dense paragraph but front-loaded with the core purpose. The list of domains could be trimmed, but it effectively communicates scope. Overall, it is well-structured and informative without excessive verbosity.

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 compensates by detailing the return value (names, descriptions, schemas with examples). It covers the main usage scenario and provides examples. Minor gaps (e.g., no error handling details) but sufficient for a discovery 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 good descriptions. The description adds value by explaining that the query parameter accepts aliases (task, q, search, description) and provides examples (e.g., 'analyze housing market trends'). This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains the output: top-N relevant tools with names, descriptions, and schemas. This clearly distinguishes discover_tools from siblings like 'query' or 'lookup' which are for direct data retrieval.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also specifies use cases (browse, search, look up) and domains. While it doesn't explicitly say when not to use it, the context is clear.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial behavioral nuance: it fans out across multiple sources in parallel, soft-fails on the USPTO PatentsView sunset, returns empty fda_products for non-biologic companies (explicitly 'expected, not a failure'), and reports sources_used/sources_failed so empty sections are interpretable.

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

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

The description is long and dense, front-loaded with query examples and the key usage directive. It is a single wall of text rather than scannable bullets, but nearly every sentence carries a necessary caveat or output detail for a multi-source tool, so the length is largely 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?

With no output schema, the description carries full responsibility for explaining return shape and edge cases. It covers all major output sections (filings, fundamentals, contracts, FDA products, hiring, news, LEI), resolver behavior, failure semantics, and accepted input forms. Very little an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%: both `type` and `value` are already well-described in the input schema, including the interchangeability of 'company' and 'ticker'. The description adds minor context like zero-padded CIK format and SEC EDGAR name resolution, but mostly restates what the schema already conveys. Baseline 3 is appropriate.

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

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

The description opens with concrete query examples and a crisp definition: 'full cross-source profile of a US public company in ONE parallel call.' It names the exact resource (entity) and the specific verb/profile operation, and distinguishes itself from single-pack SEC/XBRL/news lookups, so an agent can identify it without reading the schema.

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

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

It explicitly tells the agent when to use this tool ('when the user asks for a holistic view') and even provides a preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also covers edge-case usage behavior, such as private companies returning resolved:false with a notes line rather than a bare failure.

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is beyond annotations. However, it doesn't specify behavior when key is missing, but the idempotent hint implies safe repeated deletion.

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 with the action stated first. It includes purpose, use cases, and pairing, all in concise language 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 simplicity of the tool (one parameter, no output schema), the description covers purpose, usage, and context within the sibling tools. It lacks return value specification but the destructive annotation and idempotent hint provide sufficient guidance.

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

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

The input schema has 100% coverage with a description of the 'key' parameter as 'Memory key to delete'. The description simply repeats 'by key' without adding new meaning or examples, so baseline score of 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key', which is a specific verb+resource. It also distinguishes from siblings 'remember' and 'recall' by its action.

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 specific scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, guiding when to use this tool in the context of the memory system.

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 (read-only, idempotent, non-destructive), the description explains the internal steps: fetches the page, extracts title/description/key links, and emits standard markdown format. This adds significant behavioral context that annotations alone do not provide.

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

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

Two concise sentences with a bulleted usage list. Every sentence earns its place, front-loaded with the primary action. No wasted words.

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

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

Given no output schema, the description explains the output format (single text blob, standard markdown). Parameter count is low. Missing error handling or edge cases (invalid URLs), but overall adequate for a straightforward 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 two parameters well-described in the schema. The description mentions 'fetches the page' (implied url) and 'maximum number of link entries' (max_links), but does not add extra semantics 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 generates a production-ready llms.txt file for a URL, specifying the exact resource and action. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence, which address related but distinct use cases.

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

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

The description provides explicit use cases (client site indexing, personal project, competitor audit) but does not mention when not to use this tool or suggest alternatives. It offers clear context but lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read. The description adds that it returns specific fields (id, type, etc.), which is useful but not critical. 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: first states purpose and return fields, second gives usage context. Every sentence adds value, with no wasted words.

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

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

Given no output schema, the description lists the return fields (id, type, etc.), which is helpful. It does not explain field meanings or pagination, but for a simple list of subscriptions, this is adequate.

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

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

Schema coverage is 100%, so the schema fully documents the single parameter 'include_inactive'. The description does not add extra meaning beyond what the schema provides, earning the baseline of 3.

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

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

The description clearly states the verb 'list' and resource 'subscriptions', specifying 'the caller's active subscriptions'. It differentiates from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel'. This tells when to use it and implicitly suggests alternatives (subscribe, unsubscribe).

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

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

Annotations clearly indicate the tool is read-only, idempotent, and non-destructive. The description adds minimal behavioral context (e.g., 'edges'), but nothing contradictory.

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 extremely short (one phrase), which is concise but lacks structure and clarity. It could benefit from a clearer sentence without being overly verbose.

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

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

Given the six parameters and the knowledge-graph domain, the description is too sparse. It doesn't explain offset/limit pagination, relation types, or the return format, even though an output schema exists.

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 each parameter is documented. The description adds no additional semantic value beyond the schema.

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

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

The description states 'All edges touching a term in a language', which gives a general idea of retrieving relationships but is vague about what 'edges' are and doesn't differentiate from similar sibling tools like '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?

There is no guidance on when to use this tool versus alternatives. No context for usage or exclusions are provided.

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

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

Annotations are all false, so the description carries the full burden of behavioral disclosure. It covers rate limiting (5 per identifier per day), free/quota-exempt status, the claim_token return behavior when no account is provided, the daily digest review by the team, and the roadmap impact. No annotation 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 dense but every sentence earns its place. It is front-loaded with the core purpose, then flows through usage conditions, exclusions, token workflow, rate limits, and quota impact. No filler or redundancy.

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

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

For a tool with no output schema, the description fully covers the user-facing workflow: what to report, how to scope it to Pipeworx, what happens when filing anonymously, how to claim the token, and operational constraints (rate limit, quota, team review cadence). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage semantics beyond the schema: it explains the claim_token round-trip (file returns token → pass back later to read status), reinforces the type enum with concrete examples, and advises message crafting (be specific, 1-2 sentences, don't paste user prompt). This goes beyond the schema's field descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact scenarios (bug, feature/data_gap, praise) and clearly distinguishes this tool from the research/query siblings by positioning it as the feedback channel for Pipeworx 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?

It explicitly states when to use ('Use when a tool returns wrong/stale data...') and when not to ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead'). It also provides formatting guidance (describe in terms of Pipeworx tools/packs, don't paste user prompt) and the claim_token workflow.

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

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

Adds context beyond annotations: data source (CF analytics-engine), privacy (no PII), returned fields (pack, tool, count), and caching (5min-1h). No contradictions.

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

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

Concise, front-loaded purpose, use cases in bullet-like format, and additional details in the last sentence. No unnecessary words.

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

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

Given low complexity (1 param, no output schema, rich annotations), the description covers all needed info: what is returned, how it works, caching, and usage context.

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

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

Single parameter `window` with enum is well-described, including behavior implications (hot vs steady-state). Schema coverage 100% supports baseline 3, but description adds 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?

Clearly states the tool returns trending tools/packs and call volume over configurable windows, 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 three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and guidance on window selection for different needs.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) indicate safe, read-only, open-world behavior. The description adds critical behavioral details: the 'FILL CHECK' explains that realizable_edge_pp ≤ 0 means the arbitrage is not tradeable, and it references polymarket_fill_risk for custom sizing. 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 comprehensive but slightly verbose. It is well-structured with clear sections (modes, semantic anchor, partition filter, response details, fill check). Every sentence adds value, though some details could be trimmed without losing clarity.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities array with fields, partition_check object, fill check details). It also addresses edge cases (low similarity, placeholder filter) and references a sibling tool for custom sizing, making it complete for agent use.

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

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

Input schema has 100% coverage with descriptions for both parameters (event, topic). The description enriches these by explaining that event takes a slug (with examples) and topic takes a seed question, and it details how these modes affect the analysis (walking child markets, cross-event scanning, similarity checks).

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges by focusing on arbitrage detection through specific mathematical checks, and it details three distinct usage modes (no args, event, topic) with specific behaviors.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' Recommends event mode for specific markets and explains when cross-event mode is beneficial. No explicit when-not-to-use, but the clarity of modes makes it highly usable.

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 explains the three model families, caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), edge and Kelly calculation, and tradeable-edge knobs. It adds significant behavioral context beyond the annotations, which already indicate readOnlyHint, idempotentHint, etc. No contradiction.

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

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

The description is long but well-structured, front-loaded with the core purpose, and each section (segments, response fields, knobs, diagnostics) adds necessary detail. While it could be more concise, the complexity of the tool justifies the length.

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

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

Given the tool's complexity (9 parameters, no output schema, nested structures), the description is highly complete. It explains the output structure, why segments may be empty, Fed bet handling, and how parameters affect results. This provides excellent context for the 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?

The schema already provides 100% coverage with detailed parameter descriptions. The tool description adds some context (e.g., summarizing knobs and explaining min_partition_leg_kelly), but it doesn't significantly enhance understanding beyond what the schema already offers. 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it's built for 'what should I bet on today'. It distinguishes itself from siblings by focusing on three specific model families and the Pipeworx data disagreement.

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 guidance on when to use the tool (for discovering opportunities without paging hundreds of markets) and mentions the tradeable-edge knobs. However, it does not explicitly compare with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving the agent to infer distinctions.

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 substantial behavioral context: it returns full edge_pp_net time-series, first_seen, trend, decay_pp_per_day, expired opportunities with lifespan_days, and snapshot_dates. It also discloses limits (60-day TTL, no intraday data) and data source (daily closes).

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 every sentence adds value. It front-loads the core question and then organizes response fields (tracked[], expired[], snapshot_dates[]) clearly. Could be slightly more structured with bullet points, but overall effective.

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

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

Given no output schema, the description fully explains the response structure including all fields and edge cases (gaps due to cache-miss, TTL bounding, start time). It covers the tool's complexity with 2 parameters and no nested objects completely.

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 both 'days' and 'window' are documented. The description adds meaning beyond schema: 'days' is lookback (default 14, max 30, with clamp 2-30), 'window' default is '1wk'. It also explains that history depth is bounded by 60-day TTL, adding subtle parameter constraint context.

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: 'Edge persistence and decay telemetry' and answers a concrete question: 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by focusing on time-series trend analysis rather than raw snapshot data.

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

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

The description provides clear context on when to use the tool ('Answers...'), including a concrete example differentiating fresh vs old wide edges. It explains interpreting results (trend, decay, lifespan) but does not explicitly name alternative tools for different use cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond annotations: walking the order-book ladder, returning detailed metrics like slippage, fill details, and risks like partial basket fills converting arb into directional positions. 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 dense and well-structured with bold mode headers, but slightly verbose at several sentences. However, every sentence earns its place, and the information is front-loaded with the core purpose.

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

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

Despite no output schema, the description comprehensively enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, theoretical_sum, capture_ratio, profit_usd, per-leg details, thin_legs, forced_directional_risk) and explains their meaning. No gaps 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 coverage is 100%, but the description adds significant value: e.g., for size_usd it distinguishes buys vs sells and basket mode interpretation; for side it explains default auto behavior. This enhances the schema definitions.

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' with explicit modes (single-market and basket) and specific differentiation from sibling tools like polymarket_arbitrage and polymarket_edges by being a prerequisite validation step.

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

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

The description explicitly states when to use the tool: 'USE 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 not capturable on thin books, partial fills causing unhedged positions) and implies when not to use (small trades).

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, and the description adds substantial context beyond them: pairing_unverified is set in EITHER mode whenever pairs are returned (keyword/word-overlap matching, not a shared resolution source), temporal_alignment null means 'could not be computed' and is explicitly NOT the same as confirmed-aligned, and the fees_note discloses that spread_pp is gross, not a net tradeable edge because Kalshi's fee schedule is not modeled. It also explains that compatibility codes can be non-empty even when matched_pairs>0 and that unclassified legs are never paired. No contradiction with annotations exists.

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

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

The description is long and dense, but it is front-loaded (purpose, then modes, then response, then safety fields) and essentially every sentence carries unique disclosure value — each compatibility code is enumerated, null semantics are specified, and the fee caveat is stated. It is not a 5 because the wall-of-text structure with long compound sentences taxes parsing; tighter paragraphing would improve scannability without losing 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?

With no output schema present, the return-value burden falls entirely on the description, and it discharges it thoroughly: leg-by-leg prices in 0-1 probability, matched spread[].top_spreads_pp as Kalshi minus Polymarket, per-entry flags[], the temporal_alignment{polymarket_month,kalshi_month,aligned} object, skipped_cross_type/subtype counters, and fees_note. Edge cases are covered as well — unclassified legs landing in skipped_unclassified/low_confidence_pairs, null alignment semantics, and matches with non-empty compatibility codes. Nothing an agent needs to correctly interpret results is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds real value beyond the schema by framing the three optional parameters as a mode system: pass topic alone vs pass both explicit ticker and slug together for custom pairings, a pairing constraint the schema itself doesn't state. It also clarifies that both modes surface identical disclosures, which is not derivable from the schema. This is modest but genuine added semantic content.

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 opening line, 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' names a specific measurement, the two venues, and the scope (same resolving question), leaving no ambiguity about what the tool computes. It further enumerates two concrete modes (topic shortcuts vs explicit ticker+slug), which distinguishes it from sibling arbitrage tools like polymarket_arbitrage. The title and description strongly differentiate this tool even among its close polymarket siblings.

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

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

The description gives clear context for choosing between the two modes: topic for 10 named macro shortcuts, explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, and states both modes run the identical matcher. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' which tempers expectations about when the tool is useful. However, it never names sibling tools as explicit alternatives (e.g., when to prefer polymarket_arbitrage or polymarket_edges), so exclusions are missing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description confirms it's an edge search but adds minimal behavioral context about combining parameters or response structure. Since annotations are rich, the description is adequate but not enhanced.

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 concise and front-loaded with the core purpose. Every part contributes meaning without redundancy.

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

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

Given the rich annotations and presence of an output schema, the description is adequate but lacks explanation of parameter combination behavior and default scoping (e.g., how offset/limit apply). An agent may benefit from more context on usage patterns.

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 71%, and the description lists parameters (rel, start, end, node, source) but does not explain how they combine (e.g., AND/OR logic) or provide additional semantics beyond the schema. Examples in the input schema partially compensate, but the description itself adds limited 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 'Generic /query edge search (combine rel, start, end, node, source)' clearly indicates the tool performs edge searches in a graph, specifying the main parameters. However, it does not explicitly differentiate itself from sibling tools like 'lookup' or 'deep_research', which may serve similar purposes.

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

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

No guidance is provided on when to use this tool versus alternatives. With siblings such as 'lookup', 'search_within', and 'entity_profile', explicit context on when this low-level 'query' is appropriate would aid 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?

Adds scoping detail (by identifier) beyond annotations; 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?

Four sentences, no fluff, well-organized with clear functionality, usage, scoping, and pairing.

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

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

Covers essential aspects for a simple retrieval tool; lacks return format details but not critical given examples.

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

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

Schema coverage is 100% and description echoes schema info; minimal added value beyond 'omit to list'.

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

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

Clearly states it retrieves a value saved via remember or lists all keys, and differentiates from siblings remember and forget.

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

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

Explicitly says when to use (look up stored context) and when not (save/delete via remember/forget), with concrete examples.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical behavioral details: mark_read flag affects future calls by marking events read, polling works fine, and the feed is also available via GET. No contradiction with annotations.

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

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

The description is a single focused paragraph of 5 sentences, each adding value: purpose, return fields, filtering, mark_read behavior, alternative endpoint. It is front-loaded with the main purpose and avoids 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 exhaustive schema coverage and comprehensive annotations, the description fully covers return format, filtering, mark_read behavior, and provides an alternative access method. No output schema exists, but the return fields are described. The tool is well-understood for invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances semantics by providing examples (type filter 'sec_8k', since as ISO timestamp), explaining mark_read behavior, and noting limit defaults. This adds meaningful guidance beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies return fields (source, citation_uri, payload), and distinguishes itself by mentioning an alternative endpoint for scripts/dashboards. The verb 'pull' and resource 'fired events' are specific and unambiguous.

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

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

The description provides context for when to use this tool (polling works fine) and mentions an alternative GET endpoint for scripts/dashboards, implying when not to use this tool. However, it does not explicitly exclude usage scenarios or compare with sibling tools, leaving some room for ambiguity.

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

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

The description richly details behavioral traits beyond the annotations: it fans out to multiple sources, has fallback mechanisms, accepts various date formats, and returns structured data with citation URIs. No contradictions with annotations (readOnly, idempotent). The soft-fail for patents is explicitly noted.

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

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

The description is front-loaded with query examples and provides thorough context. While every sentence adds value, it is somewhat long. However, the structure is logical, moving from examples to behavior to 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?

Given the tool's complexity (multiple sources, date windows) and the lack of an output schema, the description sufficiently explains what the tool returns (changes grouped by source, total_changes, citations). It also mentions the alternative tool for static profiles, making it complete for selection and invocation.

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

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

Schema coverage is 100%, but the description adds significant value: it explains the 'since' parameter accepts ISO dates or relative shorthand and recommends '30d' or '1m'. It clarifies 'value' accepts ticker or CIK, and 'type' is only 'company'. This goes beyond the schema's 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 begins with concrete example queries and explicitly states it is a change feed for a company. It distinguishes itself from the sibling 'entity_profile' tool, which is for static profiles. The verb 'fan out' and listing of sources (SEC EDGAR, GDELT, USPTO) makes the action and resource very clear.

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

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

The description provides explicit guidance on when to use this tool versus 'entity_profile' (static profile). It also explains internal fallback logic (GDELT preferred, GNews when rate-limited) and soft-fail behavior for USPTO. This gives clear context for expected behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds the output range (0..1) and clarifies it's a semantic-relatedness score, which is not in annotations. No contradictions. However, it does not detail the model or knowledge base used.

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?

Single sentence, no wasted words. The key details (what it does, output range) are front-loaded. Highly concise.

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

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

Output schema exists, so return value details are not needed. The description covers the core functionality. It could mention the underlying data source or default language handling, but the schema examples and parameter descriptions provide sufficient context. Missing use case guidance slightly lowers completeness.

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

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

Input schema coverage is 100% with descriptions for each parameter. The description does not add new meaning beyond the schema (e.g., 'node1' and 'node2' are already described). 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?

Clear and specific: 'Semantic-relatedness score (0..1) between two terms.' The verb 'compute' is implied, and 'score (0..1)' defines the output. It distinguishes from sibling tools like compare_entities or entity_profile by focusing on a numeric relatedness score.

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. Lacks mention of use cases or when not to use. Sibling tools include other semantic/lookup tools, but the description does not differentiate.

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

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

Adds significant context beyond annotations: scoping by identifier, persistence differences (authenticated vs anonymous), 24-hour retention for anonymous, and cross-session use. 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 compact sentences front-loaded with purpose and usage, followed by essential behavioral details. No extraneous 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?

Fully covers purpose, usage, behavior, parameter hints, and tool relationships. Given two simple parameters, no output schema, and rich annotations, no gaps remain.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds naming conventions (e.g., 'subject_property') and usage context, providing slight additional value beyond schema.

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

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

Clearly states 'Save data the agent will need to reuse later' with specific examples (resolved ticker, target address, user preference) and distinguishes from siblings recall and forget.

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

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

Explicitly instructs when to use ('when you discover something worth carrying forward') and pairs with recall/forget, providing clear usage context and alternatives.

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

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

Annotations already mark this as readOnly/idempotent, and the description adds substantial behavioral detail: internal multi-endpoint cascade, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` reporting, and ambiguity handling via `figi_candidates`. This goes well beyond the annotations and gives the agent accurate expectations for edge cases.

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 it is organized with clear sections and dense with necessary nuance for a multi-source resolver. It front-loads the core purpose and usage rule, while later details cover edge cases; still, it could be slightly more compressed without losing 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?

With no output schema, the description sufficiently characterizes return behavior: which identifiers are produced for each type, source labeling, unresolved fields, candidate lists for ambiguous matches, and RxNorm citations. Given the tool's complexity, this is a complete enough contract for an agent to select and call it correctly.

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

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

The schema already covers both parameters fully, and the description adds significant complementary guidance: accepted value forms per type, ticker/CIK/ISIN/name options, and a crucial caution about passing only the issuer name rather than the full noun phrase. This materially improves correct invocation.

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 concrete user queries and immediately states the core purpose: resolve a user-spoken name to canonical/official identifiers. It clearly specifies supported entity types and the identifier domains (CIK, ticker, LEI, FIGI, RxCUI), making the tool's scope unambiguous and distinct from general lookup or profile 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?

It explicitly says 'Use FIRST whenever you have a name but need an ID' and gives supported types plus examples of valid input forms. However, it does not name sibling alternatives or describe when one of those should be preferred over resolve_entity, so the routing guidance is strong but not fully comparative.

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

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

The description adds behavioral detail beyond annotations: 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and specifies return fields (score, confidence, signal density). Annotations already indicate safety (readOnly, idempotent), so bar is lower; description enhances 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 concise (~3 sentences), front-loaded with purpose, and uses clear language. No unnecessary words or repetition, though it could include a bit more structure for readability.

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

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

The description covers main functionality but lacks details on error handling, edge cases (e.g., entity not found), or interpretation of returned scores. Given no output schema, additional context on return format would improve completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value: 'First entry treated as subject for narrative' and 'Omit for just workers-ai' for models. This provides practical guidance beyond parameter descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and returns a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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 explicit usage context: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use against alternatives (e.g., instead of ai_visibility_check for single entity) but does not explicitly mention when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds beyond this: explains the composite nature (fans out across deps.dev and bundlephobia), mentions partial failures and timing (bundlephobia first measurement 5-30s), and sources_failed list. No contradictions.

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

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

The description is a single paragraph but dense with information. It front-loads the composite nature. While it could be broken into bullet points, it remains clear and efficient.

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

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

No output schema exists, but the description explains the return structure (summary block, per-advisory detail, links, alternative versions) and covers edge cases like partial failures. It is fairly complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds additional context: explains the default version behavior and that scoped packages are accepted, adding value beyond the schema.

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

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

The description clearly states the tool's purpose as a composite check for npm packages covering license, advisories, and bundle size. It distinguishes itself from siblings by specifying the ecosystem (NPM) and mentioning alternative tools like deps.dev:version.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small"...' It also notes limitations: NPM only in v1, and mentions partial failures. This provides clear when-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, idempotentHint, non-destructive. Description adds significant behavioral details: truncation cap (200K chars), embedding model (BGE-base-en), window size (500-char overlapping), offset feature. 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 concise sentences, front-loaded with purpose. Every sentence earns its place: function, use-case, technical details. Zero waste.

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 fully covers return format (passages with offsets and similarity scores). Also covers limits, model, truncation, and pairing with sibling. Complete for a tool with 3 simple params.

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

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

Schema covers all 3 params with descriptions. Description adds meaning: explains query parameter with example queries ('supply-chain risk', 'fiscal year 2024 revenue'), clarifies the truncation behavior for text parameter, and mentions output features (offsets, scores) not otherwise documented.

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 semantic search inside a fetched record, specifies inputs (text + query) and output (top-N passages with offsets and similarity scores). It distinguishes from siblings by explicitly pairing with ask_pipeworx_grounded and contrasting with fetching full records.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and highlights context-saving benefit. Also provides an alternative workflow with ask_pipeworx_grounded, giving clear when-to-use guidance.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: returns subscription id, OAuth requirement, supported event types with examples, delivery channel options with specific constraints (SMS phone verification, 10/day cap, webhook HMAC signing, auto-disable after 10 failures). Exceeds annotation coverage.

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: starts with action, then requirement, supported types, delivery channels. Every sentence adds value. Slightly lengthy but appropriate given the detail needed for complex subscription types. Could be slightly more concise, but no waste.

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 (3 parameters with nested objects, no output schema), the description is complete. It explains return value (subscription id), all type-specific parameters, delivery options with restrictions, and prerequisites. No apparent gaps that would hinder an agent's correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning: explains enum values with real-world examples (e.g., sec_8k items field), details type-specific params structure, and elaborates on delivery sub-fields including security (webhook HMAC) and rate limits (SMS cap). This provides clarity beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' This is a specific verb+resource combination. The tool is meaningfully distinguished from siblings like list_subscriptions, unsubscribe, and recent_alerts, which serve different functions.

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 a prerequisite (Pipeworx OAuth account required, anonymous/BYO cannot persist), which guides when to use. It mentions the always-on feed available via recent_alerts as an alternative for pulling alerts without subscribing. However, it could more explicitly contrast with other tools or state when not to use subscribe.

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. The description adds that it returns example questions with exact tool and argument shapes, drawn from a live catalog, and differentiates behavior with/without the topic argument. 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 front-loaded with synonyms and purpose, then explains output and usage. It's a bit long but every sentence adds value. Could be slightly more concise but still well-structured.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description thoroughly explains what it returns (category-bucketed example questions with tool+argument shapes) and how to call it. No gaps for the intended 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 is 100% (one parameter fully described). The description adds meaning by explaining the effect of omitting vs. providing 'topic' (full spread vs focused), and lists example values beyond the schema's enum list.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by indicating it should be used first when the agent doesn't know what Pipeworx can do.

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

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

Explicitly recommends using this tool first when unfamiliar with Pipeworx, and offers to focus on a topic by passing a parameter. It also implies when not to use it (if already know what to ask).

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

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

Discloses that the row is deactivated (not deleted) and that historical events remain available, which goes beyond the annotations (destructiveHint=false). 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?

Two sentences, each adding value. First sentence states action and constraint, second explains behavioral effect. 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?

Complete for a simple mutation: covers purpose, usage constraint, and behavioral effect. No output schema needed.

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

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

Schema covers 100% of parameters with description for 'id'. Description adds no extra meaning beyond the schema, so baseline score applies.

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

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

Clearly states the action (cancel) and resource (subscription). Distinguishes 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?

Mentions ownership enforcement and that only own subscriptions can be canceled, providing clear context. However, no explicit comparison to alternative 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 readOnly/openWorld/idempotent annotations, the description discloses critical non-obvious behavior: 'could_not_verify' means the check did not happen and includes a verification_error object, while 'unsupported' means no source covers the claim. This prevents misinterpretation and adds real value beyond annotations.

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

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

The description is longer than ideal but every sentence contributes distinct information: example intents, usage scope, routing logic, return payload, error semantics, and performance benefit. It is front-loaded with the query patterns and logically organized, though a tighter edit could remove minor 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?

There is no output schema, so the description compensates well by specifying the verdict set, the grounded/structured value with pipeworx:// citation, and reasoning. It also explains the two failure-like verdicts and the tolerance behavior. This is comprehensive for a complex tool.

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

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

The input schema already fully documents both parameters (claim and tolerance_pct), so the baseline is 3. The description adds practical nuance—tolerance_pct overrides the wording-implied tolerance and recommends setting 1–2 for hallucination detection—offering guidance beyond the schema.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, provides example phrasings, and distinguishes itself from siblings by detailing the two processing paths (SEC EDGAR/XBRL for financial claims, grounded pipeline for others) and noting it replaces 4–6 sequential calls. This is a specific verb+resource with clear differentiation.

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

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

Explicitly says to use whenever the agent needs to check whether something a user said is factually correct, and divides claims into company-financial vs any other, giving clear scope. It does not explicitly name sibling tools as alternatives or state when-not-to-use, so it stops short of a 5.

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