Cfpb

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by specifying cost implications (BYO key for Anthropic), default model, and return structure (per-model {score, confidence, signals, raw_response} + combined view). 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?

Three sentences: first states main action and return, second covers model options and cost, third lists use cases. No redundant information. 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?

No output schema, but description adequately covers return structure. It explains default model and optional Anthropic probing. Could mention parallel probing or response time, but overall complete for a probe tool with 4 parameters and good annotations.

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%, baseline 3. Description adds significant meaning: explains 'entity' as brand/business topic, lists model options, clarifies '_apiKey' for Anthropic pass-through, and 'context' for disambiguation. This goes beyond 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?

Description clearly states it probes LLMs for brand visibility and scores (0-100) per model. Verb 'probe' is specific, resource is LLMs, and it distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on entity-specific knowledge scoring.

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 explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and when to provide an API key for Anthropic. However, it does not explicitly state when NOT to use it or compare with alternative tools among siblings.

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

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

Annotations already mark this read-only, idempotent, and non-destructive, and the description adds valuable behavioral context: it routes to any of 5,767 tools, fills arguments automatically, and returns answers with stable pipeworx:// citation URIs. It also explicitly discloses limits such as avoiding non-verifiable topics, which goes beyond the structured annotations.

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

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

The description is front-loaded with the most important guidance ("PREFER OVER WEB SEARCH") and uses helpful examples and explicit alternatives. It is somewhat redundant in the latter half, repeating the deep_research and news-routing advice, but the content remains substantive and organized.

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

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

For a tool with only one meaningful parameter and no output schema, the description provides a complete picture: when to use it, what it does with the question, what kind of answer to expect (structured, cited with pipeworx:// URIs), and which situations to avoid. The examples give the agent concrete expectations for invoking it correctly.

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

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

The input schema already documents the question parameter and all aliases, so the baseline is 3. The description adds real value beyond the schema by spelling out the types of questions that are valid, providing concrete examples, and framing the parameter as a natural-language factual query rather than just a generic string.

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 the tool as a query router that answers factual, current or historical data questions using verified sources and returns structured answers with stable citation URIs. It names the exact scope (SEC, FDA, economic stats, patents, news, etc.) and differentiates itself from siblings like deep_research, validate_claim, and ask_pipeworx_grounded.

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

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

Provides explicit when-to-use triggers ("what is", "look up", "find", "get the latest"), when to prefer it over web search, and when-not-to-use conditions (experiments, unreleased features, opinions). It also names concrete alternatives for overlapping cases: deep_research for multi-part synthesis, validate_claim for claim verification, and ask_pipeworx_grounded for single facts needing trustworthy citations.

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, non-destructive behavior, and the description adds useful context beyond them: candidate routing improvements are enabled live only during tests, none are currently active, and the tool is a full working router rather than a fallback. No annotation contradiction.

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

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

The description is compact and front-loads the essential identity (beta version, identical router) before current status and usage. Each sentence contributes either scoping, behavior, or usage context, though the parenthetical list and retirement date add slight density without hurting clarity.

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

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

Given the complexity of a universal router and no output schema, the description covers current status, usage, and fallback behavior well. However, the return value is only described indirectly as 'same response shape' as ask_pipeworx; without that sibling's definition, an agent would not know what the response contains. Still, this is a minor gap because the schema and sibling context cover most invocation needs.

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

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

Schema description coverage is 100%, so the schema already documents the parameter and its aliases. The description adds only that the arguments are the same as ask_pipeworx, which is helpful for comparison but does not materially extend the schema's parameter semantics. 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?

Description states a specific resource ('beta version of ask_pipeworx') and a clear behavior: an identical universal router with candidate routing improvements. It explicitly names the stable sibling ask_pipeworx and distinguishes this tool as the experimental edge, so an agent can tell them apart from the description alone.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing and notes that results are compared to the stable router. It also clarifies that with no active candidate it matches ask_pipeworx exactly. It lacks an explicit 'do not use this when' statement, but the beta/'experimental edge' framing implies the stable alternative.

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

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

Annotations cover read-only, open-world, and idempotent behavior, and the description adds substantial context beyond that: refusal reasons, the structured response shape, the guarantee that answers derive only from tool results, and the cost tradeoff of one extra LLM call. No contradiction with annotations.

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

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

The description is longer than average but every segment carries information: behavior, routing, return contract, refusal reasons, use cases, and cost. It is front-loaded with the most important distinguishing phrase and does not waste words, though the tool-source count detail ('5,767 across 1506 sources') is slightly extraneous.

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 — routing, extraction, refusal states, and tradeoffs against a sibling — the description is complete. An agent can decide when to invoke it, what to expect on success and failure, and how it differs from ask_pipeworx without any information beyond this text and the provided schema/annotations.

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 documentation covers 100% of parameters, so the baseline is 3. The description mentions that the tool fills arguments automatically and accepts a natural-language question, but it does not need to add parameter-level detail since the schema already describes the question parameter and its aliases.

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

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

The description opens with a specific, meaningful label — 'Hallucination-resistant answer mode for high-stakes reads' — and states the exact behavior: extracts answers using only tool result contents. It explicitly contrasts with ask_pipeworx ('Same routing as ask_pipeworx'), making the distinction between siblings clear.

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

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

It gives explicit when-to-use guidance: when the answer will be quoted, cited, or acted on, and when facts must not be invented (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative and the condition for preferring it: 'prefer ask_pipeworx for casual lookups.'

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

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

The description extensively details behavioral traits beyond annotations: resolver contract with confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits for low confidence, closed market handling, illiquid spread warnings, and resolution-rule risk. All consistent with annotations (readOnly, idempotent, non-destructive).

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

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

The description is very long and dense, but well-structured with clear sections (purpose, classifiers, fan-out examples, response shapes, resolver contract, etc.). It is not concise, but the structure helps readability. Still, it could be more streamlined.

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

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

The description is comprehensively complete for a tool with 3 parameters and no output schema. It details response shapes, error states (low confidence, closed markets, wide spreads), cancellation rules, and news behavior. Covers all edge cases a user needs to know for correct invocation and interpretation.

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

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

The input schema already provides complete descriptions for all three parameters (100% coverage), including examples, enums, and defaults. The description adds minimal new info beyond repeating parameter behaviors (e.g., depth defaults, include_raw summary). Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and unique approach (one-call Pipeworx data pull). The tool is clearly differentiated from siblings like ask_pipeworx or polymarket_arbitrage by its specific focus on individual bet research.

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

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

The description provides explicit usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives fan-out examples for different bet types. However, it does not explicitly state when not to use the tool or suggest alternatives, which would make it a 5.

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

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

Annotations mark the tool as read-only and safe, and the description adds behavioral context: it explains automatic normalization of common names to registered spelling, that the response will indicate the actual queried name, and that output includes narratives, company responses, and resolution details sorted newest first. This goes beyond basic safety to reveal how results may differ from the input.

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

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

The description is two sentences long with no redundant phrases. The first sentence provides an action-oriented summary; the second adds the most critical behavioral nuance (name resolution) and output details, each earning 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 robust annotations, output schema, and simple parameter set, the description covers the key use case. It could be enhanced by explicitly pointing to sibling tools (e.g., cfpb_search_complaints for broader searches), but it is still complete enough to select and invoke the tool correctly.

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

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

Both parameters are already described in the schema (100% coverage), so the baseline is 3. The description enriches the company parameter by revealing that everyday names are resolved automatically and that the response reports the actual queried name, which informs how to construct input. The limit parameter is sufficiently covered by the schema.

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

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

The description opens with a specific verb and resource: 'Get recent complaints against a specific company'. It provides concrete examples and clarifies the scope versus siblings (company-specific rather than generic search). It also mentions unique features like automatic name resolution, distinguishing it from cfpb_search_complaints or cfpb_get_complaint.

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 clearly implies the tool should be used when the agent needs complaints for a named company, and even gives example everyday names. However, it does not explicitly mention alternatives or state when not to use this tool, leaving a slight gap in exclusivity guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc., covering safety. The description adds behavioral context about the returned fields (narrative, company response, resolution, metadata), which is valuable 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 sentence that front-loads the purpose and includes return details. Every word earns its place; no wasted 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's simplicity (1 param, output schema present), the description sufficiently covers purpose, usage context, and response contents. No gaps remain.

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

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

Schema coverage is 100% with a clear description for complaint_id. The description adds the phrase 'by ID', reinforcing the concept but not adding meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description clearly states the verb 'retrieve' and resource 'complaint by ID', specifies return contents (narrative, etc.), and distinguishes from sibling tools like cfpb_search_complaints which are about searching, not individual retrieval.

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

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

The description implies usage when a specific complaint ID is known, providing clear context. However, it does not explicitly state when not to use it or mention alternative tools for broader searches, which would improve guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is clear. The description adds that it retrieves counts, which is consistent. No additional behavioral details are needed for this simple read operation.

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

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

The description is a single sentence with an example, very concise and front-loaded. Every word 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?

For a low-complexity tool with 3 optional parameters, an output schema, and full annotation coverage, the description is mostly complete. It lacks mention of date dependency (e.g., both dates required together?) but overall is adequate.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description reiterates filtering by company or date range but does not add 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 clearly states the tool returns complaint counts by product category, with examples like 'Credit Card' and 'Mortgage'. It distinguishes from siblings like cfpb_company_complaints by focusing on product breakdowns, though it does not explicitly contrast with 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?

No guidance on when to use this tool versus alternatives like cfpb_company_complaints or cfpb_search_complaints. The description only states filtering options, not selection criteria, leaving the agent to infer context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying the returned data (complaint narratives, company responses, resolution status), which goes beyond annotations.

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

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

The description is a single efficient sentence that front-loads the action and key filters. No superfluous text.

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

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

The description covers the core functionality and output types. With an output schema present, it does not need to elaborate return values further. However, it omits details like pagination or rate limits, which are not critical given the annotations.

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

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

Schema description coverage is 100%, so the schema itself documents all parameters thoroughly. The description does not add additional semantic meaning beyond summarizing the filter options already in the schema.

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

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

The description clearly states the tool searches consumer complaints by multiple criteria (keyword, company, product, date range) and returns specific output (narratives, responses, resolution status). It distinguishes from sibling tools like cfpb_company_complaints and cfpb_get_complaint.

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

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

No guidance on when to use this tool versus siblings such as cfpb_company_complaints or cfpb_product_breakdown. The description does not mention alternatives or exclusionary cases.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that output is a ranked list with company names and counts, which is useful but does not disclose potential pagination, maximum limit, or error conditions. No contradiction with annotations.

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

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

Two sentences with no redundancy. First sentence states action and scope; second sentence specifies output. Every word is necessary 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?

Given that output schema exists and annotations are comprehensive, the description is nearly complete. It covers the core purpose and result format. Minor improvement would be to explicitly mention descending order by count, but 'most complaints' implies ranking, so this 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?

Schema description coverage is 100%, so the schema already describes all parameters. Description reinforces that date range is used (start_date, end_date) but does not add new meaning beyond stating the tool's purpose. 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?

Description uses specific verb 'find', identifies resource 'companies with the most complaints', and specifies time scope 'in a date range'. It clearly differentiates from siblings like cfpb_search_complaints (search individual complaints) and cfpb_product_breakdown (breakdown by product) by focusing on ranking companies by complaint volume.

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 does not explicitly state when to use this tool versus alternatives or provide exclusions. The purpose is implied but lacks guidance such as 'use this to identify top complaint recipients' or 'for individual complaint details, use cfpb_get_complaint'.

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 readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with citation URIs. Differentiates behavior for companies vs drugs.

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 with front-loaded purpose and example queries. Slightly verbose with repeated query patterns, but every sentence adds value. Could be 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?

Given 2 parameters, no output schema, and comparison context, description covers types, data sources, sorting, return format, and citation URIs. Provides sufficient information for an agent to correctly select and 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% coverage with descriptions for both parameters. Description adds significant meaning beyond schema: explains what data is pulled per type (revenue, net income, cash, debt for companies; adverse events, approvals, trials for drugs) and specifies that values should be tickers/CIKs or drug names.

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 tool performs side-by-side comparison of 2–5 entities (companies or drugs) in one parallel call. Uses specific verbs like 'compare', 'rank', 'head to head' and distinguishes from sequential single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides example queries. Could be improved by naming alternative sibling tools (e.g., entity_profile), but still clear.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the account and paid-tier requirement, parallel decomposition/routing, findings-packet contents, explicit gaps[], and the 'never invented' guarantee. These are meaningful behavioral details an agent could not infer from annotations alone, and there is 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?

It is front-loaded with key usage and auth information, but it repeats the 'Best for broad/multi-part.../single lookup use ask_pipeworx' guidance nearly verbatim and trails off with an incomplete 'Output schema tells you...' fragment. The content is useful but not tightly edited.

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 compensates well by specifying the returned findings packet, citations, gaps, and evidence fields. It also covers auth, alternatives, and scope. The dangling final sentence and lack of latency/error detail keep it from being fully complete.

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

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

The schema already covers both parameters at 100%, including detailed enum semantics for depth. The description adds value with concrete example questions, clarifies that broad/multi-part questions are appropriate, and notes that depth 'thorough' requires a paid plan. This exceeds the baseline but does not add much 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 names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in one call, and explicitly distinguishes itself from open-web search. It alsoDifferentiates from ask_pipeworx, making its purpose and scope unmistakable.

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

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

It explicitly states when to use this tool ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx instead'). It also gives an auth-based condition: if not signed in, use ask_pipeworx. This is clear, actionable guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include full input schemas with examples and are ready to call directly, enhancing transparency 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?

The description is two sentences, front-loaded with purpose, and every word 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?

For a simple tool discovery function, the description explains what it returns (top-N tools with schemas) and how to use it. No output schema is needed as the return format is described. Complete given low complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions aliases for query, which is already in schema docs, and provides example queries, adding some value but not significantly beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides concrete examples (SEC filings, FDA drugs, etc.) and distinguishes itself as the primary tool for discovering other tools among the siblings.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context, though it doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive hints, so the bar is lower, but the description adds substantial behavioral context: it explains that empty sections are 'not a bug,' describes the USPTO patents API sunset and soft-fail, clarifies that FDA products only cover biologics, and details the resolution behavior for private companies. It also notes the parallel single-call execution. No contradiction with annotations exists.

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

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

The description is long but front-loads purpose and usage guidelines, then systematically lists data sources and return fields. Every sentence provides essential information for a complex tool with many output facets and edge cases, so the length is justified. It is not overly redundant, but the frequent parenthetical asides and semicolon-separated lists make it slightly dense.

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 fully explain the return structure, and it does: it lists all top-level fields (cik, company_name, resolved_from/resolved_to, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used, sources_failed) and covers edge cases like empty sections, private companies, and soft-failing sources. It is complete for an agent to know what to expect and how to 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%, so the schema already documents both `type` and `value` thoroughly. The description adds extra meaning by explaining that `type` accepts 'company' or 'ticker' interchangeably and that `value` can be any of ticker/CIK/name, including the resolution and private-company fallback behavior. This goes beyond the schema, earning a 4.

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

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

The description opens with concrete user queries ('Tell me about X', 'research Acme'), then states the core action: 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the verb (profile/research), the resource (US public company), and contrasts with chaining single-pack lookups, making it easy for an agent to distinguish from siblings like deep_research or compare_entities.

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

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

The description gives explicit guidance to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is a clear when-to-use directive with a named alternative. It also outlines accepted input shapes and the private-company fallback. However, it does not explicitly state when to use other tools (e.g., deep_research for in-depth analysis), so it lacks a when-not clause.

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. Description adds context about clearing sensitive data but doesn't go beyond what annotations convey.

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

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

Three concise sentences, front-loaded with the action. No wasted words.

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

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

Given the single parameter and no output schema, description fully covers purpose, usage, and relationship to siblings. Complete for a simple deletion 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 no extra meaning beyond the schema's key parameter description.

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

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

Description clearly states 'Delete a previously stored memory by key'. It distinguishes from siblings (remember, recall) by mentioning pairing with 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?

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with remember and recall.

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 nature. The description adds transparency by detailing the process (fetching the page, extracting info) and the output format (single text blob for site-root/llms.txt), providing 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 two concise sentences followed by a list of use cases. It is front-loaded with the core purpose and immediately provides context. No redundant or unnecessary information.

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

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

For a simple tool with only two parameters and no output schema, the description fully explains the purpose, process, output format, and use cases. Annotations cover safety and idempotency, so the description is complete.

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

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

All parameters (url, max_links) are fully described in the input schema with 100% coverage. The description does not add new semantic meaning beyond what the schema provides, meriting the baseline score.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, with specific actions (fetches page, extracts title/description/key links, emits markdown). This distinguishes it from siblings, none of which perform the same task.

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

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

The description lists explicit use cases (getting a client's site indexed, drafting your own llms.txt, auditing competitor AI visibility) but does not provide guidance on when to avoid using this tool or suggest alternative tools. However, 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 provide readOnlyHint and idempotentHint. Description adds return structure but no new behavioral traits beyond confirming read-only nature.

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

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

Two sentences, front-loaded with purpose, then returns and usage. No waste.

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

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

Simple tool with one optional param and clear output described. No gaps for an agent to use correctly.

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

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

Schema coverage is 100% with description for include_inactive. Description does not add further meaning beyond what the schema provides.

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

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

Clearly states 'list the caller's active subscriptions' and specifies returned fields. 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 tells when to use: 'to review what you're monitoring before adding more or to find an id to cancel'.

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

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

Annotations are all false (readOnlyHint: false, etc.), so the description carries the full burden. It discloses key behaviors: filing without an account returns a claim_token, passing the token later reads status and resolution, rate-limited to 5 per identifier per day, free and not counted against tool-call quota, daily digests read by the team. This goes well beyond annotation hints.

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

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

While the description is long, every sentence earns its place. It covers purpose, usage scenarios, exclusions, feedback composition, claim_token behavior, rate limits, and quota impact in a logical flow. There is zero redundancy or fluff; each sentence adds distinct value.

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

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

Given the params, nested objects, enum, and lack of output schema, the description is remarkably complete. It explains the feedback type system, context object usage, claim_token mechanics, rate limiting, and scope. The schema documents parameters thoroughly, and the description fills in operational context, making the tool fully understandable without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage context for parameters, particularly telling the agent to 'Describe the issue in terms of Pipeworx tools/packs' and warning not to paste the end-user's prompt. It also explains the claim_token lifecycle, which complements the schema's description. These additions elevate it 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?

Description starts with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool's purpose and differentiates it from sibling tools like ask_pipeworx and ask_pipeworx_beta by focusing on feedback about Pipeworx's own tools, not general questions. The scope is explicitly limited to tools served by this Pipeworx connection, making it distinct.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes a clear when-not-to-use exclusion: 'if the tool came from a different MCP server ... file it with that server instead.' This directly guides tool selection versus alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds important behaviors: self-aggregating from CF analytics-engine, no PII, caching policy (5min-1h). No contradictions.

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

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

Paragraph format with clear bullet-like list of use cases. Efficiently covers purpose, behavior, and guidance without extra 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?

No output schema, but description fully explains return values (top tools, packs, volume). Also covers data source, privacy, and caching. Complete for its complexity.

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

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

Schema has 100% coverage with enum and description for window. Description adds practical nuance: shorter windows for hot trends, longer for steady-state. Provides value beyond schema.

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

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

Clearly states it returns top tools, top packs, and total call volume over three time windows. Distinct from sibling tools like ask_pipeworx or discover_tools, making its unique purpose clear.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, and checking alignment. Lacks explicit 'when not to use' but provides strong contextual guidance.

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

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

The description thoroughly exposes the tool's behavior beyond annotations: it details the algorithms (monotonicity, partition check), filtering criteria (Jaccard similarity, placeholder fraction), and the fill check logic. The annotations (readOnlyHint, idempotentHint) are consistent with the description, and no contradictions exist.

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 verbose but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Each sentence adds substance, though some detail (e.g., exact Jaccard threshold) could be considered excessive for a tool description.

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

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

Given the complexity, the description fully covers functionality, invocation modes, algorithm details, filtering, response structure (opportunities[]), and crucial caveats like the fill check. It compensates for the lack of an output schema by describing the response shape, making it complete for agent invocation.

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

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

Both parameters have full schema descriptions (100% coverage), and the description adds significant value by explaining their purpose, acceptable values (e.g., 'event slug like "fed-decision-may-2026"'), and how the mode changes behavior. This goes beyond the schema's minimum.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no-arg trending scan, event-specific scan, and cross-event topic scan, setting it apart from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly instructs when to use each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also provides guidance on the fill check and recommends polymarket_fill_risk for custom sizing, effectively directing the agent 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: caching at KV level keyed on all knobs, model specifics (e.g., lognormal barrier, GDELT), diagnostics showing why segments may be empty, and 24h-move warnings. 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 very long and dense, front-loading purpose but then delving into detailed model explanations. While it contains valuable information, it could be more concise and structured with bullet points or sections for readability.

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

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

Given 9 parameters, no output schema, and the tool's complexity, the description is comprehensive. It explains the response structure (by_segment, diagnostics), tradeable-edge knobs, and edge cases (Fed bets, cache duration, filter_skips).

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

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

Input schema covers 100% of parameters with descriptions. The tool description adds significant context beyond the schema: e.g., for slippage_pp it explains Polymarket fees and recommends adjustments; for min_kelly it clarifies it applies to single-leg opportunities; for min_partition_leg_kelly it explains why partition arbs have kelly_fraction_half=0. This adds practical usage guidance.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It details three specific segments (model_driven, structural_arbitrage, concentrated_longshot), differentiating it from sibling tools like polymarket_arbitrage.

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

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

The description explicitly states the tool is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides guidance on tradeable-edge knobs (min_liquidity, max_spread_pp) and explains response structure, though it does not explicitly state when not to use 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 already declare readOnlyHint, openWorldHint, etc. The description substantially adds behavioral traits: it reads snapshots, returns a time-series for edge_pp_net, computes first_seen, trend, decay_pp_per_day, and limits (60-day TTL, daily closes not intraday). No contradiction with annotations; full transparency.

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

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

The description is front-loaded with the core purpose question, then systematically explains response fields and limits. Every sentence adds unique information without redundancy. Despite length, it earns its space through clear structure and useful detail.

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 all return values (tracked[], expired[], snapshot_dates[]) with field meanings and examples (e.g., trend categories, decay computation). Limits and edge cases are covered. The description is complete for a tool with two simple 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%, so baseline is high. The description adds value beyond the schema: it provides default values (14 days, '1wk'), explains the meaning of each parameter (lookback, snapshot family), and adds context for window (e.g., '24hr | 1wk | 1mo'). This enriches understanding.

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

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

The description clearly states the specific verb+resource: 'Edge persistence and decay telemetry' built from snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical analysis and signal decay. The core question 'how long has this edge existed and is it shrinking?' precisely captures the tool's unique purpose.

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 this tool (when edge age and decay matter) but does not explicitly contrast with alternatives like polymarket_edges or polymarket_arbitrage. The phrase 'a fresh wide edge and a 3-week-old wide edge are different trades' provides strong usage context, but explicit 'use this when, use that when' guidance is missing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes beyond by detailing return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and the critical risk that partial basket fills create unhedged directional positions. 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 fairly long but well-structured with section headings (SINGLE-MARKET, BASKET) and bold emphasis on key terms. Every sentence adds value, though minor redundancy exists (e.g., 'default auto' explained twice). Still, it's efficient for 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?

Given two modes, four parameters, no output schema, and high complexity, the description is remarkably complete. It explains what each mode returns (including per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk) and addresses the dominant loss mode (partial fills). An agent can correctly select and invoke this tool.

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

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

Schema coverage is 100%, baseline 3, but the description adds substantial meaning: explains the two distinct interpretation of size_usd (spend/target vs. settlement notional), the auto-detection of side for baskets, and the difference between market and event parameters. This is far more than the schema provides.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb+resource combination that immediately distinguishes it from siblings like polymarket_arbitrage and polymarket_edges. The two modes (single-market and basket) are clearly delineated.

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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear when-to-use context. Also warns about partial basket fills converting an arb into an unhedged directional position, effectively telling when not to proceed.

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

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

Annotations already mark the tool read-only and idempotent, so the bar for additional disclosure is lower. The description adds substantial behavioral context: matching is keyword/word-overlap based, pairings are flagged as unverified, Kalshi fees are not modeled, spreads are gross not net, and temporal_alignment null semantics are explicitly clarified. It also enumerates safety codes and per-leg flags, going far 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 long but well-structured, with bold-labeled sections and important caveats front-loaded near the defining statement. Every section contributes safety or interpretation context, though some repetition (e.g., 'EITHER mode' and the same matcher caveat) could be tightened. It earns its length given the complexity, but it is not genuinely 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?

For a tool with no output schema, the description compensates by enumerating key response fields (top_spreads_pp, compatibility_codes, temporal_alignment, fees_note, skipped counters), explaining their semantics, and telling the agent how to interpret non-empty warnings and null values. An agent has enough context to call the tool and correctly interpret ambiguous 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 coverage is 100%, but the description adds meaning above the schema: it lists all ten topic shortcuts, defines explicit ticker/slug override behavior, and clarifies that both modes run the identical matcher. The schema merely provides parameter names and examples; the description supplies the actual selection semantics and interaction between parameters.

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

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

The description explicitly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, using a clear verb and resource. It distinguishes itself from likely intra-venue alternatives by emphasizing 'cross-venue' and naming both venues precisely.

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 clearly explains the two operating modes—pre-mapped 'topic' shortcuts versus explicit ticker/slug pairing—and warns that pre-mapped topics often return compatibility warnings. It does not explicitly reference sibling tools or state when to prefer this over alternatives, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds scoping to user identifier (anonymous IP, key hash, or account ID) and the listing behavior when key is omitted. No contradiction with annotations.

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

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

Three sentences, each serving a clear purpose: purpose, usage guidance, and scoping/pairing. No wasted words, front-loaded, tightly written.

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 hints at return types (value or list of keys) and explains scoping. For a simple read-only tool, this is nearly complete. Could mention data type of values, but not critical.

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

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

Schema coverage is 100% with a description of the key parameter. Description adds context about omitting key to list all keys, which reinforces schema but adds usage clarity. Baseline 3, improvement for explicit omit behavior and examples.

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

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

Clearly states the tool retrieves a saved value or lists all keys (verb+resource). Explicitly distinguishes from siblings (remember, forget) by 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?

Provides concrete examples (user's target ticker, address, research notes) and explains when to use: to look up context stored earlier, avoiding re-derivation. Also references alternative tools (remember, forget).

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=true, idempotentHint=true, destructiveHint=false) are consistent with the description's 'Pull' and 'flag returned events read' language, which is non-destructive. The description adds value by disclosing that events carry specific fields (source, citation_uri, raw payload) and that the feed is available via a separate GET endpoint. 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. It front-loads the main action and then adds necessary details without redundancy. Every sentence contributes meaningful 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?

All five optional parameters are covered, return value fields are described (source, citation_uri, raw event payload), and usage patterns (polls, direct GET) are mentioned. Despite no output schema, the description is sufficient for an agent to use the tool correctly.

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

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

Input schema has 100% description coverage for all 5 parameters. The description enhances meaning by providing examples ('sec_8k') and explaining the behavioral effect of mark_read ('so the next call only shows newer ones'). This goes beyond the schema's basic descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed', which is a specific verb+resource combination. It clearly distinguishes this tool from siblings like 'list_subscriptions' (which lists subscriptions, not events) and 'subscribe' (which creates subscriptions). The purpose is unambiguous.

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

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

The description explains filtering by type and/or since timestamp, and how mark_read affects subsequent calls. It also mentions that polling works fine and that the same feed is available via a direct GET URL for scripts/dashboards, providing an alternative. No explicit when-not-to-use guidance, but otherwise clear usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: fans out to multiple sources, fallback from GDELT to GNews, and soft-fail for USPTO due to API sunset. 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 information-dense but not overly long. It's front-loaded with examples and structured logically. A slight reduction could improve conciseness, but it remains clear and effective.

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

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

Despite no output schema, the description fully explains the return format: structured changes grouped by source, total_changes count, and citation URIs. It also covers edge cases like fallback and sunset, 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?

All parameters are described in the schema with 100% coverage. The description adds extra semantics: 'since' accepts relative shorthand like '7d', '30d', '3m', '1y', and 'value' can be a ticker or CIK. This enhances understanding beyond the schema.

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

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

The description clearly states it's a change feed for a company within a time window, lists specific sources (SEC EDGAR, GDELT→GNews, USPTO), and distinguishes from the sibling tool entity_profile, which provides a static profile. Examples of queries align with the tool's purpose.

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 (for recent changes) and when not ('Use entity_profile instead when you want the static profile'). It also provides example queries and a note about rate limits and fallback behavior.

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

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

Describes storage as key-value pair scoped by identifier, persistence details (authenticated vs anonymous, 24-hour retention). 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?

Four sentences, front-loaded with purpose, no wasted words. Every sentence contributes clear 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?

Fully covers the tool's behavior, scope, and lifecycle for a simple write operation. No missing critical information.

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

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

Schema already covers both parameters with descriptions. Description adds examples of key patterns and value types, enhancing meaning.

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

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

Clearly states 'Save data' with specific verb and resource. Distinguishes from siblings by referencing recall and forget.

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

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

Explicitly describes when to use (discover something worth carrying forward) and provides examples like resolved ticker, target address. Mentions pairing with recall and forget.

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 a safe, read-only, idempotent operation, and the description adds valuable behavioral detail beyond that: graceful degradation when LEI/FIGI enrichment is unavailable, explicit `unresolved` reporting, returning `figi_candidates` on ambiguous matches, source-labelling of identifiers, and internal cascading lookups. No contradiction with annotations.

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

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

The opening is well front-loaded, but the supported-types section is an extremely long run-on with dense nested parentheticals. Useful details such as ambiguity handling, graceful degradation, and unresolved reporting are buried in prose and would be far more navigable as a short structured list or bullets.

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

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

There is no output schema, so the description carries the burden of explaining return behavior. It covers resolved identifiers, ambiguity via `figi_candidates`, explicit `unresolved` fields, source attribution, acceptance of ticker/CIK/ISIN/name, and fallback behavior when upstream sources are unavailable. Nothing essential for calling this tool 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?

Although the schema already documents both parameters, the description substantially enriches their meaning: it lists accepted input forms for `value` (ticker, CIK, ISIN, name), gives concrete examples, and adds an important caveat to pass only the entity name and never the full noun phrase. 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 clearly names a specific verb (resolve) and resource (user-spoken names to canonical/official identifiers), and demonstrates the purpose with concrete natural-language examples. It does not explicitly name or distinguish sibling tools, though 'Use FIRST whenever you have a name but need an ID' establishes its role relative to other tools.

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

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

The description provides an explicit usage trigger: 'Use FIRST whenever you have a name but need an ID.' It also clarifies acceptable inputs per type and warns against full noun phrases. However, it does not state when NOT to use this tool or name alternative tools for cases the resolver does not cover.

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, etc. The description adds that it probes each entity with ai_visibility_check and returns score, confidence, signal density. It does not contradict annotations but does not add significant behavioral detail beyond what is implied.

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

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

Three sentences, front-loaded with the core purpose, followed by mechanism and use case. No wasted words.

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

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

The description explains the overall function, how it works, and the output structure. Given the presence of a full input schema and no output schema, it is complete enough for the agent to use effectively.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by clarifying that the first entity is treated as the 'subject' and the rest as competitors, 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 tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check to probe each entity, and returning a ranked list. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (likely other comparisons).

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 it is 'useful for competitive AI-marketing audits' and gives an example. It implies that for a single entity one would use ai_visibility_check, but does not explicitly state when not to use or list 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 indicate safe, read-only, idempotent behavior. Description adds valuable context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed list for timeouts. No contradictions.

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

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

Description is verbose but efficient, front-loading the main purpose. Every sentence adds value, but could be slightly more concise. Still well-structured.

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

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

Despite no output schema, the description explains the return format (summary block, advisories, links, alternative versions), covers partial failures, ecosystem limitations, and performance notes. Complete for the tool's complexity.

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

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

Schema provides 100% coverage for both parameters (package and version). Description adds minimal extra (scoped packages accepted, version defaults to latest) but mostly repeats schema info. Baseline 3 is appropriate.

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

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

The description clearly states the tool as a composite check for evaluating npm packages, specifying it fans out across deps.dev and bundlephobia. It distinguishes from siblings by focusing on npm ecosystem and specific metrics.

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

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

Explicitly tells when to use: when agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also notes ecosystem scope (npm only) and directs alternative ecosystems to other tools.

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

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

Annotations already declare safety; description adds truncation (200K chars, flagged), embedding model, window size, similarity metric, offset info. 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?

Front-loaded with purpose, then usage, then technical details. 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?

Despite no output schema, description explains return format (passages with offsets and scores) and handles edge case (truncation). Complete for a search 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 100%; description adds practical context like max chars for text, example queries, limit range and default, 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?

Clearly states the tool performs semantic search inside a fetched record, distinguishing it from siblings like ask_pipeworx_grounded. Uses specific verbs and resources.

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

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

Explicitly advises when to use ('when the record is too big to cram into the prompt') and pairs with another tool. Lacks explicit when-not scenarios, but context suffices.

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

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

Beyond annotations (idempotent, non-destructive, non-read-only), the description details required account type, delivery channels with constraints (email verification, SMS cap, webhook signing and auto-disable), and the fact that the feed is always on. 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?

Every sentence adds essential information. The description is front-loaded with the core purpose and flows logically into prerequisites, types, and delivery. No redundancy.

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

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

Given the tool's complexity (multiple types, delivery options), the description covers all necessary aspects: purpose, prerequisites, type-specific parameters, delivery options and their constraints, and the return value. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the purpose of each subscription type and providing concrete parameter examples, enhancing the bare 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description specifies prerequisites (Pipeworx OAuth account) and supported types with examples, guiding when to use each type. It implicitly differentiates from other tools but lacks explicit 'when not to use' or direct comparison to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details about the return format (category-bucketed example questions with exact tool+argument shape), which goes beyond the annotations.

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

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

The description is concisely structured, front-loading the purpose and common phrasings, followed by a list of category topics and usage instructions. Every sentence adds substantial value without redundancy.

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

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

Given the lack of an output schema, the description comprehensively explains the return content (category-bucketed questions with tool+argument shape). It fully covers purpose, usage, and parameter semantics, making the tool self-explanatory in context.

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

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

Schema coverage is 100% with a clear description of the topic parameter. The description significantly enhances this by explaining the effect of omitting vs. providing the parameter, listing acceptable focus areas, and noting that the full spread is returned without arguments.

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

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

The description clearly states it is the onboarding entry point for a newly connected agent, returning category-bucketed example questions. It distinguishes itself from sibling tools like ask_pipeworx by focusing on providing ideas for what to ask, rather than executing a 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 tells the agent to use this tool first when unsure of Pipeworx's capabilities and to learn how to call meta-tools. Provides guidance on calling with no arguments vs. passing a topic to focus, giving clear when-to-use context.

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

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

The description adds behavioral context beyond annotations: it explains that the row is deactivated (not deleted) and that ownership is enforced. This supplements the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) without contradiction.

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

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

Two sentences, zero wasted words. The description is front-loaded with the main action and then provides key behavioral traits concisely.

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 (1 parameter, no output schema, annotations present), the description is complete. It covers what the tool does, constraints (ownership), and outcome (deactivation, history availability). No missing information.

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

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

The input schema already describes the 'id' parameter with 100% coverage. The description does not add new semantic details about the parameter itself, but it provides context about ownership and deactivation that indirectly relates to how the parameter is used. 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 specific verb 'cancel' and resource 'subscription by id', clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. It also explains the outcome (deactivation) and ownership enforcement, which adds clarity.

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

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

The description states ownership enforcement ('you can only cancel your own subscriptions'), which guides usage. It also mentions that historical events remain available via 'recent_alerts', providing a clear alternative for accessing history. However, it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: the exact verdict values, the meaning of the two failure modes (could_not_verify, unsupported), the presence of verification_error with stage/detail, the warning that could_not_verify must not be treated as evidence, and the pipeline mechanics (percent-delta math, grounded sources, verbatim evidence with citations).

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: example phrasings first, then usage, then pipeline details, return values, and caller warnings. Every sentence contributes value. It could be slightly tightened (e.g., trimming example lists), but the length is justified by the tool's complexity, and the front-loading is effective.

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

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

Given no output schema, the description fully accounts for return values (verdict set, grounded/structured actual value, citation, reasoning), error handling (could_not_verify with verification_error), the unsupported case, and its role as a single-call consolidation of 4–6 steps. It leaves no critical ambiguity for an agent deciding or invoking the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic guidance for both parameters: example claim formats for the claim field and the tolerance_pct's role as an override (with the 1–2 recommendation for hallucination detection and default behavior). This extra context merits a 4.

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

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

The description clearly states a specific verb+resource: natural-language claim verification against authoritative sources. It provides multiple example user phrasings, distinguishes its scope (company-financial vs other fact checks), and explicitly frames itself as a replacement for 4–6 sequential calls, differentiating it 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?

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes internal routing (SEC EDGAR fast path for financial claims vs grounded pipeline for anything else), giving clear context. However, it does not explicitly name alternative tools or say when not to use it, so it falls just 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.