Fmcsa

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds cost implications (free default vs BYO key), data flow (pass-through to Anthropic), and response structure (per-model details). 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?

Four sentences, front-loaded with purpose. Every sentence adds value. No redundancy or fluff. Efficiently conveys key 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 1 required param, no output schema, the description fully covers return format (per-model {score, confidence, signals, raw_response}), cost model, and use cases. Sufficient for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value beyond schema: explains default model, when apiKey is needed, context purpose. Provides usage hints not in 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 probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the verb 'probe' and 'score', the resource 'LLMs', and output structure. Distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring per model.

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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. However, does not mention when not to use or directly compare with sibling tools. Suggests context parameter for disambiguation.

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

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

The annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context by explaining that the tool performs routing, fills arguments on behalf of the user, and returns structured answers with stable pipeworx:// citation URIs—information not available from annotations alone.

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 directive ('PREFER OVER WEB SEARCH') and is densely informative: domains, trigger phrases, examples, and a default-start instruction. It is somewhat long and has a confusing garbled tail fragment, which prevents a perfect score, but the core structure 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?

With no output schema present, the description usefully states what the caller gets back: a structured answer with stable pipeworx:// citation URIs. It also explains the routing behavior well enough for an agent to select and invoke the tool confidently. It could go slightly deeper on exact result formatting or failure cases, but it is not materially incomplete.

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 all parameters and their aliases with 100% coverage, so the description does not need to redefine them. It adds meaning by specifying the expected phrasing of the natural-language question and offering six concrete examples that clarify what belongs in the required 'question' parameter.

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

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

The description states a specific role: it routes natural-language questions to one of 5,695 tools across 1,491 verified sources and returns a structured answer with citation URIs. This clearly differentiates it from a generic web search and establishes it as an authoritative-data oracle, even though sibling beta/grounded variants are not explicitly named.

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

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

It explicitly says to PREFER this over web search, gives trigger phrases ('what is', 'look up', 'find', 'get the latest', 'current'), lists example queries, and closes with 'START HERE for most questions'. This is strong when-to-use guidance, and the trailing fragment points to step-up research via deep_research as the 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?

Discloses that routing behavior may change live when a candidate is under test, that no candidate is currently active, and that it currently matches ask_pipeworx exactly. This adds meaningful volatile-behavior context beyond the shape-on-sensitive read/idempotent 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 focused sentences: identity, current experimental state, and usage instruction. Every sentence adds unique information and the most important distinction is 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?

The description covers what the tool is, how it relates to ask_pipeworx, when to use it, and its experimental nature. It relies on ask_pipeworx for full parameter and response details, but that reference is explicit and acceptable given the identical behavior.

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

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

The schema already documents all parameters with 100% coverage, including the aliases q, text, and input. The description only says it uses the same arguments as ask_pipeworx, which adds no parameter meaning beyond the schema.

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

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

Description identifies it as the beta version of ask_pipeworx with identical routing scope and experimental candidate routing improvements. It clearly distinguishes it from the stable ask_pipeworx sibling by noting the live test behavior and newest routing intent.

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

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

Explicitly instructs the agent to use it like ask_pipeworx when the newest routing behavior is desired. It also clarifies that it is a full working router rather than a fallback stub, removing ambiguity about whether to avoid 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?

The description goes well beyond the readOnly/idempotent annotations by disclosing refusal behavior, the 'ONLY what the tool result contains' constraint, evidence verbatim quoting, and the precise refusal_reason enumeration. It also surfaces the extra LLM call cost. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and differentiator, then efficiently covers routing, return shape, refusal reasons, use cases, and tradeoff. Every sentence earns its place, and the return/refusal detail is justified because there is no output schema to carry that 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 single-parameter tool with no output schema, the description is unusually complete: it explains what happens internally, what the success/failure responses look like, when to prefer the sibling, and the cost implication. An agent has enough to call it correctly and interpret results.

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

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

Schema description coverage is 100%: the sole meaningful parameter `question` is documented as natural language, and all five aliases are explicitly listed. The description adds no additional parameter-level semantics, but none are needed given the complete 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 mode ('hallucination-resistant answer mode'), a clear verb ('EXTRACTS the answer'), and differentiates itself from the sibling ask_pipeworx by emphasizing groundedness. It is immediately obvious what this tool does and how it differs from the non-grounded alternative.

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 this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples. It also states when not to use it: 'prefer ask_pipeworx for casual lookups', and explains the cost tradeoff.

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 and idempotent hints, but the description adds extensive behavioral context: resolution logic, fan-out patterns, response shapes, safety mechanisms (low-confidence short-circuits, closed market handling, liquidity warnings, cancellation rule parsing). This goes far beyond the annotations and provides complete 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 well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with purpose. While verbose, every section appears necessary given the tool's complexity. Could be slightly more concise, but readability is good.

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

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

Given the tool's complexity (3 params, no output schema, multiple data sources), the description covers all essential aspects: inputs, outputs, error states, safety, edge cases, and resolution details. Nothing critical is omitted.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains market parameter accepts slug/URL/text, depth options with default, include_raw with rationale and size implications. Examples further clarify usage. This adds significant value beyond the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and output (evidence packet + comparison). The usage examples ('should I bet on X', etc.) make the purpose unmistakable and distinguish it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides explicit use cases ('Use for...') and details about when to inspect certain fields (e.g., RESOLVER CONTRACT). However, it does not explicitly state when NOT to use the tool or mention alternatives, so it lacks full exclusion 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?

Description provides rich behavioral details beyond annotations: data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, result sorting by primary metric, and inclusion of citation URIs. Annotations indicate read-only and idempotent, which aligns with the description.

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 a single paragraph but front-loads key use-case phrases and core function. All sentences add value. Could be slightly more structured with bullet points for data sources or results, but remains clear and efficient.

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

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

Description explains return format (paired data + citation URIs), result ordering, and data sources. No output schema, so description carries full burden; it addresses edge cases and provides sufficient context for a tool with 2 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%. Description adds meaning by explaining enum values ('company' pulls financial data, 'drug' pulls adverse events) and array items (tickers/CIKs for company, names for drug) with concrete 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?

Description specifies verb 'compare', resource 'entities' (companies or drugs), and context from user phrases like 'Compare X and Y' or 'X vs Y'. Clearly distinguishes from siblings by noting it replaces 8–15 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?

Description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and explains when to use 'company' vs 'drug' type. Could be improved by mentioning when not to use (e.g., for single entity lookups, use entity_profile).

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

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

Annotations only signal read-only/idempotent safety; the description adds substantial behavior: account requirement, parallel facet decomposition, findings packet contents, explicit gaps[], contradictions[] for standard/thorough, citation_uri fetchability, semantic excerpting, and latency expectations. It does not contradict the annotations.

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

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

The description is long but every sentence contributes either selection guidance, call-time behavior, or output semantics. It is front-loaded with the auth gate and core purpose before layering details, though it is dense enough to be slightly harder to skim.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop, and citation_uri. Account prerequisites, fallback tool, depth semantics, and latency are also present, so the agent has what it needs to 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?

The schema already covers both parameters at 10% coverage, so the baseline is 3. The description delivers extra meaning beyond the schema by noting that depth:'thorough' requires a paid plan, clarifying how depth affects hops and gap recovery, and reinforcing that broad natural-language questions are expected.

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 identifies an explicit verb and resource: grounded multi-source research across 1491 structured data sources via parallel tool routing. It also clearly distinguishes itself from open-web search and from ask_pipeworx by framing deep_research for broad/multi-part questions rather than single lookups.

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

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

It gives direct selection rules: use ask_pipeworx if not signed in, use ask_pipeworx for single lookups, and use deep_research for broad/multi-part questions over structured data. It even names a sibling alternative explicitly rather than leaving choice to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. Description adds valuable behavioral detail: returns top-N tools with full schemas and examples, no second lookup needed. This contextualizes the read-only, repeatable nature 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 approximately 4 sentences, front-loaded with purpose, then usage guidance, then return details, then explicit call to action. Every sentence provides distinct 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 tool's complexity (6 parameters, 1 required, no output schema), the description covers the return format (names, descriptions, schemas, examples), usage context (call first), and alias flexibility. No major gaps for a discovery tool.

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

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

Schema description coverage is 100% with all 6 parameters described. The description mentions query accepts aliases (task, q, description, search) and provides examples in the schema, but adds little extra meaning beyond what the schema already conveys. 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?

Description starts with 'Find tools by describing the data or task,' clearly stating the verb (Find) and resource (tools). It distinguishes from sibling tools by explicitly positioning this as a discovery tool used before selecting a specific tool, and lists many data domains to clarify scope.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance. Missing explicit when-not-to-use, but the first-call directive implies it is for exploration, not for direct queries.

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

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

Beyond annotations (readOnly, idempotent, etc.), description details the sources fanned out (SEC, XBRL, USPTO, news, GLEIF), mentions patents soft-fail after May 2025, and describes return structure. No contradiction with annotations.

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

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

Description is dense and informative without fluff, but could be slightly more structured (e.g., bullet points). Still, every sentence adds value and it front-loads with examples.

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 lack of output schema, description fully explains return fields (cik, filings with URIs, fundamentals, patents, news, LEI) and notes limitations. Complete for a tool with simple inputs.

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

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

Schema coverage is 100%, but description adds crucial context: value accepts ticker or zero-padded CIK and explicitly states names not supported, which is not fully captured in 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 explicitly states it provides a full cross-source profile of a US public company in one call, with clear examples like 'Tell me about X' and 'research Acme'. It distinguishes itself from chaining single-pack lookups, which are 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?

States to ALWAYS PREFER this tool over chaining lookups for holistic views. Explicitly says names are not supported and directs to use resolve_entity first. Provides clear when-to and when-not-to use guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds value by noting 'Keyless' (no authentication required) and enumerating the specific data fields returned, giving the agent a clear picture of what to expect.

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 core purpose. Each sentence earns its place: purpose, return values, calling conventions and alternatives. No redundant wording.

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 moderate complexity and absence of an output schema, the description covers the main return fields and calling options. It does not mention edge cases like not-found behavior or error handling, which would have made it fully complete, but it is still highly informative.

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 meaning by explaining the relationship between the direct parameters (dot_number, mc_number, name) and the generic by/value pair, clarifying that they are alternative calling shapes. This goes beyond the schema's individual property 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 looks up a US motor carrier by USDOT number, MC/docket number, or company name, and lists concrete return fields. It distinguishes itself from sibling tools by explicitly naming the alternatives for related functions.

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

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

Provides explicit guidance on when to use this tool (carrier census lookup) versus alternatives ('For carrier authority... use fmcsa_operating_authority; for safety scores use fmcsa_safety_snapshot'). It also clarifies the different calling conventions (direct params vs by/value pair).

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds that the tool is 'Keyless' (no API key required) and specifies the response fields. It doesn't disclose rate limits or data freshness, but adds meaningful 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 sentences long, front-loaded with the purpose, and every sentence adds value. No extraneous 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 parameter, no output schema, no nested objects), the description covers the output fields, use case, and differentiation. It is complete for an AI agent to understand when and how to use it.

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

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

Schema coverage is 100%, baseline 3. The description repeats 'by USDOT number' which matches the schema's parameter description, and adds 'Keyless' (not parameter-related). It adds minimal extra meaning beyond what the schema already 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 explicitly states the verb 'Get', the resource 'carrier's FMCSA operating authority', and lists the specific outputs (MC docket number, authority statuses). It also distinguishes itself from sibling tools by mentioning complementarity with fmcsa_carrier_lookup and fmcsa_safety_snapshot.

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 states when to use this tool ('Answers is this carrier authorized to operate/broker freight') and explicitly contrasts it with census (fmcsa_carrier_lookup) and safety (fmcsa_safety_snapshot) tools, providing direct usage 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 mark the tool as read-only and non-destructive. The description adds context beyond annotations by specifying the data source (FMCSA SAFER Company Snapshot), noting that it is 'Keyless' by default, and explaining that an optional FMCSA QCMobile webKey via _apiKey unlocks additional SMS BASIC categories with violation counts and percentiles. This is useful behavioral disclosure about authentication and data scope.

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 two-sentence paragraph that packs a high density of useful information without fluff. The first sentence enumerates exactly what data will be returned, and the second explains the optional key and its benefits. Every clause adds value, making it appropriately sized for the tool's complexity.

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

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

The description is remarkably complete: it lists all major output fields (safety rating, dates, status, inspection counts, OOS rates, crash counts, BASIC categories), explains the default keyless behavior and optional enhanced mode, and identifies the data source. With a single required parameter and no output schema, this description gives an agent sufficient context 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?

The schema covers dot_number with a description, and the tool description reinforces its meaning (USDOT number). The description adds meaning by introducing an optional _apiKey parameter not present in the schema, explaining its purpose and the additional data it yields. This goes beyond the schema's coverage, though the undocumented parameter is a minor concern.

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 gets the FMCSA safety profile for a US motor carrier by USDOT number, with a detailed list of included data (safety rating, inspection counts, OOS rates, crash counts). The verb 'Get' and the resource 'safety profile' are specific, and the listing of distinct data fields distinguishes it from sibling tools like fmcsa_carrier_lookup or fmcsa_search_carriers.

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

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

The description provides clear context by enumerating the exact safety-related data returned, implying this is the tool for carrier safety snapshots. However, it does not explicitly state when not to use it (e.g., for operating authority or search) or name alternatives, so it falls short of a 5 but is above a 3.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds 'Keyless' (no API key required) and 'ranked by fleet size', offering useful behavioral context beyond annotations. No contradictions.

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

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

Two sentences plus a clear alternative usage sentence. No redundant or irrelevant information. Efficient and front-loaded.

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

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

Despite no output schema, description clearly enumerates return fields (USDOT number, legal/DBA name, city/state, power units, drivers, status). Specifies optional state filter and ranking by fleet size. Fully addresses the tool's complexity and context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that name is case-insensitive, which is not in the schema's parameter description. Other parameters are adequately described in schema. Minor added value, so score remains 3.

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

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

Clearly states the tool searches US motor carriers by company name (partial, case-insensitive), returns specific fields, and ranks by fleet size. Distinguishes from sibling fmcsa_carrier_lookup.

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 directs to use fmcsa_carrier_lookup for full details on a returned USDOT number, providing clear alternative. Does not fully enumerate when not to use this tool, but coverage is strong.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds context about clearing sensitive data and stale context, aligning with the annotations without contradiction.

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

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

The description is very concise (two sentences), front-loads the primary action, and avoids any 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 simplicity (one parameter, no output schema, clear annotations), the description covers purpose, when to use, and relationships, making it 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?

Schema coverage is 100% and the description simply restates 'by key'. No additional detail about key format or constraints is provided, so baseline score applies.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and distinguishes it from siblings 'remember' and 'recall' by explicitly mentioning them as companions.

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

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

The description provides explicit scenarios for use ('when context is stale, the task is done, or you want to clear sensitive data') and pairs with related tools, but does not 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description explains the steps: fetches page, extracts title/description/key links, and emits standard markdown format, and notes the output is a text blob. This adds significant value and is consistent with annotations.

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

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

The description is concise (3 sentences), front-loads the purpose, then explains the process, and ends with use cases. Every sentence adds value with 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 simplicity and no output schema, the description sufficiently explains what the tool does, how it works, and why it would be used. It is complete enough for an agent to decide when to invoke it.

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

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

Schema coverage is 100% with good parameter descriptions. The description does not add new semantics beyond what is in the schema; it restates that it fetches the URL and limits links. 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 generates an llms.txt file for any URL, specifying the output format and the purpose. It uses a specific verb and resource, and no sibling tool has the same function, making it easy to distinguish.

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

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

The description provides explicit use cases (client site indexing, personal project drafting, competitor auditing), but does not mention when not to use the tool or suggest alternatives among siblings. The context is clear but lacks exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by specifying returned fields and the optional include_inactive parameter, 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, front-loaded with purpose and output fields, followed by usage guidance. 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?

For a simple list operation with one optional parameter and no output schema, the description lists return fields and usage context, fully covering the tool's functionality.

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

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

Schema coverage is 100% with parameter description already in schema. Description does not add extra meaning beyond what the schema provides, meeting 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields, distinguishing from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel', providing clear context for usage.

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

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

Beyond the annotations (which only indicate non-read-only, non-idempotent), the description discloses key behaviors: filing without an account returns a claim_token, that token can be used later to read resolution status, rate limited to 5 per identifier per day, free, and that signal affects roadmap. This adds context about what happens after filing and how to retrieve results.

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

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

The description is long but every sentence earns its place: purpose, use-cases, exclusion, disambiguation, content guidance, claim_token workflow, and rate limit. It is front-loaded with the primary purpose and structured logically. No fluff or repetition.

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 explains what to expect: once filed, a claim_token is returned; passing it later tells the user if it was fixed and what changed. It also covers the tool's scope (Pipeworx connection only), rate limit, and roadmap impact. For a feedback tool with 0 required params, the description leaves no major gap in understanding.

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

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

The schema already documents all 4 parameters with 100% coverage, so baseline is 3. The description adds value by explaining the claim_token workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), the message guidance ('Don't paste the end-user's prompt'), and the rate-limit context. This lifts it to 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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the tool's purpose (submit feedback) and resource (Pipeworx team). It distinguishes from siblings like ask_pipeworx by framing this as reporting issues rather than asking questions.

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 specifies when to use: '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).' Also provides a clear exclusion: if the tool came from a different MCP server, file with that server instead. Names alternatives behaviorally without naming a specific sibling.

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 readOnly, idempotent, nondestructive. The description adds valuable context: derived from CF analytics-engine, no PII, cached 5min-1h depending on window. No contradictions.

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

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

Five sentences, front-loaded with core purpose, followed by use cases and technical details. Every sentence adds value; no filler or redundancy.

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

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

The description mentions return values (top tools, packs, call volume) but does not specify exact structure, format, or whether counts/ranks are included. Without an output schema, a bit more detail on return format would improve completeness.

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

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

Schema covers the single parameter 'window' with enum and description. The description enriches it by explaining behavioral implications: shorter windows surface hot items, longer windows show steady-state demand. Adds meaning beyond schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a configurable window, derived from AI agent usage. This specific verb-resource combination distinguishes it from siblings like 'discover_tools' which likely offer broader or different discovery.

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

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

The description lists three concrete use cases (discovering hot data, confirming canonical tool, aligning with trends) but does not explicitly mention when not to use the tool or contrast it with alternatives among the siblings. Clear context, but lacks exclusion guidance.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false. The description adds extensive behavioral context: what happens with no args (scans top ~200 markets), event mode (walks child markets, checks date/threshold ordering, partition check), topic mode (searches related events, Jaccard similarity filter, placeholders filter), and fill check (against live book depth with realizable edge). No contradictions.

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

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

The description is well-structured and front-loaded with the main purpose. However, it is somewhat verbose with many technical details, which could be trimmed slightly without losing clarity.

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

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

Given the complexity of the tool (multiple modes, fill check, similarity filter) and the absence of an output schema, the description is remarkably complete. It explains the return format (opportunities array with fields) and even suggests using 'polymarket_fill_risk' for custom sizing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema by explaining recommended use cases, example slugs, and the underlying checks performed for each parameter.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no-args for trending scan, event mode for a specific market, and topic mode for cross-event scanning. This makes it distinct 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 recommends 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)'. However, it does not explicitly state when to avoid using this tool in favor of alternatives, such as when fill risk is too high.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by explaining how edge calculations work (net of slippage), the three model segments, caching at 1h, and diagnostic outputs. 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?

Though lengthy, every sentence provides essential behavioral or structural information. The description is well-organized: purpose, model breakdown, knobs, response format. No 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?

Given the complexity (9 parameters, no output schema), the description fully compensates by detailing the output structure (by_segment, diagnostics) and explaining caching and edge calculation. An agent can fully understand usage without external references.

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

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

Schema coverage is 100% and each parameter is already described. The description adds value by grouping knobs (e.g., tradeable-edge filters) and explaining their interactions, but the baseline is high due to schema completeness. Slight improvement over baseline.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically targeting 'what should I bet on today' scenarios. This distinct purpose differentiates it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides clear context on when to use the tool (discovery without paging hundreds of markets) and details adjustable knobs. However, it lacks explicit instruction on when not to use it or direct comparisons to alternative tools, leaving some ambiguity for the agent.

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

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

The description richly discloses behavioral traits beyond annotations: it describes reading from daily snapshots, tracking time-series, first_seen, trend, decay_pp_per_day, expired opportunities, and median lifespan. It also notes limits like 60-day TTL and that decay is from daily closes. This adds significant value over 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 a clear opening statement, parameter list, detailed response format, and limits. It is front-loaded with the core purpose. While every sentence earns its place, minor trimming could improve conciseness without losing information.

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

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

Since there is no output schema, the description thoroughly explains return fields: tracked[], expired[], snapshot_dates[]. It covers all necessary behavioral and return value details, making the tool fully understandable without additional documentation.

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

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

Schema coverage is 100%, baseline 3. The description clarifies defaults and constraints for 'days' (default 14, max 30) and 'window' (snapshot family, default '1wk'), adding context not in the schema descriptions (e.g., 'max 30' vs 'clamp 2-30'). It also explains the role of 'window' in selecting snapshot families.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and explicitly answers 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like 'polymarket_edges' by focusing on persistence and decay rather than raw edges.

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

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

The description implies usage for edge persistence analysis but does not explicitly state when to use this tool versus alternatives or provide conditions for not using it. No exclusionary or comparative guidance is given.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds detailed behavioral context: what the tool returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), how basket mode computes theoretical vs realizable sum, capture ratio, and forced directional risk. 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?

Description is long but well-structured with sections for overall purpose, requirement, single-market details, basket details, and usage guidance. Each sentence adds value; no filler. Could be slightly more condensed but complexity justifies length.

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

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

Given complexity (4 parameters, no output schema, two modes), description is thorough. Covers return fields for both modes (top_of_book, vwap_fill_price, slippage, shares_filled, verdict etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). No output schema, so description fully covers return values and behavioral consequences.

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 beyond schema: explains the auto-default for side in basket mode (auto from partition sum), clarifies size_usd interpretation differences for buys vs sells in single-market and as settlement notional in basket, mentions clamp range (10–1,000,000) not in 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 checks realizable vs theoretical edge against live CLOB order book depth. It distinguishes two explicit modes (single-market and basket) and names specific sibling tools (polymarket_arbitrage, polymarket_edges) as related but distinct actions.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Provides compelling rationale: theoretical overround on thin books is not capturable and partial fills convert arb to directional position, which is the dominant loss mode.

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

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

Description adds extensive behavioral context beyond annotations: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype) with detailed explanations. No contradiction with annotations (all 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?

Description is long but well-structured and front-loaded. Every sentence adds value, but could be slightly more concise. Good use of headings and bullet-style lists for safety fields.

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 modes, safety fields, temporal alignment), the description covers all necessary aspects. No output schema, but response structure is explained clearly with example fields like top_spreads_pp and compatibility_warning cases.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context for topic enum values and explains override behavior of explicit tickers, but does not significantly enhance meaning beyond schemā; adequate.

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 calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. Specific verb+resource+scope.

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?

Explains when to use (comparing prices across venues) and when not (when compatibility_warning fires). Describes two modes (topic shortcuts vs explicit tickers) and warns that pre-mapped topics often return warnings. Lacks explicit mention of alternatives but context makes it 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 annotations (readOnlyHint, etc.), description adds scope (per identifier) and pairing context. No contradictions.

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

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

Three sentences, front-loaded with main action, efficient and clear. Minor redundancy in parameter info.

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 full schema coverage, description provides usage context and pairing. No output schema needed.

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

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

Schema coverage is 100%; description repeats schema info (omit to list keys) but adds use-case context. Baseline 3 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 it retrieves values saved via remember or lists keys, differentiating from siblings remember and forget.

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

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

Explicitly states when to use (look up stored context) and how to pair with remember/forget. Provides clear context for selection.

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

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

Description claims mark_read:true flags events as read, implying a side effect, but annotations declare readOnlyHint:true and idempotentHint:true, creating a contradiction. Score set to 1 per rules.

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

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

Description is concise (four sentences), front-loaded with purpose, and each sentence adds value without redundancy.

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

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

Covers main functionality, return format, filters, mark_read behavior, and alternative access. Missing explicit mention of unread_only and limit, but those are in schema. No output schema but description adequately describes return structure.

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

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

Schema coverage is 100%, so baseline is 3. Description adds example type and ISO timestamp format but does not significantly extend beyond schema descriptions for parameters like limit and unread_only.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies return fields (source, citation_uri, raw event payload), and distinguishes it from sibling tools like list_subscriptions.

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

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

Provides context on filtering by type and since, and mentions an alternative access method (GET endpoint). However, lacks explicit when-not or comparison to siblings like subscribe.

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

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

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds valuable behavioral details: that it performs one parallel call, fans out to SEC EDGAR, GDELT/GNews (with fallback), and USPTO (soft-fails). It also explains date parameter formats. No contradiction with annotations.

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

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

The description is front-loaded with example queries and is dense with information. While every sentence adds value, it could be slightly more concise. Still, it is well-structured and efficient.

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

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

Given there is no output schema, the description explains the return structure (changes[] grouped by source, total_changes count, citation URIs) and covers all sources and fallback. It is fully complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning: 'type' only supports 'company', 'since' accepts ISO or relative shorthand with examples and a recommendation for typical monitoring, and 'value' accepts ticker or CIK. This is additive beyond the schema.

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

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

The description opens with example queries like 'What's new with X' and explicitly states it provides a change feed for a company in a time window. It also distinguishes from sibling tool entity_profile by noting when to use static profile instead. The purpose is 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?

The description clearly indicates when to use this tool (for change-feed queries) and when to use entity_profile instead. It also describes the multi-source fan-out and fallback behavior, providing explicit context for correct invocation.

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

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

Discloses scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24 hours) users. No contradiction with annotations (idempotentHint, readOnlyHint).

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: purpose, usage, scoping/detail. Every sentence adds value; no wasted words.

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

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

Given the simple two-param tool with no output schema, the description fully explains purpose, usage, behavior, and parameter examples. Complete for correct agent usage.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds practical examples for key and value, enhancing understanding beyond the schema.

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

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

The description clearly states the tool saves data for reuse, specifies the resource (key-value pairs), and distinguishes from sibling tools recall and forget by mentioning their usage.

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 discovering something worth carrying forward. Mentions pair with recall and forget, providing clear alternatives.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive; the description goes well beyond them by explaining cascading internal lookups, graceful degradation of LEI/FIGI enrichment, explicit labeling of unresolved identifiers, and ISIN-to-LEI mapping for non-US issuers. This is rich behavioral disclosure with 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 long, but it is front-loaded with purpose, use-first guidance, and supported types. The company parenthetical is dense but contains many edge-case-relevant details (fallback behavior, source labeling, unresolved handling). It could be trimmed, but every sentence contributes meaningful decision-making information.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns: canonical identifiers, source labels, unresolved fields, and the internal multi-step resolution/replacement of manual lookups. It covers input formats, supported entity types, enrichment fallbacks, and limitations (e.g., GLEIF/OpenFIGI unavailable), making it complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable meaning beyond the schema: it explains what each supported type returns (CIK/ticker/LEI/FIGI for company; RxCUI/ingredient/brand for drug) and clarifies how values like ISIN are interpreted. This elevates the parameter semantics beyond the schema alone.

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

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

The description opens with concrete user phrasing examples and states a specific, non-tautological purpose: resolving user-spoken names to canonical identifiers needed by other tools. It clearly distinguishes the tool from siblings by focusing on identifier resolution rather than profiles or 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?

It explicitly advises 'Use FIRST whenever you have a name but need an ID' and details supported entity types with input formats. It does not explicitly name alternative tools or when-not-to-use conditions, but the context is clear enough for an agent to select it appropriately.

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, openWorldHint, and non-destructive behavior. The description adds behavioral context: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized. Returns ranked list with score, confidence, signal density per entity.' No contradictions.

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

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

Two sentences: first sentence states core purpose, second sentence gives use case and output details. Front-loaded, 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?

Description covers the process, output structure, and a usage scenario. Given no output schema, it describes return values well. Could mention error handling or edge cases, but overall sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific details beyond what the schema provides; it focuses on tool functionality rather than parameter meanings.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Description provides clear context: 'useful for competitive AI-marketing audits'. It implies when to use (comparing multiple entities) but does not explicitly list alternatives or when not to use, though the sibling list suggests ai_visibility_check for single entity checks.

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 it as readOnly and idempotent. Description adds behavioral details: it fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This is excellent 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 slightly long (about 150 words) but well-structured: composite nature, use cases, return value, ecosystem limitation, failure behavior. Every sentence adds value, and the core purpose is 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 the complexity and the lack of output schema, the description provides a detailed summary of what is returned (summary block, advisory details, links, alternative versions) and explains failure handling. It is complete for the tool's purpose.

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 does not add much beyond the schema for parameters; it mentions that version defaults to latest when omitted, which is already in the schema. However, the explanation of the return value provides context for parameter usage.

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

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

The description clearly states it is a composite check for npm packages, aggregating license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support from deps.dev and bundlephobia. It is distinct from sibling tools, none of which mention npm or package analysis.

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

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

Explicitly tells when to use: when agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding towards alternatives for other ecosystems.

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. Description adds specific behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation flag. 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?

Concise with three well-structured sentences. Front-loaded with core purpose, then usage guidance, then technical details. 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?

No output schema, but description explicitly states return values: top-N passages with character offsets and similarity scores. Also mentions pairing with grounded tool, providing complete 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%. Description adds limited value beyond schema: for 'text' it adds context ('the text you already pulled'), for 'query' gives examples, and for 'limit' mentions default 5. Baseline 3 due to high coverage.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples like SEC 10-K and articles. It distinguishes itself by explaining how it pairs with ask_pipeworx_grounded, a sibling tool, for grounding over passages.

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 the record is too big to cram into the prompt' and that it saves context. Provides pairing guidance with grounded tool, though does not explicitly state when not to use.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, and the description adds behavioral details such as SMS daily cap ('10/day') and webhook auto-disable after 10 consecutive failures. It also explains authentication requirements. No contradiction with annotations.

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

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

The description is a single paragraph that is front-loaded with purpose and then details. It is informative but could be more structured (e.g., bullet points for delivery types). However, it avoids unnecessary verbosity and every sentence contributes 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 complexity (3 params, nested objects, no output schema), the description covers the tool's purpose, auth requirements, all supported types with parameter examples, delivery options with caveats, and key behaviors. It lacks explicit mention of return structure beyond the ID, but that is acceptable 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%, baseline 3. The description enriches parameters by providing type-specific examples (e.g., sec_8k items, polymarket_edge topic) and delivery sub-options with format constraints and behaviors (e.g., phone verification, webhook signing secret). This adds significant value beyond the schema.

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

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

The description clearly states the tool's action ('Create a proactive monitoring subscription'), specifies the resource ('subscription'), and outputs ('Returns the new subscription id'). It differentiates from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation and listing supported types and delivery channels.

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 prerequisites ('Requires a Pipeworx OAuth account; anonymous + BYO cannot persist subscriptions'), and lists supported types with examples. However, it does not explicitly state when not to use the tool or name alternative tools, though the context signals include many 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 indicate read-only, idempotent, open-world. Description adds context that it returns example questions with tool+argument shapes from a live catalog, and that it's a static onboarding tool. 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 somewhat long but well-structured: front-loaded with alternative phrasings, then explains output categories, then usage. Every sentence adds value; minor redundancy could be trimmed.

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

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

Given single optional parameter and no output schema, description adequately explains output structure and usage. Does not cover errors or edge cases, but acceptable for a simple tool.

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

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

Schema coverage is 100%. Description adds no new semantic meaning beyond the schema's parameter description. It restates the topic options, which are 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?

Description clearly states the tool returns category-bucketed example questions for Pipeworx, and explicitly positions it as the first tool to use for onboarding. It distinguishes from siblings like 'discover_tools' by stating 'Use this FIRST'.

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

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

Provides explicit guidance: use first when you don't know what Pipeworx can do, call with no arguments for full spread or pass topic to focus. Does not explicitly exclude other tools, but direction is clear.

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

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

Beyond annotations, it explains ownership enforcement, deactivation (not deletion), and that historical events remain accessible via 'recent_alerts'. This adds significant value without contradicting 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, no wasted words. Front-loaded with primary action, then constraints and side effects. Excellent structure for quick comprehension.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, ownership, deactivation behavior, and connection to a related tool ('recent_alerts'). It is complete and self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by linking the id to 'subscribe' and explaining the effect of the operation, providing more meaning than the schema alone.

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

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

The description clearly states the action ('Cancel a subscription by id') and specifies the resource ('subscription'). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by noting ownership enforcement and deactivation semantics.

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

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

The description provides clear context: you can only cancel your own subscriptions, and it deactivates instead of deleting. It implies when to use this tool versus alternatives, though it does not explicitly exclude scenarios.

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, so the bar is lower; the description adds significant behavioral context: the two processing paths (SEC EDGAR + XBRL vs grounded pipeline), the meaning of could_not_verify with verification_error (not evidence), the unsupported verdict meaning, and that it replaces 4–6 sequential calls. This exceeds the annotation-provided safety profile and gives the agent crucial handling instructions.

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

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

The description is somewhat long but densely packed: it opens with example intents, then gives usage guidance, processing paths, return values, a high-importance caveat, and an efficiency note. It is well-structured with clear breaks, though it could be trimmed slightly without loss of essential 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?

There is no output schema, so the description must explain return values; it does so by listing the six verdicts, the actual value with citation, and reasoning. It also explains the two tricky verdicts (could_not_verify and unsupported) in detail, and covers the two processing paths. For a tool with this complexity, the description is highly complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no parameter-specific syntax beyond what's in the schema; it only mentions 'exact percent-delta math' which indirectly relates to tolerance but doesn't add meaning beyond the schema's description of tolerance_pct.

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

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

The description states a specific verb+resource: natural-language claim verification against authoritative sources. It provides multiple example phrasings (fact check, verify the claim) and distinguishes this tool from general Q&A siblings by emphasizing factual claim verification with a structured financial path and grounded pipeline. It also lists output verdict types, making the purpose unambiguous.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use. It also explains the routing between financial and other claims. However, it does not explicitly mention when not to use this tool or name alternatives (e.g., ask_pipeworx for general queries), so it falls short of a 5.

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