Data Denver

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

Adds details beyond annotations: cost implications (free vs. Anthropic BYO), return format (score, confidence, signals, raw_response, combined view). No contradiction with readOnlyHint=true or other 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?

Single paragraph with key information front-loaded (action, resource, scoring). Efficient but could benefit from slight restructuring (e.g., separating return format). No wasted sentences.

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, description fully explains return values and structure. Covers prerequisites (API key), default behavior, and use cases. Complete for a probing tool with simple input parameters.

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

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

Schema coverage is 100%, but description adds value by explaining default model behavior for 'models' parameter and how '_apiKey' is passed through. Clarifies context parameter usage for disambiguation.

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

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

Description uses specific verb 'probe' and resource 'LLMs' with scoring of visibility. Clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' and 'ask_pipeworx' by focusing on brand visibility across models.

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

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

States use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and gives context on default model vs. Anthropic with key. Lacks explicit when-not-to-use but provides clear situational 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context by revealing it routes to 5,743 tools, fills arguments, returns structured answers with stable citation URIs, and works on every tier in one fast call. It does not mention limitations or failure modes, but the additional routing and output details exceed the baseline.

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-organized and front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'). Examples and sibling routing are clearly separated. Minor redundancy exists ('START HERE' restates the already-emphasized default status), but the length is justified by the breadth of the tool.

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

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

For a broad, open-ended question-answering tool with no output schema, the description covers the essential context: what domains it handles, what kinds of queries trigger it, how it differs from alternatives, and what the return value looks like (structured answer with citation URIs). An agent has enough information to invoke it appropriately and understand the response shape.

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

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

Schema coverage is 100% with clear descriptions for the question parameter and its aliases, so the baseline applies. The description adds example queries and trigger phrases, but these are usage illustrations rather than new parameter-level semantics. No significant meaning beyond the schema is provided.

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

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

The description clearly states the tool routes natural-language factual questions to over 5,000 domain tools and returns structured answers with citations. It explicitly contrasts with web search and sibling tools like ask_pipeworx_grounded and deep_research, removing ambiguity about what this tool uniquely provides.

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: prefer over web search, use as the default starting point, and step up to named alternatives only for specific needs. It provides concrete example queries and even mentions breaking-news handling, leaving little to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond that: candidate routing improvements are enabled live during tests, no candidate is currently active, the tool falls back to nothing, and it is a full working router rather than a wrapper. This clearly sets expectations for an experimental edge.

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

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

The description is compact and front-loaded: it states the beta relationship, lists concrete equivalences, explains the current candidate state, and gives a direct usage instruction. The specific number of tools and the retirement date add useful context without excessive 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?

For a simple single-required-parameter tool with rich annotations and no output schema, the description covers the essential context: what the tool does, how it behaves experimentally, when to use it, and what it falls back to. The referenced 'same response shape' assumes knowledge of ask_pipeworx, but that is acceptable given the sibling context and explicit naming.

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

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

Schema description coverage is 100% and the schema already documents the 'question' parameter plus five aliases. The description adds that the tool takes 'the same arguments' as ask_pipeworx and produces the same response shape, but it does not add per-parameter meaning beyond the schema. A baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx: an identical universal router with the same 5,743 tools, arguments, and response shape. It distinguishes the tool from its stable sibling and from ask_pipeworx_grounded by explaining its experimental role and current behavioral equivalence.

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 it exactly like ask_pipeworx when you want the newest routing' and notes the current state where no candidate is active so it matches ask_pipeworx exactly. It does not explicitly discuss when to prefer ask_pipeworx_grounded, but the use condition versus the stable router is clear.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: the refusal contract with exact refusal_reason values, the evidence/verbatim-quote return shape, the 'ONLY what the tool result contains' guarantee, and the extra LLM call cost. An agent knows this tool will refuse rather than invent.

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 efficient: purpose, return contract, usage rules, and cost tradeoff are covered in a few sentences, with the core behavioral guarantee front-loaded. The detail about refusal reasons is warranted and not filler.

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

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

For a one-parameter tool with no output schema, the description essentially supplies the output schema (success shape and refusal object with all refusal reasons), the hallucination-resistance guarantee, and the selection tradeoff against ask_pipeworx. Nothing needed to call it correctly appears 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?

Parameter schema coverage is 100%, including all five aliases for the single required question parameter, so the schema already handles parameter meaning. The description adds no parameter-level detail beyond indicating natural-language questions, so the 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 names a specific mode ('hallucination-resistant answer mode'), a concrete workflow ('picks the right tool... fetches the data... EXTRACTS the answer using ONLY what the tool result contains'), and immediately contrasts it with ask_pipeworx. An agent can distinguish this grounded variant from the sibling list without opening schemas.

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

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

States explicit usage conditions: use when an answer will be quoted, cited, or acted on and facts must not be invented, with example domains (financial verdicts, legal claims, medical lookups). It also gives the exclusion—prefer ask_pipeworx for casual lookups—and notes the extra LLM call cost, guiding tool 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing market resolution, classifier fan-out, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, wide-spread handling, and cancellation rule parsing.

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 (~500 words) but well-structured with bold section headers (e.g., CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) and front-loaded core purpose. While comprehensive, some redundancy could be trimmed for an AI agent.

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

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

Given the tool's complexity (multiple classifiers, fan-out sources, detailed response fields, error handling), the description is fully complete. It covers all response shapes, edge cases (low confidence, closed markets, wide spreads), and cancellation rules—essential since no 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 coverage is 100%, and the description adds significant value: it explains depth options ('quick = 2-3 evidence sources'), market parameter types (slug, URL, text), and include_raw summary vs full payload, which is not in the schema descriptions.

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

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

The description clearly states the verb ('Research') and resource ('Polymarket bet') and method ('pulling Pipeworx data'), and distinguishes from sibling tools like 'ask_pipeworx' by emphasizing the fan-out and classification logic.

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

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

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), though no direct alternative tools are mentioned. The context from sibling names implies when not to use this tool.

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

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

Annotations indicate safe read-only, idempotent behavior. The description adds meaningful context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/Trials for drugs), fiscal year handling, and result sorting, going beyond annotations.

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

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

The description is dense but well-organized, front-loading key purpose and usage. Every sentence adds value, though it's a single paragraph without explicit structure.

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, description adequately explains return data (paired data + citation URIs) and data freshness. Rich annotations compensate for any gaps, but a note on auth or rate limits could 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 clarifies enum values and array constraints but doesn't add format details beyond schema.

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

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

The description explicitly states the tool compares 2-5 companies or drugs side-by-side in one parallel call, with example queries and clear distinction from sequential lookups.

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

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

The description explicitly instructs to prefer this over sequential lookups and details when to use for company vs drug types, providing clear guidance on appropriate contexts.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral context: account/paywall requirements, parallel tool routing, evidence-and-citation return format, explicit gaps[] for unanswered facets, contradiction scanning, hop fields, fetchable citation URIs, semantic excerpting, and latency expectations. No contradiction with annotations is present.

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

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

The description is long but information-dense, and the most decision-critical facts (account requirement, fallback tool, not-open-web positioning) appear early. Every sentence contributes functional guidance, though the density and length could be slightly 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 fully compensates by explaining what the findings packet includes: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri resolvability. It also covers auth, cost tiers, latency, and fallback behavior, making the tool actionable for an agent.

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

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

Schema coverage for both parameters is 100%, so the schema already documents question and depth. The description adds meaningful context beyond it: how depth affects hops and contradiction scans, that 'thorough' requires a paid plan, that broad questions are acceptable, and how facets are decomposed. Not a full 5 because the schema already carries the core parameter semantics.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing them in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can differentiate it from siblings without opening schemas.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, while single lookups and breaking/colloquial current-news topics should go to ask_pipeworx. It also names the fallback for unsigned-in users and explains depth-level tradeoffs, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's addition of 'for discovery' and the return of layer id+name adds moderate behavioral context. No contradictions, but no extra details on auth or rate limits.

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

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

Two sentences, no extraneous words. Front-loaded with the core purpose and then details on usage. Every sentence adds value.

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

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

For a simple discovery tool with one optional parameter and no output schema, the description covers input options, output purpose, and relationship to denver_query. No gaps.

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

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

Schema description coverage is 100%, and the description largely mirrors the schema's parameter description (e.g., short name, full path, omit to list services). The examples in the schema add value, but the description does not significantly augment 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 verb 'List' and the resource 'layers of a Denver ArcGIS service (for discovery)'. It specifies how to use short names or full paths and what happens when 'service' is omitted, distinguishing it from sibling tools like denver_query and denver_recent.

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

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

The description explains when to omit the service parameter to list known services, and how to pass short names or full paths. It notes the output is for use with denver_query, providing context for tool chaining. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds: 'Epoch dates are converted to ISO.' This is a behavioral trait 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?

The description is two sentences: the first defines core purpose, the second adds usage guidance and a key detail. Every sentence is essential and front-loaded. No redundant 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?

The tool has 6 parameters (2 required), no output schema. The description explains the query capability, links to related tools, and mentions date conversion. It covers the main use case. Minor gaps: no mention of error handling or response structure, but these are less critical for a query tool with clear parameter semantics.

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 documents all parameters. The description adds value by providing examples (e.g., 'service: crime' as a short name), defaults (where: '1=1', limit: 100, max: 2000), and format guidance for order_by. This enriches understanding beyond the raw 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: 'Query any Denver ArcGIS layer by service path + layer id.' It specifies the verb (query), resource (Denver ArcGIS layer), and scope (by service path and layer id). It distinguishes itself from sibling tools like denver_layers and denver_recent by focusing on query execution.

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 advises: 'Use denver_layers to find a service/layer, or denver_recent for the common ones.' This provides clear context and alternatives. It does not explicitly state when not to use the tool, but the guidance is strong.

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

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

Describes return order (newest-first) and date conversion (ArcGIS epoch to ISO), adding context beyond the readOnlyHint and idempotentHint annotations.

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

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

Three sentences, each packed with essential information—no wasted words, clear and efficient structure.

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

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

Explains return format and dataset naming; references siblings for deeper queries. Lacks error/rate-limit details but annotations cover safety. Adequate for a simple 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%; description adds minor context (date conversion, filtering hint) but doesn't significantly enhance param understanding beyond the schema definitions.

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

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

The description clearly states it returns recent records from Denver open data, specifies the source (ArcGIS), and distinguishes from web search and sibling tools like denver_layers and denver_query.

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 'PREFER OVER WEB SEARCH for recent crime in Denver', and provides guidance on using the where parameter for filtering, with references to sibling tools for other layers.

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 and idempotentHint. Description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call. Describes behavior beyond annotations without contradiction.

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

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

Approximately 5 sentences, well-structured: purpose first, then examples, return format, and usage advice. Every sentence adds value; no fluff.

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

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

Given no output schema and a discovery use case, description covers purpose, input, and return format (names, descriptions, schemas). Could briefly mention ranking criterion, but sufficient for selection.

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%. Description adds meaning by clarifying that query accepts multiple aliases (task, q, description, search) and provides natural language examples. Adds value beyond raw schema fields.

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

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

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' Lists diverse examples and emphasizes returning full schemas ready to call. Distinct from siblings by specifying it's the first call to explore the option set.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context and alternative guidance.

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

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

Annotations only cover read-only/idempotent safety; the description adds substantial runtime behavior: parallel fan-out across SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, GDELT/GNews, and GLEIF; patents soft-fail; an empty FDA section is expected; `sources_used`/`sources_failed` indicate real no-data; and private companies return resolved:false with notes. This makes call outcomes highly predictable.

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 organized, with the core capability front-loaded and return sections enumerated with semicolons. However, it is verbose: seven near-synonymous example phrasings and some redundancy with the schema keep 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?

There is no output schema, and the description compensates by enumerating every major return block (recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) plus failure and empty-result semantics. For a tool with this many sources and edge cases, nothing essential to invoking it 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?

The input schema already covers both parameters at 100%, so the baseline is 3. The description adds concrete formats: zero-padded CIK ('0000320193'), company-name resolution via SEC EDGAR, and the explicit note that 'company' and 'ticker' are interchangeable. That extra nuance justifies above baseline.

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

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

The opening line states the core function: 'full cross-source profile of a US public company in ONE parallel call.' The examples ('brief me on Tesla', 'what does Apple do') map directly to user intent, and the contrast with 'chaining single-pack SEC/XBRL/news lookups' distinguishes it from narrower alternatives.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which gives a strong when-to-use trigger and the alternative pattern to avoid. It does not enumerate exclusions or compare directly with sibling tools like resolve_entity or compare_entities, so it is not a perfect 5.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Delete' verb is consistent. The description adds context about clearing sensitive data, but no additional behavioral traits beyond what annotations provide. No contradiction.

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

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

Three sentences with no wasted words: first sentence states the action, second provides usage context, third mentions related tools. Efficient and front-loaded.

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

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

For a simple tool with one parameter, the description covers purpose, usage, and relationships. No output schema needed. Complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. The description ('by key') adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly stating the tool's function. It also distinguishes itself from sibling tools like 'remember' and 'recall' in the last sentence.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with 'remember' and 'recall'. Lacks explicit when-not cases, but still offers clear 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown. It also says the output is a single text blob for site-root/llms.txt, which is useful context beyond annotations.

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

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

The description is concise: two sentences plus a list of use cases. Every sentence adds value, and the main action is front-loaded. No redundant information.

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

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

Given the tool has only 2 parameters, full schema coverage, and rich annotations, the description adequately explains the output format and what is extracted. No gaps remain for the agent to understand the tool's behavior.

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

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

Schema description coverage is 100% with both parameters documented. The description does not add significant meaning beyond the schema; it mentions URL and max_links but the schema already includes defaults and limits. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Generate', the resource 'llms.txt file', and the scope 'for any URL'. It explains the process (fetch, extract, emit) and distinguishes itself from sibling tools which have different 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?

The description explicitly lists three use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor. It does not mention when not to use or alternatives, but the use cases are clear and relevant.

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, so description's mention of return fields adds marginal value. 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?

Two sentences, efficient and front-loaded with purpose. Every word earns its place.

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

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

Given the tool's simplicity, single optional parameter, and lack of output schema, the description fully covers its behavior and return fields.

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 boolean parameter), and description does not add meaning beyond the schema. Baseline of 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates returned fields (id, type, params, created_at, last_fired_at, fire_count). Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context but lacks explicit when-not-to-use.

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

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

The description discloses key behaviors beyond annotations: filing without an account returns a claim_token which can be passed back to read resolution status, rate-limited to 5 per identifier per day, and free/no quota. It also explains the team reads digests daily, adding roadmap context. No contradictions with annotations.

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

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

The description is longer than typical but every sentence earns its place — purpose, use cases, exclusions, token mechanics, rate limit, and quota. It's front-loaded with the core action and well-structured. Slightly denser than necessary but not wasteful.

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

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

Given no output schema, the description fully explains what happens: returns a claim_token for later lookup, and later returns status/changes. It also covers rate limits, quota, scope, and how the feedback is used. Complete for a feedback 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%, so baseline is 3. The description adds value by clarifying claim_token usage ('pass it back later... with no other arguments') and giving guidance for message content ('describe in terms of Pipeworx tools/packs, don't paste the end-user's 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 clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs (broken, missing, exists) and identifies the resource (Pipeworx team). It also distinguishes itself from sibling research/query tools by clarifying it's only for tools served by this Pipeworx connection.

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

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

The description provides explicit when-to-use guidance: for bugs, feature requests, data gaps, or praise. It also gives a clear exclusion: do not report tools from other MCP servers, and directs users where to file those instead. This fully covers usage vs 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?

Adds context beyond annotations: describes data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and self-aggregating nature. Annotations already declare readOnly, openWorld, idempotent, non-destructive; description enriches behavioral understanding.

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 plus bullet points. Front-loaded with core function, then use cases, then metadata. No extraneous words; every sentence adds value.

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

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

Covers what is returned (top tools, top packs, total call volume), caching, and privacy. Lacks explicit output schema, but for a simple read tool the description is sufficient.

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

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

The schema has one parameter with enum and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose values appropriately.

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

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

Description clearly states it returns top tools, top packs, and total call volume over recent windows. Distinguishes itself from sibling tools like discover_tools and ask_pipeworx by focusing on trending usage data.

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

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

Lists three specific use cases (discovering hot data sources, confirming canonical tool, checking alignment). However, does not explicitly state when not to use this tool or compare to alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) establish safety and idempotency. The description enriches this with detailed behavior: semantic similarity thresholds, placeholder filtering, partition sum checks, and fill check logic. No contradictions exist; the description adds value beyond the annotations.

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

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

The description is fairly long but well-structured, starting with a summary, then breaking into mode details, filters, response format, and fill check. While comprehensive, a slight reduction (e.g., moving some details to a separate note) could improve conciseness without losing critical information.

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

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

Given no output schema, the description thoroughly explains the response structure, including fields like gap_pp, suggested_trade, reasoning, and partition_check in event mode. It covers what happens with each input mode, edge cases (e.g., placeholder filtering), and even warns when the trade is not realizable. The tool's interaction with a sibling tool (polymarket_fill_risk) is noted, ensuring the agent has full 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?

Although the input schema covers both parameters 100%, the description adds significant meaning: it explains the purpose of each parameter, provides real-world usage examples, and details how each mode operates. This helps the agent understand the semantic impact of choosing event vs. topic beyond the schema descriptions.

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

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

The description clearly states the verb 'Find arbitrage opportunities', the resource 'on Polymarket', and the methods 'via monotonicity violations + partition-sum checks'. It distinguishes three distinct modes (no args, event, topic) and uses specific examples, making the purpose unambiguous and well-differentiated from sibling 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?

Explicit guidance is provided for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It includes usage examples, conditions for when not to trade, and references a sibling tool for custom sizing, giving clear when-to-use and when-not-to-use advice.

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 rich behavioral context: data sources (FRED log-returns, GDELT ratio), calculation details (favorite-longshot bias correction, Kelly caps), response structure with diagnostics, and caching behavior. 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 thorough but long (approx. 300 words). It front-loads the purpose but could be more concise. The structure uses paragraphs and some inline lists, making it adequate for an agent but slightly 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?

Despite no output schema, the description comprehensively covers the response structure (by_segment segments, fed_candidates, _diagnostics), per-opportunity fields, caching, and why segments may be empty. This makes the tool well-understood without additional documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the role of parameters like min_partition_leg_kelly in detail, clarifying how tradeable-edge knobs filter opportunities beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and specifies it is built for 'what should I bet on today' for agents. It distinguishes from sibling tools by detailing unique model families and tradeable-edge knobs.

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

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

The description explains the tool helps agents discover opportunities without paging through hundreds of markets, and provides context for when to use tradeable-edge filters. It does not explicitly state when not to use, but the sibling list implies alternatives exist, and the description covers limitations like Fed data unreliability.

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

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

Description adds behavioral traits beyond annotations: response structure (tracked, expired, snapshot_dates), edge_pp_net sign, decay computation (daily closes, not intraday), and bounds (60-day TTL, snapshot enable time). 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?

Description is dense but well-structured, starting with purpose, then response format, then limits. Every sentence adds value, though slightly longer than necessary.

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

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

With no output schema, description fully explains return values and their meaning, including edge_pp_net sign, trend classification, and date gaps. Covers limits and assumptions thoroughly.

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

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

Schema has 100% coverage; description adds default values and clarifies semantics like 'snapshot family' for window. Provides more context than 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 provides edge persistence and decay telemetry from daily snapshots, distinguishing it from sibling tools like polymarket_edges. It answers a specific question: how long an edge has existed and whether it's shrinking, with concrete examples.

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

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

The description implies when to use the tool (for historical trend analysis) and contrasts fresh vs. old edges, but does not explicitly state when not to use or name alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it checks order book depth, walks the ladder, returns verdicts (clean|degraded|cannot_fill), and warns about forced directional risk. No contradiction with annotations.

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

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

The description is long but well-structured with section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the purpose and every sentence adds value. Minor redundancy could be trimmed, but the density 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?

No output schema exists, so the description details many return fields (top_of_book, vwap_fill_price, slippage_pp, etc.). It covers both modes, explains edge cases (thin books, partial fills), and addresses the dominant loss mode. Complete for a risk-check tool.

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

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

Schema description coverage is 100%, and the description adds extra context: explains default values for side and size_usd, clarifies auto-detection for basket mode side, and interprets size_usd differently for single-market vs basket modes.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return fields and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why: theoretical overround on thin books is not capturable and partial basket fills convert arb into unhedged directional positions.

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

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

The description goes far beyond the read-only/idempotent annotations: it discloses that fees are not modeled, that spread_pp is gross, that pairing_unverified is always set, that compatibility warnings can appear even with matched pairs, and that null temporal_alignment means unknown rather than aligned. This gives an agent an unusually honest picture of the tool's limitations.

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 into labeled sections: modes, response, safety fields, codes, skipped counters, and fee disclosure. Almost every sentence adds operational value, though some repetitions (e.g., 'in EITHER mode' and repeated pairing caveats) could be trimmed.

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 must explain return semantics, and it does: leg-by-leg prices, top_spreads_pp, compatibility_codes, flags, skipped_unclassified, temporal_alignment, and fees_note are all described. Together with detailed interpretation guidance for warnings and null values, the agent has what it needs to invoke and interpret 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%, so the baseline is 3. The description adds meaningful extra semantics by explaining how the parameters interact: topic auto-fetches the matching event on each venue, while kalshi_event_ticker and polymarket_event_slug override the mapped sides, and both modes run the identical matcher. This clarifies relationships the schema alone does not.

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

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

The description opens with a clear, specific statement: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from venue-internal or single-source tools by emphasizing cross-venue comparison and naming the exact signed metric (Kalshi − Polymarket).

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 two explicit modes — topic shortcuts vs. explicit kalshi_event_ticker + polymarket_event_slug — are clearly explained, including when to use each. The description also cautions that pre-mapped topics are not automatically tradeable. However, it does not explicitly name sibling alternatives or state when not to use this tool in favor of tools like polymarket_arbitrage or polymarket_edges.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by explaining scoping to the agent's identifier and the dual behavior (retrieve by key or list all). 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 concise sentences with the core action front-loaded. No wasted words; each sentence contributes purpose, context, and pairing 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 simple read tool with one optional parameter and no output schema, the description covers behavior, scoping, and relationships. Annotations handle safety. No 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?

The single optional parameter 'key' is described in the schema. The description adds that omitting key lists all keys, which is meaningful context beyond the schema's type definition.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys, using a specific verb and resource. It distinguishes from sibling tools remember and forget by describing complementary actions.

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

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

Provides explicit context on when to use (to look up stored context without re-deriving) and scoping (by identifier). Mentions pairing with remember and forget, guiding appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: returns specific fields (source, citation_uri, payload), mark_read flag behavior, and polling suitability. No contradictions; adds 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?

Single paragraph, well-structured with purpose first. Each sentence contributes value. Could be slightly more concise but remains clear and informative.

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

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

No output schema, but description explains return fields. Parameters all documented. For a read-only list tool with good annotations, it covers essential behavior (polling, alternative endpoint, usage). Missing explicit pagination details but limit parameter covers it.

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

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

Schema coverage is 100%, so baseline is 3. Description explains 'type' with example 'sec_8k', 'since' as ISO timestamp, and 'mark_read' behavior. However, 'unread_only' is not mentioned in description but is in schema. Adds some meaning but not exhaustive.

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

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

Description clearly states it pulls fired events from the subscription feed, specifying the resource (alerts) and action (pull/return). Distinguishes itself from siblings like subscribe or list_subscriptions by focusing on the alert feed content. Uses specific verb 'Pull' and identifies return fields.

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

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

Description provides explicit usage context: 'Polls work fine' and mentions an alternative access method via a REST endpoint for scripts/dashboards. Lacks explicit when-not-to-use or comparison to other tools, but context is sufficient for most 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, idempotentHint, and destructiveHint=false. The description adds significant behavioral details: parallel fan-out to multiple sources, fallback logic, soft-failure for USPTO, accepted date formats (ISO and relative), and return structure (changes grouped, total_changes count, citations). No contradictions.

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

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

The description is a single efficient paragraph with front-loaded natural language examples. Every sentence adds value without redundancy, covering purpose, sources, fallback, date handling, and return format.

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 absence of an output schema, the description adequately explains the return format (changes grouped by source, total_changes, citation URIs). It covers edge cases (rate limiting, API sunset) and provides complete context for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter: type limited to 'company', since includes examples and recommended '30d' or '1m', value accepts ticker or CIK. This adds practical 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 uses natural language examples ('What's new with X', 'latest on Y') and clearly states it provides a change feed for a company in a time window via one parallel call. It names the three data sources (SEC, GDELT/GNews, USPTO) and distinguishes itself from sibling tool entity_profile.

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

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

The description explicitly tells when to use this tool (e.g., 'news on Tesla recently') and when not to ('Use entity_profile instead when you want the static profile...'). It also explains fallback behavior between GDELT and GNews, providing clear context for tool 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 already declare the tool as non-read-only, non-destructive, and idempotent. The description adds valuable context beyond annotations: scope ('scoped by your identifier'), persistence duration ('24 hours for anonymous sessions'), and that it stores key-value pairs. 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 brief (5 sentences) with the main action front-loaded. Every sentence contributes essential information: purpose, usage guidance, technical storage details, and companion tool references. No redundant or vague language.

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

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

For a simple 2-parameter tool with no output schema and comprehensive annotations, the description covers purpose, usage, persistence, and collaboration with sibling tools. It fully equips an agent to decide when and how to invoke the tool.

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

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

Schema has 100% description coverage for both 'key' and 'value' parameters. The description adds meaning by providing concrete examples of keys ('subject_property', 'target_ticker', 'user_preference') and values ('findings, addresses, preferences, notes'), enhancing usability 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 that the tool saves data for reuse across conversations or sessions, specifying key-value pair storage scoped by identifier. It distinguishes from siblings 'recall' and 'forget' by naming them as companions, ensuring no confusion.

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: 'when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.' It provides context on persistence (authenticated vs anonymous) to guide appropriate usage.

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

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

The description richly discloses behavior beyond annotations: it explains supported types, cross-source identity spine (CIK, LEI, FIGI), graceful degradation if GLEIF/OpenFIGI are unavailable, the handling of unresolved identifiers (explicitly listed under 'unresolved' rather than omitted), and the fact that each call cascades through multiple endpoints. It also states that ambiguous security names yield figi_candidates, which is a critical behavioral trait. No contradiction with annotations.

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

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

The description is lengthy but well-structured. It front-loads the core purpose with examples, then details supported types and special cases. Every sentence carries useful information, though some could be tightened. Given the complexity of the tool, the verbosity is justified, but it could be condensed slightly 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 carries the full burden of explaining return behavior. It covers what identifiers are returned, the unresolved field, figi_candidates for ambiguity, and degradation fallback. It also explains the internal cascade and the replacement of multiple manual lookups. The description is essentially complete for an agent to call this 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?

Although the schema already documents both parameters (100% coverage), the description adds substantial meaning. For the 'value' parameter, it specifies exactly what to pass (entity name only, bond issuer exactly as printed, never the full noun phrase) and gives concrete examples. For 'type', it elaborates on the two enum values and their resolution logic. This goes well beyond the schema's one-line 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 states a clear purpose: resolving user-spoken names into canonical/official identifiers for use by other tools. It provides numerous example queries that illustrate the exact use case, and it explicitly positions itself as the first tool to use when a name needs an ID, distinguishing it from siblings like entity_profile and compare_entities without even naming them.

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

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

The description gives an explicit 'Use FIRST whenever you have a name but need an ID' directive, which is a clear when-to-use instruction. It also provides detailed input formatting guidance (e.g., for bonds, pass the issuer exactly as printed, not the full noun phrase), and explains how the tool handles ambiguous names by returning figi_candidates. This effectively tells the agent when and how to invoke it correctly.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds behavioral details: it probes each entity using ai_visibility_check, ranks results, and returns a list with score, confidence, signal density. It also explains that models can include Anthropic (requiring an API key) and that context disambiguates common names. 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 four sentences, each adding value: first sentence states purpose, second explains mechanism, third gives a concrete usage example, fourth lists output elements. It is front-loaded and concise with 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 the tool's complexity (comparing multiple entities with optional models and context) and the absence of an output schema, the description covers all parameters and describes the output format (ranked list with score, confidence, signal density). It does not cover potential errors or limits, but the tool's purpose is well-explained.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema: it explains that the first entity is treated as the 'subject' for narrative, that 'workers-ai' is the free default model, that '_apiKey' is only needed if 'anthropic' is in models, and that context disambiguates common names. This provides helpful context for parameter usage.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities). It also distinguishes from the sibling tool 'ai_visibility_check' by implying this is for multi-entity comparison, and mentions probing each entity with that tool.

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 a concrete use case: 'competitive AI-marketing audits' and an example question ('does Claude know about us as well as our competitors?'). It implies when to use this tool (multi-entity comparison) but does not explicitly state when not to use it or name alternatives, though the context suggests using ai_visibility_check for single entities.

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 safe read-only operation. Description adds critical behavioral context: fans out across multiple services, potential 5-30s delay for bundlephobia first measurement, graceful degradation with sources_failed field. 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?

Single dense paragraph, front-loaded with purpose. Every sentence adds value, but could be slightly restructured for readability. Efficient use of words given the complexity.

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

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

No output schema, so description must explain returns. It does so thoroughly: summary block fields, per-advisory details, links, alternative versions. Also covers error handling and ecosystem scope. Nothing missing for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by noting that version defaults to latest and that scoped packages are accepted. While schema already describes parameters, the description provides additional usage 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?

Description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It specifies the verb (scan/check), the resource (npm packages), and distinguishes from siblings by being a multi-source composite call.

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

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

Explicitly states when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear when-not-to-use guidance.

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

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

Discloses technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)'. Annotations already indicate idempotent and read-only, and description reinforces safe behavior. 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 paragraph of 5 sentences. Every sentence adds distinct value: purpose, use case, pairing suggestion, technical details, and limitations. No fluff.

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

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

For a tool with no output schema, the description clearly explains what is returned (top-N passages with character offsets and similarity scores). Covers essential behavioral aspects (embedding method, window size, character limit, truncation flag). Complements annotations and schema perfectly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing examples for the 'query' parameter (e.g., 'supply-chain risk') and clarifying that the 'text' parameter takes fetched document text. Also implicitly describes output (character offsets, similarity scores). Adds meaningful context beyond schema.

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

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

Explicitly states 'semantic search INSIDE a fetched record' with clear verb (search) and resource (inside fetched text). Distinguishes from siblings by specifying it works within a given text and pairs with 'ask_pipeworx_grounded' for grounding. No ambiguity.

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 usage scenario: 'Use when the record is too big to cram into the prompt—search_within saves context'. Also explains benefits (returning only relevant passages with offsets for verification) and suggests pairing with another tool ('ask_pipeworx_grounded'). Comprehensive 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 indicate write behavior (readOnlyHint=false) and description confirms creation. Description adds value beyond annotations by disclosing OAuth requirements, SMS rate limits, and one-time webhook secret, but omits explicit mention of idempotency hinted by annotations.

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

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

The description is front-loaded with the core purpose, then details types and delivery. While lengthy, every sentence provides necessary information for correct invocation, earning its place without significant 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?

The description covers all necessary aspects: purpose, subscription types with parameters, delivery options with constraints, and prerequisites. Despite no output schema, it specifies 'Returns the new subscription id', making it complete for a complex tool.

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

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

Schema coverage is 100%, providing baseline of 3. However, the description adds significant detail beyond the schema: specific examples for each type (e.g., items:['5.02'] for sec_8k) and constraints for delivery (phone verification, 10/day cap), which enhances 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 states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly indicates the tool's action and result, distinguishing it from siblings like list_subscriptions or unsubscribe.

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

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

The description explains usage context with delivery channels referencing recent_alerts as a way to pull from the feed, but does not explicitly contrast with siblings like list_subscriptions or unsubscribe. Still, it provides sufficient context for choosing when to use this tool.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds return structure details (category-bucketed examples with tool shapes) and explains behavior (full spread vs topic focus). Adds useful context 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 thorough but could be trimmed; it front-loads the core purpose and lists categories efficiently. Given the complexity, it strikes a good balance.

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 description fully explains return format (category-bucketed examples with tool/argument shapes) and covers use cases (getting started, learning meta-tools). Complete for an onboarding tool.

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

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

Schema coverage is 100% with parameter description. Description adds value by clarifying default behavior ('Omit for a cross-category spread') and reiterating the enum focus areas.

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

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

The description clearly defines the tool as an onboarding entry point that returns category-bucketed example questions with tool and argument shapes, distinguishing it from query siblings like ask_pipeworx.

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

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

Explicitly states to use this first when unsure of what Pipeworx can do, and mentions passing topic to focus, with clear alternatives like meta-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?

Adds significant behavioral context beyond annotations: ownership enforced, deactivation vs deletion, and historical event availability via recent_alerts. Aligns with annotations (non-destructive, idempotent).

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

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

Two sentences, all information is relevant and front-loaded. No fluff.

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

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

Tool is simple (1 param, no output schema). Description fully covers purpose, side effects, ownership, and references sibling tool for historical data.

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%; the description mentions 'by id' but adds no extra meaning beyond the schema's parameter description. 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?

The description clearly states the action (cancel), the resource (subscription), and the identifier (by id). It distinguishes from sibling tools 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?

Explicitly states ownership enforcement (only your own subscriptions) and outcome (deactivation, not deletion). Does not mention when to avoid using or alternatives, but context is clear.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by explaining the two processing paths, enumerating all six verdict categories, and crucially distinguishing 'could_not_verify' (with verification_error, not evidence) from 'unsupported' (no source coverage). This is valuable behavioral context that prevents misinterpretation of results and is not available from annotations or schema.

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

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

The description is somewhat long, but it is front-loaded with usage examples and each section (routing, verdicts, error semantics, replacement value) adds distinct, non-redundant information. It is well-organized and every sentence contributes, though a tighter structure could have been slightly more 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?

Even though there is no output schema, the description fully specifies return values (verdict, actual value with citation, reasoning), explains all verdict outcomes, details error semantics (verification_error, unsupported vs could_not_verify), and outlines the two routing paths. This is a complete operational spec for an agent to invoke the tool correctly and interpret 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?

Schema description coverage is 100%: both 'claim' and 'tolerance_pct' are already well-documented with examples and semantics. The description does not add further parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description explicitly identifies the tool as a natural-language claim verification tool with concrete example phrasings ("Is it true that…", "fact check"), a clear verb-resource pair (verify claim), and differentiates it from generic lookup tools by stating it replaces 4–6 sequential calls. The purpose is unmistakable and distinct from sibling tools.

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

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

Provides explicit guidance: "Use whenever the agent needs to check whether something a user said is factually correct" and outlines two routing paths (SEC EDGAR for financial claims, grounded pipeline for other factual claims). It notes the tool replaces a multi-step process, which implies a preference over sequential calls. However, it does not explicitly name alternative sibling tools or state when not to use them, so it falls slightly short of a 5.

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