Fmcsa

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

Annotations already declare readOnly, idempotent, not destructive, and open world. The description adds value by explaining model selection (default workers-ai vs BYO Anthropic), payment responsibility, and return format (per-model fields + combined view). It does not contradict annotations.

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

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

Single paragraph, front-loaded with action, includes essential details (default model, optional key, return structure, use cases) without unnecessary words. Every sentence adds value.

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

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

Given the absence of an output schema, the description compensates by specifying the return format. It covers model options, key requirement, use cases, and disambiguation context parameter. Sibling tools are listed but the description makes the tool's unique role clear.

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 detailed descriptions for all 4 parameters. The description adds some context (default model, payment flow) but does not significantly enhance understanding beyond the schema. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('probe') and resource ('LLMs') and clearly states the output (visibility score 0-100 per model). It distinguishes from sibling tools like ask_pipeworx and scan_competitor_ai_presence by focusing on general AI visibility rather than specific factual queries or competitor scanning.

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 concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional API key. However, it does not explicitly state when not to use this tool or provide direct comparisons to alternatives like entity_profile or deep_research.

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 routing behavior (4,991 tools), citation format (pipeworx:// URIs), and default nature. Annotations already indicate safe, idempotent operations; description adds detail 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?

Well-structured with clear sections and front-loaded preference. Slightly verbose but each sentence adds value; could be trimmed slightly without losing meaning.

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

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

Complete for a complex tool: explains return format, citations, when to use alternatives, and provides examples. No output schema needed given the description.

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

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

Schema has 100% coverage with descriptions and aliases. Description adds context that the question can be natural language and provides examples, 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?

Description clearly states it routes questions to thousands of tools and returns structured answers with citations. It differentiates itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicit guidance: 'PREFER OVER WEB SEARCH' for specific domains, 'START HERE for most questions', and 'Step up only when needed' with concrete alternatives. Provides examples of when to use and when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: source-preference ranking behavior ('when your question names a source, it wins'), experimental nature, fallback to nothing (full working router), and comparison purpose. No contradictions with annotations.

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

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

The description is moderately long but every sentence adds value: it explains what the tool is, how it differs, when to use, and its fallback behavior. Could be slightly tighter, but it's well-structured with a clear lead-in.

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

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

Given the complexity of a beta router routing to 4,991 tools, the description covers the key aspects: routing improvements, source-preference ranking, identical interface to ask_pipeworx, and comparison purpose. No output schema exists, but the response is said to be identical to the stable router, which is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds that parameters are identical to ask_pipeworx but doesn't elaborate on semantics beyond what the schema already provides. The aliases are well-documented in the schema.

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

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

The description clearly states this is the beta version of ask_pipeworx, a universal router with the same 4,991 tools and same arguments, but with experimental source-preference ranking. It explicitly distinguishes itself from the stable ask_pipeworx by noting it's the 'experimental edge' with candidate routing improvements.

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 tells users to use it exactly like ask_pipeworx when they want the newest routing, and that results are compared against the stable router. It implies when not to use by contrasting with the stable version, though it could be more explicit about avoiding it for production reliability.

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

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

Adds key details beyond annotations: cost (extra LLM call), return format with evidence and refusal reasons, and the constraint of not inventing facts. No contradiction with annotations.

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

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

Single paragraph containing all essential info, but could be more structured with bullet points or headings for quick scanning. 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, yet the description fully explains return structure (answer, evidence, confidence, source, etc.) and entire refusal reason taxonomy, making it complete for high-stakes use.

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

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

100% schema coverage; description mentions the 'question' main parameter but adds minimal new info beyond the schema's alias listing.

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?

Describes itself as a hallucination-resistant answer mode for high-stakes reads, distinct from sibling ask_pipeworx. Verbs: 'extracts' and 'fetches' clarify action.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on', provides examples, and advises preferring ask_pipeworx for casual lookups.

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

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

Annotations already mark as readOnly, idempotent, openWorld, and non-destructive. The description adds extensive behavioral context: fan-out logic per market type, response shapes (market/match/resolver), safety mechanisms (low-confidence short-circuit, closed markets, wide spreads), news fallback handling, and resolution-rule risk. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, safety). Every sentence adds essential detail for correct usage. Slightly verbose given the complexity, but justified.

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

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

Despite no output schema, the description comprehensively explains return value fields (result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields), edge cases (low confidence, closed markets, wide spreads, cancellation rules), and provides examples. No gaps for agent understanding.

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

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

Schema description coverage is 100%, but the description adds significant meaning: explains market input can be slug, URL, or question text; clarifies depth enum values (quick=2-3 sources, thorough=full fan-out); details include_raw default false and impact on response size. This goes well 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, identifies specific use cases ("should I bet on X", "what does the data say about Y", "is there edge in Z"), and lists multiple input formats (slug, URL, question text). It differentiates from sibling tools by focusing on single-market research with data fan-out and evidence packet return.

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 and input formats, and includes examples like market_input in the schema. It does not explicitly state when not to use the tool or compare to alternatives, but the sibling list and focus on Polymarket bets make the context clear.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context, including data sources (SEC EDGAR for companies, FAERS/FDA for drugs), handling of fiscal year ends, result sorting, and citation URIs. No contradictions with annotations.

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

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

The description is well-organized, starting with example queries, then the core function, then details per type. It is slightly verbose but every sentence adds value. No fluff, but could be slightly more concise 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 tool's complexity (two entity types, multiple metrics, sorting), the description covers what is returned and how results are presented. The input schema is fully covered. Without an output schema, the description sufficiently explains the return format and citation mechanism.

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 meaning by explaining what data each type returns and providing formatting guidance for values (tickers/CIKs for companies, drug names). It also clarifies min/max constraints and that results are sorted by primary metric.

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

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

The description clearly states the tool is for side-by-side comparison of 2–5 companies or drugs, distinguishing it from single-entity lookups. It uses specific verbs like 'compare' and provides concrete examples of natural language queries that trigger it.

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

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

The description explicitly advises preferring this tool over sequential single-pack lookups when comparing entities. It provides usage context with examples, though it does not explicitly list alternatives or 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 provide readOnlyHint, openWorldHint, idempotentHint. Description adds extensive context: account requirement, parallel execution, return format (findings with gaps/contradictions), iteration behavior, timing expectations, and data source limitations.

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

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

The description is well-structured with front-loaded account requirement and alternative, but is verbose with many details. While comprehensive, it could be streamlined without losing essential information. Still earns a high score for 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 tool complexity (no output schema, nuanced behavior), the description is extremely complete: covers return format, edge cases (empty gaps for uncatalogued topics), iteration mechanics, and timing. No gaps left unaddressed.

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 substantial value by explaining depth levels' behaviors (quick=3 facets, standard=gap recovery+contradictions, thorough=leads+contradictions) and that question can be broad/multi-part without restriction.

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

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

The description clearly defines the tool as a grounded multi-source research tool across Pipeworx's structured data sources, using verbs like 'research' and specific resource identification. It effectively distinguishes from siblings like ask_pipeworx and bet_research.

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

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

Explicitly states when to use (broad/multi-part questions over structured data), when not (single lookup, breaking/news), and provides alternatives (ask_pipeworx). Also notes account requirements and alternative usage if not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds that results are ready-to-call with full schemas, which is valuable behavioral 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?

Two dense sentences with no filler. Front-loaded with purpose. Every sentence earns its place.

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

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

No output schema, but the description explains return format (top-N tools with schemas). Parameter documentation is complete. Could mention default limit value, but otherwise thorough.

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

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

Schema coverage is 100%. The description explains the query parameter as 'natural language description' and lists aliases, which adds meaning beyond the schema's brief descriptions. Also mentions limit defaults.

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 'Find tools by describing the data or task' with a specific verb and resource. It lists many example domains, distinguishing it from sibling tools that search for data rather than tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds significant behavioral context: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; details return fields (cik, recent_filings with URIs, fundamentals sorted by period end, patents with sunset status, news via GDELT->GNews fallback, LEI); and notes that patents soft-fail. No contradiction with annotations.

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

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

The description is relatively long but well-structured with examples, bullet-like listing of returns, and clear constraints. Every sentence adds value, though a slightly more structured presentation (e.g., formal bullet list) could improve readability. Still, it earns its length.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is thorough. It lists all major return components and notes limitations (patent sunset, name support). However, it could provide more detail on the output structure (e.g., format of fundamentals or news entries) to fully compensate for the missing output schema.

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

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

The input schema provides enum for type and description for value. The description adds essential meaning: it confirms that only 'company' type is supported, specifies that value accepts ticker or zero-padded CIK (not names), and advises using resolve_entity if only a name is available. This enriches the schema effectively.

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

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

The description explicitly states the tool's purpose: producing a full cross-source profile of a US public company in one parallel call. It provides example queries (e.g., 'tell me about X', 'brief me on Tesla') and clearly distinguishes from sibling tools by advising preference over chaining single-pack lookups and recommending resolve_entity for names.

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

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

The description gives clear when-to-use guidance: whenever a user asks for a holistic view of a company. It also specifies when NOT to use it: when only a name is available (use resolve_entity first) or when the entity is not a US public company. This effectively differentiates from siblings like compare_entities or resolve_entity.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, etc., but the description adds valuable behavioral context by listing exactly what fields are returned (legal name, address, status, fleet size, etc.). No contradictions with annotations.

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

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

Three sentences with no wasted words: first sentence covers purpose and return data, second covers parameter usage, third provides sibling alternatives. Front-loaded with the main action.

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 complete enough given the tool's low complexity (2 params, no output schema). It explains all return fields, parameter usage, and sibling differentiation. Minor gap: no mention of error behavior (e.g., carrier not found), but not critical.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter usage (set 'by' to 'dot', 'mc', or 'name' with the value in 'value') but does not add new semantics beyond the schema's own 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 action ('look up') and the specific resource ('US motor carrier in the FMCSA census'), and distinguishes itself from sibling tools by explicitly naming fmcsa_operating_authority and fmcsa_safety_snapshot as alternatives for different needs.

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

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

The description provides explicit guidance on when to use this tool versus alternatives ('For carrier authority ... use fmcsa_operating_authority; for safety scores use fmcsa_safety_snapshot'), and explains how to set the 'by' and 'value' parameters for different lookup types.

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, leaving less burden on description. The description adds behavioral context like 'Keyless' (no auth required) and specifies the status values returned, which goes beyond annotations.

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

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

Description is compact (2-3 sentences), front-loaded with the main action and output. Every sentence adds value: purpose, output details, usage guidance, and sibling differentiation. No redundant or filler content.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, output ingredients, usage context, and behavioral notes. It could be more complete by mentioning any pagination or limitations, but overall it is sufficient.

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

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

Schema coverage is 100%—the single parameter `dot_number` is already described in the schema with an example. The description does not add new semantic information about the parameter beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states tool retrieves FMCSA operating authority by USDOT number, specifying exact outputs (MC docket number, statuses for common/contract/broker authority). It explicitly distinguishes from sibling tools (fmcsa_carrier_lookup, fmcsa_safety_snapshot) by noting this tool provides legal authority to operate, complementing the others.

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 frames the tool as answering 'is this carrier authorized to operate/broker freight' and positions it as complementing census and safety tools, giving clear context for when to use it versus alternatives. It provides both a use case and differentiation.

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 and idempotentHint, meaning the tool is safe and idempotent. The description adds value by detailing the specific data returned and the API key requirement, which is not covered by annotations.

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

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

The description is two sentences long, with the first sentence clearly stating the primary purpose and the second providing necessary context about the API key. Every sentence is efficient and contributes meaning.

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 is simple with only two parameters and no output schema, the description fully explains what the tool does and what it returns. It covers required inputs, output details, and a prerequisite, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description merely repeats the dot_number example and notes the _apiKey injection, adding no new semantic 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?

The description clearly states the tool retrieves an FMCSA safety profile for a carrier by USDOT number, listing specific data points like safety rating, OOS status, and SMS BASIC categories. It distinguishes from sibling tools like fmcsa_carrier_lookup and fmcsa_operating_authority by focusing on the safety snapshot 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?

The description explicitly mentions the requirement for an FMCSA webKey and how to obtain it, providing clear context for usage. However, it does not explicitly state when not to use this tool or suggest alternatives, limiting guidance on tool selection among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds significant behavioral context: returns specific fields (USDOT number, legal/DBA name, city/state, power units, drivers, status), ranking by fleet size, case-insensitivity, partial matching, and 'Keyless' operation. This adds value beyond annotations without contradiction.

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

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

Two sentences, front-loaded with the core action, no wasted words. Includes essential details (partial match, ranking, keyless) and a sibling reference. Highly efficient.

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

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

Given the tool is a search with 3 parameters, no output schema, and rich annotations, the description covers return fields, ranking, and sibling relationship. Missing pagination or total count details, but limit parameter mitigates this. Overall 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. The description reiterates parameter meaning (e.g., 'e.g. "swift transport"' for name, 'Max results (1-50, default 15)' for limit) but does not add new semantics beyond the schema. No extra nuance or usage hints 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 verb 'Search', the resource 'US motor carriers', and key features: partial case-insensitive matching, ranked by fleet size. It distinguishes from sibling 'fmcsa_carrier_lookup' for detail retrieval. This meets the highest standard of 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?

Provides explicit guidance to use 'fmcsa_carrier_lookup' for full detail on a returned USDOT number, establishing a clear when-to-use alternative. Does not exhaustively cover when not to use (e.g., for safety ratings, use other siblings), but the given alternative is sufficient. Lacks explicit not-to-use 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 destructiveHint=true and idempotentHint=true, so the description's simple 'Delete' adds no further behavioral insight. No additional context like effect on other data or permissions is provided.

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

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

Two concise sentences with no filler. Front-loaded with primary action, then usage guidance.

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

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

For a simple tool with one required parameter, good annotations, and no output schema, the description sufficiently covers purpose, usage, and pairing with siblings.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter. The description merely says 'by key', adding no new 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?

The description clearly states the tool deletes a previously stored memory by key, with specific verbs ('Delete') and resource ('memory'), and distinguishes from related siblings like 'remember' and 'recall'.

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

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

Explicitly describes when to use (context stale, task done, clear sensitive data) and pairs with sibling tools 'remember' and 'recall', providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond annotations by explaining the process and output format. 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 concise (3-4 sentences) and well-structured. It front-loads the purpose, then explains the process, and lists use cases. Every sentence adds value without unnecessary elaboration.

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

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

Given no output schema, the description explains the output as 'standard llms.txt markdown format' and 'single text blob ready to drop at site-root/llms.txt'. It covers the inputs fully via the schema. Could mention error handling or rate limits, but overall sufficient for the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'title/description/key links' extracted, which provides context but does not add significant meaning to the url or max_links parameters beyond what the schema already provides. The schema descriptions are 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 verb 'generate', the resource 'llms.txt file', and the context 'for any URL so AI crawlers can index the site cleanly'. It distinguishes from sibling tools by focusing specifically on generating the llms.txt format, whereas siblings like ai_visibility_check or scan_competitor_ai_presence serve different purposes.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitor AI visibility. It does not mention when not to use or alternatives, but the sibling list does not contain a direct alternative, so the guidance is clear and sufficient.

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. The description adds return fields and the default behavior of listing only active subscriptions, which is useful context beyond annotations.

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

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

Two sentences, front-loaded with the core purpose, and no wasted words. Highly efficient.

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

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

For a simple tool with one optional parameter, strong annotations, and no output schema, the description covers purpose, usage, and return fields comprehensively.

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

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

Schema description coverage is 100%, and the one parameter (include_inactive) is clearly described in the schema. The description adds minimal extra value by implying the default behavior.

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 'List the caller's active subscriptions', specifying the verb (list) and resource (subscriptions). It also distinguishes 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?

The description provides specific use cases: 'review what you're monitoring before adding more or to find an id to cancel'. It gives context but lacks explicit when-not-to-use guidance.

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

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

Annotations are minimal (no idempotent or destructive hints), but the description adds important behavioral context: rate-limited to 5 per identifier per day, free, does not count against tool-call quota, and signals that feedback is read daily and influences roadmap. This goes beyond the annotations.

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

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

Description is concise at 5 sentences, front-loaded with purpose and usage. Every sentence adds value—no redundancy or fluff. Structure flows naturally from what to when to how.

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 (3 params, 2 required, nested object but not complex), the description covers all necessary aspects: purpose, usage, parameter semantics, constraints (rate limit), and behavioral impact. No output schema is needed for a feedback tool; the description implies acknowledgment.

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

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

Schema coverage is 100%, and the description adds significant meaning: it explains the enum values (e.g., 'bug = something broke or returned wrong data'), provides guidance on message content (be specific, which tool, what error), and clarifies that context is optional. This enriches 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's purpose: sending feedback about bugs, missing features, data gaps, or praise to the Pipeworx team. It distinguishes itself from sibling tools by focusing on feedback rather than data retrieval or 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 specifies when to use each feedback type (bug, feature, data_gap, praise) and provides clear negative guidance: do not paste end-user prompts, describe in terms of Pipeworx tools/packs. This helps an AI agent decide when to invoke the tool.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds that data is 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h', providing valuable insight into data source, privacy, and staleness.

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

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

The description is compact with no redundancy. The first sentence states the core function, followed by bullet-style use cases, and a final sentence about data origin and caching. Every sentence adds value.

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

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

For a simple read-only tool with one optional parameter, the description covers what is returned (top tools, top packs, total call volume), caching behavior, and data privacy. No output schema is needed as the return is well-described.

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

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

The single parameter 'window' is fully described in the schema (enum with descriptions). The tool description adds extra guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', enhancing the schema's description.

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

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

The description clearly states the verb 'Returns' and the resources 'top tools, top packs, and total call volume'. It distinguishes from sibling tools like 'ask_pipeworx' by focusing on aggregated trending data rather than direct queries.

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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and aligning use cases. While alternatives are not directly named, the use cases implicitly guide when to use this tool over others like 'ask_pipeworx'.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds rich behavioral details: semantic similarity filtering, placeholder filtering, partition check, fill check against live book. No contradictions. Discloses that realizable_edge_pp ≤ 0 means do not trade.

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

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

The description is longer than average but well-structured with a clear flow: main purpose, argument usage, detailed behavior of each mode, then output format and fill check. Every sentence adds value, but could be slightly more concise.

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

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

Even without an output schema, the description comprehensively explains the response structure (opportunities[], partition_check, fill check). Covers all inputs, behavior, limitations, and post-processing. Highly complete for a complex financial arbitrage 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% but description adds significant meaning: explains event vs topic, provides example slugs, describes cross-event mode behavior, semantic anchor (Jaccard similarity), and partition filter. Goes well 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and contrasts with sibling tools like polymarket_edges.

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

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

Explicitly specifies when to use each argument: 'Call with NO args for trending_scan', 'event for a specific market', 'topic for cross-event scanning'. Provides examples and mentions fill check to avoid non-tradable signals. Also refers to polymarket_fill_risk for custom sizing.

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, openWorld, idempotent, non-destructive. The description adds rich behavioral context: caching at KV level keyed on knobs, response structure with diagnostics (WHY segments are empty), and tradeable-edge knobs that affect outcome. No contradictions.

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

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

The description is dense and well-structured, starting with purpose, then model families, knobs, and response details. However, it is quite long; some details (specific α values for sports) could be trimmed without losing clarity. Still front-loaded with core 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?

Despite no output schema, the description fully explains the response top-level structure (by_segment, fed_candidates, _diagnostics) and diagnostic counters. It provides enough detail for an agent to understand what to expect and how to use the tool effectively.

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

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

Schema coverage is 100% (9 parameters described in schema), so baseline 3. The description adds significant value by explaining nuanced behaviors like slippage_pp ('Polymarket has zero trading fees...') and min_partition_leg_kelly (why min_kelly doesn't filter partition arbs).

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and distinguishes from siblings like 'polymarket_arbitrage' through its unique angle of edge discovery without paging.

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

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

The description explicitly says it is for discovering opportunities without paging hundreds of markets and details tradeable-edge knobs. However, it does not explicitly mention when not to use it or compare with sibling tools like 'polymarket_arbitrage', which are clear alternatives for arbitrage-specific use cases.

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

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

The description discloses behavioral details beyond annotations, including response structure (tracked, expired, snapshot_dates), computation method (daily closes), and data limitations (60-day TTL, gaps due to cache-misses). No contradictions with annotations.

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

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

The description is well-structured, starting with purpose and then detailing response fields. It is somewhat verbose but every sentence adds value. Could be slightly more concise.

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

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

Given the lack of output schema, the description thoroughly explains the return structure and limitations. It covers all necessary aspects for an agent to understand what the tool provides and its constraints.

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 largely repeats schema defaults and clamps. It provides minimal extra value (e.g., cache-miss explanation) but does not significantly enhance parameter understanding.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering specific questions about edge duration and trend. It distinguishes itself from a raw snapshot tool by focusing on time-series 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?

The description implies usage for analyzing edge history and decay, but lacks explicit guidance on when to use this versus sibling tools like polymarket_edges. No exclusions or alternative suggestions are provided.

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

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

Annotations indicate safe read-only behavior. Description adds operational details: walks the ladder, returns specific metrics, explains forced directional risk in baskets. Does not contradict 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 well-structured with sections for single-market and basket, uses bold for emphasis. It is slightly long but every sentence adds value. Could be marginally trimmed but remains clear.

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

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

No output schema, so description fully explains return values for both modes: top_of_book, vwap_fill_price, slippage_pp, etc. for single; theoretical_sum, realizable_sum, capture_ratio, forced_directional_risk for basket. Adequately covers all important aspects.

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

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

Schema covers 100% of parameters, but description adds significant value: explains size_usd as settlement notional for baskets, clarifies side defaults, and defines the exclusivity of market vs event. This goes beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates itself from siblings like polymarket_arbitrage and polymarket_edges by being a prerequisite risk check.

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 rationale about theoretical overround not being capturable and partial basket fills causing directional risk, guiding when to use and when not.

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 declaring the tool as readOnly, idempotent, and nondestructive, the description details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type) that clarify when the spread is valid. 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 detailed but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though slightly verbose. Front-loads core purpose.

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

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

No output schema, but description comprehensively covers response structure (leg prices, top_spreads_pp, safety fields) and their interpretations. Adequately addresses the complexity of cross-venue spread calculations.

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

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

Schema coverage is 100% and description adds substantial meaning: explains two modes, lists all ten topics for the topic parameter, and clarifies override behavior for explicit tickers. Enhances understanding beyond schema alone.

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

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

Clearly states it is a cross-venue spread tool for Kalshi and Polymarket, distinguishes from siblings (e.g., polymarket_arbitrage) by specifying the dual-venue focus. Provides two modes and concrete examples.

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

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

Explicitly explains when to use (find spreads between venues) and when spreads are meaningless (compatibility_warning, temporal alignment misalignment). Warns that pre-mapped topics may not be tradeable. Lacks explicit contrast with alternatives but adequately guides usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the pairing with remember/forget. This goes beyond annotations without contradiction.

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

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

The description is three sentences, front-loading the action. It is efficient with no redundant text, though it could be slightly more compact.

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 read-only get/list tool with no output schema, the description covers the two return outcomes (value or list of keys) and scoping. It does not detail format, but it is fairly complete given the tool's simplicity.

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 description coverage is 100%, with the 'key' parameter already described as 'Memory key to retrieve (omit to list all keys)'. The description essentially repeats this, adding no new semantics beyond reinforcing the behavior. 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 retrieves a value or lists all keys, with specific verb-resource pair ('retrieve a value', 'list all saved keys'). It distinguishes from sibling tools like 'remember' and 'forget' by referencing them directly.

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

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

The description explains when to use the tool ('look up context stored earlier') and when to omit the key (list all). It also mentions pairing with 'remember' and 'forget'. However, it does not explicitly state when not to use or list alternatives among other sibling tools, though the context is clear.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, etc. The description adds behavioral specifics: what fields are returned, mark_read semantics, and polling support. 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?

Front-loaded purpose, each sentence adds value. No fluff. Efficiently conveys key information in a few sentences.

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

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

Despite no output schema, description specifies return fields. All parameters are explained. Polling and alternative endpoint are mentioned. Complete for a straightforward read tool with good annotations.

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

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

Schema coverage is 100% (baseline 3). Description adds meaning to each parameter: type filter, limit default, since as fired_at, mark_read and unread_only behavior. Provides more context than schema alone.

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

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

The description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It details return fields and filter options, distinguishing it from siblings like recent_changes and list_subscriptions.

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

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

It explains polling suitability and provides an alternative access method (registry URL). It also describes the mark_read behavior for continuous polling. Could explicitly contrast with similar tools but sufficient context 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 readOnly, openWorld, idempotent, non-destructive. Description adds details on fan-out, fallback logic from GDELT to GNews, USPTO soft-failure, and return structure (changes[] grouped by source + total_changes + citation URIs). No contradictions.

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

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

Description is informative but somewhat lengthy. Front-loaded with example queries. Every sentence adds value, but could be slightly more concise. Still well-structured.

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

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

Given complex multi-source behavior, fallback logic, soft-failures, and lack of output schema, the description covers return format, alternative tool, and parameter usage comprehensively. No gaps.

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

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

Schema already has 100% coverage with descriptions for all three parameters. Description adds extra context for 'since' with example formats and a recommended value ('30d') for typical monitoring, plus explains value can be ticker or CIK.

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 clear example intents, then states 'change feed for a company' with specifics on sources and window. Distinguishes by naming sibling tool entity_profile for static profiles.

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

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

Explicitly says 'Use entity_profile instead when you want the static profile' for exclusion. Provides context on when to use (recent updates/news) and alternatives.

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

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

Annotations already declare non-destructive, idempotent. Description adds that memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain 24 hours. No contradictions.

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

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

Four sentences, front-loaded with purpose, then when to use, then scoping, then pairing. 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?

Covers purpose, usage, param semantics, scoping, persistence, and sibling relations. No output schema needed for this simple tool. Complete and 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 100% with descriptions for key and value. Description adds naming conventions and value types (e.g., 'findings, addresses, preferences, notes') which adds value beyond schema.

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

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

Clearly states 'Save data the agent will need to reuse later' – specific verb (save) and resource (data for reuse). Distinguishes from sibling tools like recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward...' and names alternatives: 'Pair with recall to retrieve later, forget to delete.' Also explains scoping and persistence differences.

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 read-only, idempotent, and non-destructive. The description adds useful behavioral context: 'Each call cascades through several lookup endpoints internally', which explains internal complexity. No contradictions with annotations. The description complements annotations without being redundant.

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 a clear purpose statement. It is moderately long but every sentence adds value, explaining supported types, return values, and internal cascading. Minor redundancy (e.g., 'auto-disambiguated' could be omitted) but overall 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 that there is no output schema, the description fully compensates by specifying the exact return fields for each entity type (including citation URIs). It also explains the tool's internal behavior and usage context. No missing information; the tool's behavior is fully covered.

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

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

Although the input schema covers 100% of parameters, the description significantly enhances semantics by detailing the return structure for each entity type (e.g., for company: 'returns ticker + 10-digit CIK + company_name from SEC EDGAR + pipeworx://edgar/company/{cik} citation URI'). This goes beyond the schema's basic 'value' description, helping the agent understand what will be returned.

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: resolving a user-spoken name to a canonical/official identifier. It provides specific example queries ('What's the ticker for…', 'find the CIK for…') and explicitly lists supported entity types (company, drug) with their respective outputs. This uniquely distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

The description includes a strong usage guideline: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it replaces 2-3 manual lookups, implying efficiency. While it doesn't explicitly state when not to use, the context is clear given the tool's focus on resolution. The sibling list contains tools with different purposes, so differentiation is adequate.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. Description adds that it internally probes with ai_visibility_check, treats first entity as subject, and returns ranked list with score, confidence, signal density. 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, front-loaded with main action and output, no filler. 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?

Given no output schema, description sufficiently covers output structure, usage context, and internal mechanism. No missing critical info for a read-only comparison tool.

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

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

Schema coverage is 100% (baseline 3). Description adds meaning: first entity treated as 'subject', rest as competitors; default model is workers-ai unless specified. These details go beyond schema descriptions.

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

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

Description explicitly states compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. Distinct from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Provides clear use case (competitive AI-marketing audits) with an example question. Implies alternative when not needed (single entity check via ai_visibility_check), but no explicit exclusion of other 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?

Description adds behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia may take 5-30s and appears in sources_failed. Annotations already indicate readOnly, openWorld, idempotent, non-destructive, so description complements 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 comprehensive and front-loaded with key information. Every sentence adds value, though it could be slightly more concise. Still, it balances detail and clarity well.

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

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

The description fully compensates for the lack of an output schema by detailing the return structure (summary block, advisories, links, alternatives). It also covers edge cases (partial failures, timing) and ecosystem scope, making it complete for a complex composite 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 both parameters well-described. The description adds no new parameter information beyond what the schema already provides (e.g., scoped packages, default version). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages using deps.dev and bundlephobia. It is distinct from sibling tools, which cover different domains (AI, betting, FMCSA, etc.).

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

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

Explicitly states when to use ('whenever an agent asks is X safe / popular / small'), ecosystem constraint ('NPM ecosystem only in v1'), and alternatives for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also warns about bundlephobia timing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant context: 200K char cap with truncation flag, BGE-base-en embeddings, 500-char overlapping windows, cosine similarity, and offset for verification. This goes well beyond what annotations provide.

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

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

The description is four sentences, front-loaded with purpose, then usage, then technical details. Every sentence adds value without repetition. Structure is 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?

With no output schema, the description explains return format: top-N passages with offsets and similarity scores. It also covers limits (200K chars, truncation), technical details (embedding model, windowing), and pairing with another tool. 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%, so baseline is 3. The description adds value by giving examples for query (e.g., 'supply-chain risk'), clarifying max chars for text, and stating default and range for limit (1-20, default 5). This enhances understanding of 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 performs semantic search inside a fetched record, using a specific verb (search) and resource (within a source). It distinguishes from sibling tool ask_pipeworx_grounded by noting they pair together: fetch with gateway then ground 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: 'Use when the record is too big to cram into the prompt'. Provides context on saving context and returning only relevant passages. Mentions pairing with ask_pipeworx_grounded. Does not explicitly exlude small records or list alternatives, but the guidance is clear and actionable.

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

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

Disclosures are consistent with annotations: readOnlyHint=false (write operation), idempotentHint=true (safe to retry). Adds context such as 10/day SMS cap, auto-disable after 10 webhook failures, and one-time webhook secret. 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?

Well-structured and front-loaded, but slightly dense. Every sentence adds value; no wasted words. Could be slightly more streamlined but still 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 no output schema, the description adequately explains return values (subscription id, webhook secret). Covers prerequisites, type options with examples, delivery channels with constraints, and error conditions (auto-disable).

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

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

Schema coverage is 100%, and description adds value with concrete examples, constraints, and behavioral details beyond schema (e.g., SMS requires verified phone, webhook auto-disable).

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It lists supported types and distinguishes from sibling tools like list_subscriptions 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 mentions prerequisites (OAuth account, anonymous/BYO cannot persist) and constraints (SMS cap, webhook verification). Does not explicitly compare to alternatives like recent_alerts or polymarket_arbitrage, but context is clear.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already provide safety profile. The description adds rich behavioral context: it returns example questions with exact tool+argument shape, drawn from the live catalog, and is the onboarding entry point. No contradictions, and it goes beyond annotations to explain the tool's role and output structure.

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

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

The description is dense but well-structured: it starts with triggering questions, states purpose, then explains parameters and output. Each sentence adds value, though there is minor redundancy (categories listed twice). It is appropriately sized for the complexity of the tool.

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

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

Given no output schema, the description fully explains the return format: 'Returns category-bucketed example questions... each with the exact tool + argument shape.' It also covers the intended use case (first-time user) and the parameter effect. The description, together with annotations, leaves no gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% (single optional 'topic' parameter with enum-like description). The description reinforces the parameter's purpose with examples ('e.g. "finance", "pharma", "betting"') and explains the behavior difference between including and omitting it, adding value beyond the schema.

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

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

The description clearly states this is the onboarding entry point for an agent that just connected. It uses specific verbs ('returns category-bucketed example questions') and resources ('live catalog of thousands of tools'). It distinguishes itself from siblings by stating 'Use this FIRST' and referencing meta-tools like ask_pipeworx and compare_entities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains parameter usage: 'Call with no arguments for the full spread, or pass topic to focus.' It lacks explicit when-not-to-use guidance but provides strong contextual hints.

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 ownership enforcement and that the row is deactivated not deleted, matching destructiveHint=false. Aligns with annotations, no contradiction.

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

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

Two concise sentences, front-loaded with action and resource, 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?

Covers behavior, side effects, and linkage to recent_alerts. Lacks explicit return value description, but no output schema exists.

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

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

Schema covers the single parameter fully. Description adds no additional parameter-level 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?

Clearly states 'Cancel a subscription by id', with ownership enforcement. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Describes ownership enforcement and mentions historical events via recent_alerts. Gives context for use, but does not explicitly state when not to use or alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and not destructive. The description adds valuable context about the two verification paths, return verdict types, and citation format, enhancing transparency 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 thorough but not excessively verbose. It front-loads with query patterns and proceeds to usage context, processing details, and output. Every sentence adds value, though slightly more conciseness could improve scannability.

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

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

Given the tool's complexity (two processing paths, multiple output verdicts), the description is complete. It covers when to use, how claims are routed, what output to expect (verdict, value, citation), and the replacement of multiple calls. No output schema exists, but the description sufficiently explains return values.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema for parameters; it mentions tolerance implied by claim wording but provides no new details about the parameters themselves.

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 specifies the tool's purpose clearly with example query phrases ('Is it true that...', 'fact check') and states it performs claim verification against authoritative sources. It distinguishes from siblings by noting it replaces 4-6 sequential calls and explains the two processing paths.

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 instructs to use this tool whenever factual checking is needed and differentiates between company-financial claims (using structured fast path) and other claims (using grounded pipeline). It lacks explicit 'when not to use' but the context and sibling names (e.g., deep_research) imply alternatives.

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