Nhtsa

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

Annotations already declare safe read-only behavior, and the description adds meaningful context: the default model choice, cost implications for using Anthropic, and the exact return structure. This goes beyond annotations without contradicting them.

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

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

The description is compact and front-loaded with the core action, then covers key operational details and use cases in three sentences. Every sentence adds value without redundancy.

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

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

Given the tool's moderate complexity, the description covers purpose, default behavior, cost implications, return format, and use cases. The input schema is fully documented, and the output structure is explicitly outlined, so no major gaps remain despite the absence of an output schema.

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

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

All four parameters are described in the schema with 100% coverage. The description adds extra semantics by explaining the default model and the role of _apiKey in enabling Anthropic calls, enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility (0-100). It mentions the default model and return shape, making the core purpose specific. However, it does not explicitly differentiate from siblings like scan_competitor_ai_presence, though the scope is broader in nature.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default model behavior. It does not explicitly say when not to use it or mention alternatives, but the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context: it routes the question to one of 5,564 tools across 1,462 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also notes 'one fast call' and that it works on every tier. This goes beyond annotations but doesn't fully describe failure modes or latency, so 4 is appropriate.

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

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

The description is long but information-dense, with the key directive front-loaded in the first sentence. It provides examples and explicit routing instructions. It could be slightly tightened but every sentence earns its place—domains, trigger phrases, alternatives, and behavioral notes all add value. The structured examples in the schema complement rather than repeat the description.

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

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

This is a complex multi-domain routing tool with no output schema, so the description carries a heavy burden. It fully covers what to use it for, how it works (routing to 5,564 tools), what it returns (structured answer with citations), when to step up to alternatives, and provides numerous examples. Given the tool's broad scope, the description is remarkably complete.

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

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

Schema coverage is 100% and all six parameters are aliases for the same 'question' parameter, which the schema already documents. The description adds value by listing the common aliases (q, text, input, query, prompt) and clarifying that the parameter accepts a natural-language question. It also provides three parameter examples in the schema. Since the description supplements the schema with usage context but the schema already covers meaning well, a 4 is warranted.

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 starts with a clear directive: 'PREFER OVER WEB SEARCH for questions about current or historical data' and enumerates specific domains (SEC filings, FDA drug data, FRED/BLS, etc.). It clearly distinguishes from siblings by naming alternatives like ask_pipeworx_grounded and deep_research for cases needing different behavior. It also provides concrete trigger phrases and examples, making the tool's purpose unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the user asks...' with concrete phrases and examples. It explicitly states when to step up: 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also covers exclusions like breaking-news, saying ask_pipeworx already routes to live news, and mentions it works on every tier.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: it is a beta with live candidate routing improvements, currently none active, and it is a full working router rather than a fallback. This goes beyond the annotations to explain the experimental nature and current state.

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 long and each sentence adds necessary context: what it is, current state, usage, and non-fallback status. It is slightly detailed but well-structured with no filler. It earns a 4 rather than 5 because it could be trimmed slightly without losing core 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?

For a universal router with 5,564 tools, the description is remarkably complete. It clarifies the beta status, the absence of active candidates, the exact equivalence to ask_pipeworx currently, and the response shape. It also explains how results are used, which gives the agent full context for invoking this tool.

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

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

The schema has 100% coverage with the 'question' parameter and five aliases described. The description only says 'same arguments' and doesn't add semantic detail beyond the schema, which is sufficient. Since the schema already explains parameters, the description adds no extra meaning, so 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 identifies the tool as a beta version of ask_pipeworx, a universal router, and explicitly states it is identical to the stable version with candidate routing improvements. It uses specific verbs ('ask', 'router') and distinguishes from the sibling tool ask_pipeworx by highlighting the experimental edge.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing clear when-to-use guidance. It doesn't explicitly say when not to use it, but implies preference for the stable router for non-experimental needs. The comparison to stable router is mentioned, giving context on its role.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds substantial behavioral context: it discloses refusal reasons, guarantees verbatim evidence, states that the answer is extracted only from the fetched data, and notes the extra LLM call cost. It does not contradict the annotations.

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

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

The description is information-dense but every sentence earns its place: it defines the mode, explains routing, specifies return and refusal shapes, gives use cases, and states tradeoffs versus the sibling tool. It is front-loaded with the core purpose and structured clearly.

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 fully compensates by enumerating the success response fields and all refusal reasons. It covers complex routing behavior, grounding constraints, high-stakes use cases, and cost implications, 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%, and every parameter is an alias for the same natural-language question, already documented in the schema. The tool description adds no meaningful parameter-level semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description immediately identifies the tool as a 'hallucination-resistant answer mode' and precisely states it 'EXTRACTS the answer using ONLY what the tool result contains.' It clearly distinguishes itself from the sibling ask_pipeworx by naming it and contrasting the grounded behavior, so the purpose is both specific and differentiated.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a when-not-to-use case by saying 'prefer ask_pipeworx for casual lookups' and explains the extra LLM call cost. This is exemplary usage guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral traits: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return status:'market_closed_or_inactive' and skip fan-out, wide-spread markets carry tradeability:'illiquid_wide_spread', and cancellation rules are parsed with ev_impact quantification. It also explains the fallback behavior for news (GDELT 429s with GNews backfill). These details go far beyond the annotations and are essential for safe agent use.

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 exceptionally long, but every sentence earns its place given the tool's complexity. It is structured with uppercase section labels (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) which improves navigability. It is front-loaded with the core purpose and usage, and the later sections provide critical operational details that would otherwise require separate documentation.

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

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

With no output schema, the description fully compensates by explaining the response shapes (result.market, result.analysis, result.evidence), the resolver contract (market_match_confidence, alternatives, suggestions), parent_event extraction, news fields, and safety statuses. It also covers the resolution-rule risk and blocking behavior for closed markets. This is a complete operational guide for an agent.

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

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

The input schema already provides full descriptions for all three parameters (market, depth, include_raw) with 100% coverage. The description adds some context for the 'market' parameter by showing slug/URL/question-text examples and explaining the resolver behavior, but it does not add significant semantics beyond the schema. Per the rubric, baseline 3 is appropriate when schema coverage is high.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools by detailing the resolve-classify-fan-out-return flow and providing concrete use cases like 'should I bet on X'. The scope is unambiguous and the tool's role relative to other Polymarket tools like polymarket_edges is evident.

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

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

The description gives explicit usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also provides extensive fan-out examples that clarify when specific data sources will be triggered. However, it does not explicitly mention when not to use the tool or name alternative sibling tools, which would earn a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial context: pulls from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. This goes well beyond the annotation baseline.

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

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

The description is dense but every sentence earns its place. It front-loads example queries and the core function, then adds data-source details and sorting behavior. It's appropriately sized for the tool's complexity and avoids fluff.

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

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

Despite having no output schema, the description covers return values (paired data + citation URIs), data sources, sorting, and edge cases (off-calendar fiscal years). It also explains why the tool is efficient, replacing 8–15 sequential lookups. This gives a complete context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description enriches both parameters significantly. It explains what each 'type' value does, gives concrete examples for 'values', and clarifies behavioral details like fiscal-year handling and result sorting, adding meaning beyond the schema definitions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It includes specific query examples and explicitly distinguishes itself from sequential single-pack lookups, showing a strong differentiation from sibling tools.

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

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

It provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent when to use this tool and implicitly when not to (for single-entity lookups). The description also explains which data sources are used for each entity type.

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, and destructiveHint=false, so the safety profile is known. The description adds behavioral context by listing the specific fields returned (make, model, year, body style, engine type, drivetrain, plant). It does not mention error handling or edge cases, but the annotations cover the main behavioral concerns.

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

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

The description is two concise sentences: the first states the action and result, the second gives an example and cross-references alternative tools. Every element earns its place with no redundant filler or restating of the tool name.

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

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

The tool is simple with one parameter, a full output schema exists, and the description provides a clear outcome (vehicle details) with specific fields and an example. It also situates the tool among siblings by naming where to go for recalls/ratings, making the context complete.

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

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

The input schema already describes the vin parameter as a 17-character VIN with an example, achieving 100% schema description coverage. The description repeats the example but does not add significant new semantic meaning beyond what the schema provides. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly identifies the tool's function with a specific verb and resource: 'Decode a VIN to get vehicle details.' It distinguishes itself from siblings by explicitly stating the return fields and directing users to get_recalls / get_safety_ratings for related but different data.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'For recalls/ratings use get_recalls / get_safety_ratings.' This exclusion clearly defines the scope of decode_vin, and the example input further clarifies the expected use case.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses account requirements, parallel tool routing, gap[]/contradictions[] behavior, hop semantics, citation resolution guarantees, semantic excerpting, and latency expectations. No contradiction with annotations exists; the detail is extensive.

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

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

The description is long but every sentence provides substantive guidance, including usage constraints, behavioral details, and performance expectations. It is not structured with bullets, but the length is proportionate to the tool's complexity.

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

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

For a complex tool with no output schema, the description thoroughly covers the input semantics, return format, error/gap behavior, authentication requirements, and caveats about news topics. It leaves little ambiguity for an agent to decide invocation.

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

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

Schema coverage is 100%, providing baseline 3. The description adds value by elaborating on depth levels (e.g., 'standard' re-angles gaps, 'thorough' chases best leads) and clarifies that 'question' can be broad/multi-part. This extends beyond the schema's brief enum 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 it performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, with a specific verb-resource pair. It distinguishes itself by explicitly noting it is 'NOT open-web search' and by contrasting with sibling ask_pipeworx for single lookups and news topics.

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

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

It explicitly states when to use this tool: 'Best for broad/multi-part questions over structured data' and gives concrete when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and for 'BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. This provides clear alternatives.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds meaningful behavioral context: it returns top-N tools, includes full input schemas with curated examples, and states the results are directly callable without a second schema lookup. This goes beyond the annotations and helps the agent understand the result format.

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

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

Three sentences with front-loaded purpose, a useful domain list, and clear return behavior. Every sentence earns its place, and the structure makes the tool easy to scan. No redundancy with the schema or annotations.

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

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

Despite having no output schema, the description fully explains what the tool returns (top-N tools with names, descriptions, schemas, examples) and why it should be used first. Given the large sibling toolset, this context is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and all properties are described, so the baseline is 3. The description reinforces that 'query' is a natural-language task description, which aligns with the schema, but it does not add new parameter-level detail beyond what the schema already provides. This meets the baseline without exceeding it.

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

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

The description opens with a specific verb+resource ('Find tools by describing the data or task') and enumerates a broad set of domains, making the tool's role clear. It distinguishes itself from the domain-specific siblings by positioning discover_tools as a meta-tool for finding other tools. This is far beyond a tautology.

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

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

The description explicitly states when to use the tool ('Use when you need to browse, search, look up, or discover what tools exist') and adds a strong directive ('Call this FIRST when you have many tools available'). It does not explicitly name alternatives or say when not to use it, but the usage context is unmistakable.

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 read-only/idempotent/non-destructive behavior. The description adds valuable caveats: USPTO PatentsView API is sunset and soft-fails, news uses a GDELT→GNews fallback, fundamentals are restricted to latest 10-K fields, and filings include pipeworx URIs. No contradiction with annotations.

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

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

The description is dense and information-rich, but the long list of example phrases and the heavy enumeration of return fields make it less scannable than ideal. Every sentence provides useful information, though the structure could be tightened.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does so thoroughly: names all major data sections, sources, ordering for fundamentals, fallback behavior, and the soft-fail for patents, giving an agent enough context to invoke the tool correctly.

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

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

Schema description coverage is 100% and already explains both parameters, including examples and the name-not-supported exclusion. The tool description restates this same guidance without adding new parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description explicitly states the tool creates a 'full cross-source profile of a US public company' in one parallel call and enumerates the returned components (CIK, filings, fundamentals, patents, news, LEI). It also distinguishes itself from sibling tools by noting that names are not supported and resolve_entity should be used instead.

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 strong usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies the exact input formats accepted (ticker or CIK) and directs users to resolve_entity when only a name is available, preventing misuse.

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 disclose destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds context about deleting 'previously stored' memories and calls out sensitive data, but otherwise aligns with annotations without introducing contradictions.

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

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

The description is two sentences: the first states the action precisely, the second provides usage guidance and sibling context. There is no fluff or redundancy, and key information is front-loaded.

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

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

For a simple one-parameter delete tool with clear annotations and schema, the description fully covers the relevant context: what it does, when to use it, and how it relates to sibling tools. No output schema is needed, and no major gaps exist.

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

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

Schema description coverage is 100% — the 'key' parameter is fully documented as 'Memory key to delete'. The description adds no additional parameter-level meaning, so the baseline score applies.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself from sibling tools by mentioning 'Pair with remember and recall', positioning it as the deletion counterpart.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references siblings, clarifying when to use this tool versus remember/recall.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). The description adds meaningful behavioral context beyond annotations, such as that it fetches a URL, extracts content, and emits standard llms.txt markdown, and that the output is a single text blob. It does not contradict the annotations and provides useful process details, though it omits potential edge cases like errors or rate limits.

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

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

The description is a single paragraph of four sentences, front-loaded with the primary purpose, followed by process details and use cases. It is slightly verbose due to the use-case list, but every sentence contributes meaning. It could be tightened, but it is well-structured and not padded.

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 (2 params, no output schema), the description is quite complete. It explains the output format ('single text blob ready to drop at site-root/llms.txt') and includes use cases. It does not cover failure modes or auth requirements, but given the annotations and schema, the description provides enough context for an agent to invoke it correctly.

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

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

The input schema fully documents both parameters with descriptions (100% coverage), so the baseline is 3. The description adds little beyond the schema—it implies the URL is the target site and mentions the output format, but does not explain max_links semantics. The schema already handles parameter meaning adequately.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It also explains the process (fetches page, extracts title/description/key links) and the output format. This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on auditing AI presence rather than generating the file.

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives the agent context on when to use the tool, though it does not explicitly mention when not to use it or name alternative tools, falling short of the top score.

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, and non-destructive behavior. The description adds useful context: data source (owner filings), returned fields (components, summary, crash/fire flags, injuries/deaths, filing date), and required input pattern. No contradiction with annotations.

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

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

Two sentences: the first states the purpose and key differentiator; the second gives usage examples and return fields. Every sentence earns its place with no filler.

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

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

No output schema exists, so the description appropriately lists return fields (components, summary, crash/fire flags, injuries/deaths, filing date). It also covers purpose, inputs, and example queries. Minor gap: no detail on result structure or pagination, but acceptable for a low-complexity 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 covers all three parameters with descriptions and examples (100% coverage). The description only repeats 'Pass make + model + model_year' without adding further parameter semantics, so it stays at baseline.

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

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

The description clearly states the resource ('owner-filed NHTSA complaints') and differentiates from official recalls, which is a relevant sibling (get_recalls). The phrasing 'real-world problems drivers reported' adds precise 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 example queries and contrasts with recalls ('vs official recalls'), but does not name the alternative tool (get_recalls) nor state when not to use the tool. The usage intent is clear, but exclusion guidance is implicit rather than explicit.

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 read-only, idempotent, and non-destructive behavior. The description adds that it returns make names and IDs, and implies filtering by year, which provides useful behavioral context beyond the annotations. The only issue is the ambiguous year reference given the empty schema.

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

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

The description is three short sentences, front-loaded with the primary action, followed by return type and an example. Every sentence adds value, and there is no wasted prose.

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 core function and return content are covered, and annotations handle the safety profile. However, the discrepancy between the described year input and the empty schema leaves a significant gap, making the description incomplete for a tool that appears to require a model year argument.

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

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

The input schema has zero properties, yet the description mentions a 'model year' and provides the example 'year 2023' without specifying a parameter name, type, or format. This introduces confusion rather than clarifying parameter semantics. With no schema parameters, the description should either confirm no parameters or properly document the year input.

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 all vehicle brands (makes) for a model year. It includes a specific example and distinguishes itself from sibling tools like get_models by focusing on 'makes' rather than other 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 context 'for a model year' implies when to use it: when a list of makes for a given year is needed. It does not explicitly mention alternatives or exclusions, but the usage context is clear enough for a simple tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the useful detail that the response contains model names and IDs, but it does not disclose any additional behavioral traits beyond what annotations or schema imply. No contradiction exists.

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

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

The description is concise (two short sentences plus an example), front-loads the core action, and avoids redundant filler. Every sentence contributes to understanding the tool's purpose and usage.

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 small parameter count, rich annotations, and existence of an output schema, the description is adequately complete. It conveys the essential inputs, expected output type, and a usage example. It doesn't need to detail return values since the output schema covers that.

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

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

Schema description coverage is 100%, so the schema already describes both 'make' and 'year' with examples. The description's example (Toyota, 2023) adds minimal extra meaning beyond the schema, which is sufficient for a baseline score.

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

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

The description states exactly what the tool does: 'Get all vehicle models for a make and year' and specifies the output ('model names and IDs'). This distinguishes it from sibling tools like get_makes by focusing on models rather than makes, and the verb+resource structure is specific and clear.

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

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

The description clearly implies the usage context: this tool is for retrieving models when the user supplies a make and year. It provides a concrete example (Toyota, 2023) that reinforces the expected inputs. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description goes beyond annotations by specifying the returned data fields (component, summary, safety consequence, remedy, campaign number, report date), which adds useful context about the tool's output.

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 (three sentences) and front-loads the main purpose. The all-caps emphasis on 'PREFER OVER WEB SEARCH' and 'RECALLS' is intentional but a bit noisy; every sentence contributes value, though it could be slightly more polished.

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 three well-documented parameters and no output schema, the description covers what the tool does, when to use it, what it returns, and how to invoke it. It is fully self-contained and leaves no significant gaps for an agent to guess.

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 each parameter having its own description and examples. The description's 'Pass make + model + model_year' adds no new semantic meaning beyond what the schema already provides, so a 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?

States clearly that it gets official NHTSA safety recalls for a vehicle, using the specific verb 'Get' and a well-defined resource. It is easily distinguished from sibling tools like get_complaints or decode_vin by focusing solely on recalls.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives concrete example queries, which tells the agent when to use this tool. However, it does not mention any sibling tool alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns overall/frontal/side/rollover star ratings and uses NHTSA NCAP data, which is useful context about the return content. However, it does not disclose potential limitations (e.g., missing ratings for some vehicles) or additional behavioral details beyond what annotations cover.

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

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

The description is two sentences long, front-loaded with the core purpose, and every word earns its place. It includes a clear scalar phrase and two example queries, with no filler.

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

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

The description covers the tool's return type (star ratings across multiple dimensions), the data source (NHTSA NCAP), and required parameters. Since there is no output schema, mentioning the rating categories provides sufficient context for a simple lookup tool. It does not address error handling or empty results, but that is not essential for this straightforward tool.

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

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

Schema description coverage is 100% and each parameter is documented with examples. The description merely restates 'Pass make + model + model_year' without adding new meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Get') and identifies a distinct resource (NHTSA 5-Star Safety Ratings / NCAP crash-test results) with clear scope (overall, frontal, side, rollover). It also provides example queries, distinguishing it from sibling tools like get_recalls or get_complaints.

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

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

The description explicitly states when to use the tool ('Use for “crash test rating for a 2021 Honda Civic”, “how safe is X”') and what parameters to pass ('Pass make + model + model_year'). It does not mention alternatives or exclusions, but the positive guidance is concrete 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description adds value by listing the exact return fields and the active-only default. This gives the agent a clear picture of the response shape without needing an output schema.

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

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

Two sentences, no redundant phrasing. The first sentence states the action and return fields; the second sentence gives practical guidance, earning its place.

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

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

Low complexity tool with one optional parameter and no output schema. The description adequately specifies return fields and typical use cases, making it self-contained for invocation.

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

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

Schema covers 100% of the single parameter with its own description. The tool description does not add additional semantics beyond the schema's include_inactive explanation, so 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?

Clearly states the tool lists the caller's active subscriptions with a specific verb and resource. It doesn't explicitly distinguish from sibling tools, but the resource scope is unambiguous and distinct from subscribe/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?

Provides explicit usage context: review before adding more subscriptions and find an id to cancel. No exclusions or alternatives mentioned, but the context is clear for when to invoke this tool.

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

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

The description discloses non-obvious behaviors: anonymous filing returns a claim_token, rate limit of 5 per day, no quota impact, daily digest review, and roadmap influence. These go well beyond the minimal annotations (all false hints) and give the agent a clear model of side effects.

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

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

Though longer than average, every sentence delivers distinct, necessary information: purpose, use cases, exclusion criteria, token workflow, rate limits, and roadmap impact. It is logically ordered and front-loaded with the core purpose.

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

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

For a feedback tool with no output schema, the description fully covers inputs, the response token, follow-up workflow, limits, and the distinction between Pipeworx tools and third-party tools. Nothing important is left unspecified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage semantics beyond the schema: how to use claim_token as a standalone lookup ('with no other arguments'), the exact call pattern, and clarifies that context is optional. This extra value justifies a 4.

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

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

The description opens with a strong verb phrase, 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the tool's purpose. It differentiates from all sibling research/query tools by focusing on feedback to the Pipeworx team itself.

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

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

Explicitly lists when to use (bug, feature/data_gap, praise) and when NOT to use (feedback for other MCP servers), with a concrete test ('Pipeworx tool names are the ones this connection lists'). Also explains how to use claim_token for later follow-up, giving complete guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: data source (CF analytics-engine), no PII, cache behavior (5min-1h varying by window), and the self-aggregating nature of the signal. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, uses a structured list for use cases, and every sentence adds value—data provenance, privacy, cache timing. No fluff or repetition.

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

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

Despite having no output schema, the description explains exactly what is returned (top tools, top packs, total call volume). It covers operational details (cache, window options), privacy guarantees (no PII), and data source, making it complete for a single-parameter read-only tool.

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

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

The schema fully documents the 'window' parameter with an enum and a description explaining the tradeoff between short and long windows. The tool description reinforces this but does not add new semantic information beyond what the schema already provides. Baseline of 3 is appropriate given 100% schema coverage.

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

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

The description clearly states a specific action ('Returns') and resource ('top tools, top packs, and total call volume') over a recent window. It distinguishes itself from sibling tools by focusing on aggregate agent usage trends rather than individual queries or tool discovery.

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

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

The description explicitly lists three concrete use cases with 'Useful for', giving clear context on when to invoke the tool. It does not explicitly mention when not to use it or name alternatives, but the use cases are sufficient to guide selection.

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

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

Beyond the read-only/idempotent annotations, the description discloses crucial behaviors: the partition placeholder filter (>20% returns null), the fill-check semantics (realizable_edge_pp ≤ 0 means do not trade), and the `skipped_low_similarity` count. This is rich, non-obvious context that materially affects whether the agent acts on a result.

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

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

The description is long, but every section (semantic anchor, partition filter, response, fill check) contributes non-redundant operational details. It is front-loaded with the core purpose and call patterns, though a few points like the partition-check explanation are repeated across modes.

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 still fully specifies the return shape (`opportunities[]`, `partition_check`, fill-check fields), the top-200 market scope, thresholds, and disqualification rules. It is complete enough to invoke correctly without external documentation.

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

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

The input schema already documents both parameters well (100% coverage), and the description adds meaningful extras: the no-args default, accepted event URLs, and the behavioral consequences of each mode (walks child markets, flattens union for topic). This goes beyond the schema but does not need to be a 5 since the schema already carries substantial meaning.

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

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

The opening sentence names the specific verb ('Find'), resource ('arbitrage opportunities on Polymarket'), and method ('monotonicity violations + partition-sum checks'), clearly distinguishing it from sibling edge/fill-risk tools. It also immediately scopes the tool by listing the three invocation modes.

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

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

The description explicitly tells the agent when to call with no args (`trending_scan`), when to pass `event` vs `topic`, and recommends `event` for a specific market. It also names an alternative tool (`polymarket_fill_risk`) for custom sizing, giving clear decision guidance.

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

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

Discloses substantial non-obvious behavior: slippage is subtracted from raw edge, Kelly is capped at 0.25, a 24h-move warning is emitted, Fed bets are excluded due to unreliable signals, and results are cached 1h keyed on knobs. The readOnly/idempotent annotations are reinforced rather than contradicted.

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 organized into flagged segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and contains densely packed facts like per-sport α values and gate relaxations. Each sentence contributes unique information, though the length might be heavy for an agent to parse quickly.

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 specifies the response top-level fields (by_segment, fed_candidates, _diagnostics), lists opportunity fields, and explains why empty segments occur via funnel counters. It covers caching, knob interactions, and edge-case filters, making it fully actionable.

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

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

The schema covers all 9 parameters, and the description adds operational meaning: it explains min_liquidity and max_spread_pp as 'tradeable-edge' filters, and min_partition_leg_kelly applies to per-leg Kelly inside partitions because parent-level kelly_fraction_half is always 0. This goes beyond the schema's individual 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?

Opens with a specific verb-object statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly differentiates from sibling tools by emphasizing models and disagreement; further detail on model families and response segments removes ambiguity.

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

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

Explicitly states the intended use case: 'Built for "what should I bet on today"' and the agent discovering opportunities 'without paging hundreds of markets.' It does not name sibling tools or enumerate exclusions, so the guidance is contextual but not comparative.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, but the description adds rich behavioral context: snapshot gaps due to cache-miss behavior, 60-day TTL limits, daily-close basis for decay, and semantics of expired opportunities. 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 Args, RESPONSE, and LIMITS sections. Every sentence provides operational detail, though it is somewhat verbose for a two-parameter tool. It earns a high score for density and organization.

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 thoroughly documents the response shape: tracked[], expired[], snapshot_dates[], and their interpretation. It also covers data source limitations (TTL, cache-miss gaps) and computation basis, making it complete for an analytics 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 for both parameters is 100%, including defaults and clamps, so the baseline is 3. The description restates the defaults and adds 'snapshot family' context, but does not add meaning beyond what the schema already provides.

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

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

The description clearly states the tool's function: edge persistence and decay telemetry derived from daily polymarket_edges snapshots, answering whether an edge is new or shrinking. It distinguishes itself from sibling polymarket_edges by focusing on historical persistence and decay rather than current edge values.

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

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

The description gives clear context for when to use the tool (evaluating edge age and decay, explaining that fresh and old wide edges are different trades) but does not explicitly name alternative tools or state when not to use it. The sibling list implies alternatives, but no direct exclusion is present.

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, but the description adds behavioral details: 'walks the ladder', returns 'top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict', and warns about 'thin_legs' and 'forced_directional_risk'. No contradiction with annotations.

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

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

The description is long but structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded with the core purpose. Every sentence adds necessary detail for the two mode types.

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 two modes and no output schema, the description thoroughly lists expected return values, prerequisites, and risk warnings. It covers what happens in both single-market and basket modes, including failure conditions ('cannot_fill' verdict, 'forced_directional_risk').

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

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

Schema coverage is 100% but the description enriches parameter meaning: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. This goes beyond the schema's field descriptions.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth'), and clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by positioning this as a pre-trade 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 when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains the failure mode ('partial basket fills convert an arb into an unhedged directional position'). It also clarifies the required modes (market vs event).

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavioral detail: it explains the compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0, or with both venues >5 legs), temporal_alignment effect on spread validity, and skipped_cross_type/subtype counters that expose why leg-pair comparisons were dropped. This honestly discloses limitations and edge cases without contradicting annotations.

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

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

The description is long (~250 words) but well-structured with clear labels like TWO MODES, RESPONSE, and SAFETY FIELDS. It front-loads the primary purpose and then expands into necessary detail. Every sentence provides relevant information, though the safety-fields section is verbose. The density is justified for a tool with complex matching logic, so it earns a 4 rather than a 3.

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 explains the return structure: 'each venue's leg-by-leg prices (raw probability 0-1) plus matched spread[].top_spreads_pp (Kalshi − Polymarket)'. It also covers the compatibility_warning and temporal_alignment fields thoroughly, and explicitly warns about the rarity of tradeable spreads. For a read-only analytic tool, this is comprehensive and leaves little ambiguity about what the agent will receive.

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

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

The schema already covers 100% of parameter descriptions, including the topic enumeration and override semantics for kalshi_event_ticker and polymarket_event_slug. The description adds value by framing the two modes ('TWO MODES') and explaining when to use topic vs explicit parameters, plus the auto-fetch behavior. While the schema already notes overrides, the description clarifies the overall mode selection logic, adding 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's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and even notes when the spread is or isn't a real signal. The two modes (topic shortcuts vs explicit ticker/slug) further clarify scope.

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

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

The description explains the two modes and provides guidance on when the spread is meaningful ('when the bet shapes are equivalent that delta is a real signal') and when not ('when they aren't the tool says so'). It warns that 'most pre-mapped topics return compatibility_warning today' and 'pre-mapped ≠ tradeable', which helps set expectations. However, it does not explicitly name alternative tools for single-venue analysis, so usage guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds valuable context about scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving vs. listing keys, which is not evident from annotations alone.

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

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

The description is three sentences, front-loaded with the primary action, then examples, scoping, and sibling pairing. Every sentence adds value without redundancy or fluff.

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

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

For a simple one-optional-parameter tool with no output schema, the description fully explains both usage modes, the storage scope, and its relationship to remember and forget. No critical information is missing.

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

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

Schema covers 100% of the parameter description, including 'omit to list all keys'. The description repeats this information but adds no new semantic detail about the parameter itself beyond what the schema provides, so it meets the baseline.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys when the key is omitted. It names the paired tools (remember, forget) and gives concrete examples like 'user's target ticker' and 'address', making its purpose unmistakable.

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

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

Explicit guidance is provided: 'Use to look up context the agent stored earlier' and examples of when to apply. It also mentions pairing with remember and forget, clearly distinguishing from sibling tools.

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

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

Annotation Contradiction: the annotations declare readOnlyHint=true, but the description describes a mutating side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the read-only hint. Per rubric, any contradiction yields a score of 1.

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, all information-dense and non-redundant. It front-loads the main purpose and then details filters, mark_read, and alternative access. Slightly paragraph-like, but each sentence earns its place; a slightly tighter structure with bullet points 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?

No output schema exists, but the description covers the key return fields (source, citation_uri, raw payload), filter options, mark_read behavior, and an alternative HTTP endpoint. It omits nothing critical beyond what the schema already documents. The annotation contradiction tempers completeness slightly, but the description itself is quite 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?

Input schema covers all 5 parameters with descriptions (100% coverage), so baseline is 3. The description adds extra semantic value by giving a concrete type example ('sec_8k'), noting type and since can be combined ('and/or'), and explaining the effect of mark_read:true on subsequent calls.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly identifies the tool's output (recent alerts with source, citation_uri, raw payload) and distinguishes it from sibling tools by focusing on the alerts feed rather than changes or 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?

The description states you can filter by type and since, and explicitly says polling works fine and the same feed is available via HTTP for scripts/dashboards, which implies the intended use case vs. external access. It doesn't explicitly name sibling tools to avoid, but provides clear contextual usage signals.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses fan-out to SEC EDGAR, GDELT→GNews fallback with rate-limit/5xx specifics, USPTO soft-fail due to API sunset, and the return structure. This is rich behavioral context annotations cannot convey.

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

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

The description is dense but front-loaded with user-phrase examples that quickly signal intent. While longer than minimal, every sentence covers a distinct aspect (sources, fallback, params, return format, alternative), making it efficient for a multi-source tool.

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

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

There is no output schema, but the description explains the return value shape (changes[], total_changes, citation URIs). It covers data sources, error/fallback behavior, parameter formats, and when to use an alternative, providing complete context for a tool that aggregates multiple APIs.

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 for the 'since' parameter with examples and a typical-use recommendation ('30d' or '1m'), and reaffirms ticker/CIK formats. This extra guidance pushes it above baseline.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with natural language examples. It explicitly distinguishes itself from entity_profile by naming that alternative for static profiles, making the purpose unmistakable.

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

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

The description gives explicit usage context: 'Use entity_profile instead when you want the static profile' and recommends 'since' values like '30d' or '1m' for typical monitoring. This tells the agent when to choose this tool versus a sibling.

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

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

Adds rich context beyond annotations: scoping by identifier, persistent memory for authenticated users vs 24-hour retention for anonymous sessions, and the key-value storage model. Annotations only indicate idempotent and non-destructive, so the description fills important behavioral gaps.

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

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

Three sentences: purpose, when-to-use, and storage/retention behavior. Each sentence earns its place, the main action is front-loaded, and there is no redundancy or fluff.

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

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

For a simple two-parameter tool with no output schema, the description covers all essential aspects: purpose, usage triggers, persistence semantics, and relationship with sibling tools. It is fully sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with already descriptive parameter explanations (key examples, value as any text). The description adds the key-value pair context but does not substantially extend understanding beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description opens with a clear verb ('Save') and defines the resource as data for later reuse, with concrete examples (ticker, address, preference). It also distinguishes this from sibling tools recall and forget by explaining the memory lifecycle.

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

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

Explicitly states when to use ('Use when you discover something worth carrying forward') and provides alternatives by pairing with recall for retrieval and forget for deletion, making the selection 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 provide readOnlyHint, idempotentHint, and openWorldHint, so the description doesn't need to restate safety. It adds substantial behavioral context: internal cascading through multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, and the explicit handling of unresolved identifiers under an `unresolved` field. This clarifies edge-case behavior beyond what annotations convey.

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

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

The description is front-loaded with examples and a clear purpose statement. It is relatively long but structured: examples, supported types with detail, graceful degradation note, and efficiency statement. Every sentence earns its place, though some redundancy exists (e.g., repeating supported types). Still, it remains efficient for the amount of information conveyed.

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, graceful degradation, no output schema), the description covers the key behavioral aspects: what identifiers are returned, how unresolved items are handled, and fallback behavior. It does not describe the exact output structure, but the mention of source-labels and an `unresolved` field provides sufficient mental model. One could argue an example response would improve completeness, but as-is it is adequate.

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

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

Schema coverage is 100% with descriptions for both parameters. The description goes further by detailing the 'company' type's cross-source identity spine, explaining that ISIN input resolves via GLEIF, and clarifying that value accepts ticker, CIK, ISIN, or company name—adding nuance beyond the schema's brief examples. This additional context helps the agent form correct queries.

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

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

The description opens with clear example queries ('What's the ticker for…' etc.) and explicitly states the tool resolves a name to canonical identifiers. It distinguishes itself from siblings by instructing 'Use FIRST whenever you have a name but need an ID,' which directly contrasts with tools like entity_profile that act on already-resolved IDs.

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 explicit usage guidance ('Use FIRST whenever you have a name but need an ID') and lists concrete query patterns. It mentions that the tool 'replaces 2-3 manual lookups', implying efficiency. However, it does not explicitly state when NOT to use (e.g., if the ID is already known) or name alternative tools for comparison, though the sibling context suggests entity_profile is a natural follow-up.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds valuable behavioral detail: it internally calls ai_visibility_check per entity, ranks by score, and returns specific metrics. This goes beyond what annotations provide and is consistent with them.

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 core action front-loaded in the first sentence and the second covering use case and output. Every word earns its place; no redundancy or filler.

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

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

Given 4 parameters, no enums, and no output schema, the description provides enough context: purpose, method, output structure, and a typical query example. Minor gap is not explaining what 'score' or 'confidence' represent conceptually, but the overall tool behavior is well-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?

Schema description coverage is 100%, with each parameter already fully described (e.g., 'entities' with 'First entry treated as the subject', 'models' with supported values, 'context' for disambiguation). The tool description does not add extra parameter semantics beyond restating that entities are probed and ranked, so baseline 3 applies.

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

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

The description uses the specific verb 'Compare' with a clear resource ('AI visibility across multiple entities') and explicitly states the method (probes with ai_visibility_check, ranks by score) and output (ranked list with score/confidence/signal density). It distinguishes itself from the sibling ai_visibility_check by framing itself as a side-by-side multi-entity 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 a concrete use case ('competitive AI-marketing audits') and an example question, which clearly implies when to use it. It does not explicitly mention alternatives or exclusions, but the context of probing 'your brand + N competitors' makes it obvious this is the multi-entity version of ai_visibility_check.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses composite behavior, fan-out to two services, graceful degradation on partial failures, timing (5-30s for bundlephobia), and the sources_failed field. This goes well beyond the structured hints.

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

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

The description is packed with essential information, front-loaded with the core purpose. Though multi-sentence, every sentence adds value: sources of data, use cases, return fields, ecosystem scope, and degradation behavior. No redundant content.

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

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

With no output schema, the description fully explains the return value structure (summary block fields, per-advisory detail, links, alternative versions). It also covers failure modes and ecosystem limitations, making it self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100% with clear descriptions for 'package' and 'version'. The tool description does not add additional parameter-specific detail, but the schema already carries the meaning. 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 a specific verb+resource: scanning an npm package dependency for a 'should I add this' check. It distinguishes from siblings by explicitly scoping to npm in v1 and directing other ecosystems to deps.dev:version.

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

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

Provides explicit when-to-use guidance ('Use whenever an agent asks...') and exclusion criteria (other ecosystems go to deps.dev:version). This is stronger than most alternatives.

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

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

Beyond the read-only and idempotent annotations, the description discloses critical behavioral details: character-offset outputs, similarity scores, BGE-base-en embeddings, 500-char overlapping windows, a 200K character cap, and that longer inputs are truncated and flagged. This adds substantial context for safe and accurate invocation.

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: definition, use case, integration, then technical details. Every sentence adds value, though it is longer than strictly necessary. Front-loaded core purpose, with implementation details at the end, making it easy for an agent to parse.

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 lacking an output schema, the description fully specifies the return format (passages with character offsets and similarity scores) and behavior (overlapping windows, truncation). It is complete for a search tool with this complexity, covering inputs, outputs, limitations, and use context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by providing concrete examples for the query ('supply-chain risk', 'fiscal year 2024 revenue'), clarifying that 'text' is the previously fetched record (e.g., SEC 10-K body), and explaining limit's default and range. This goes beyond the schema's bare 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 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes the tool from siblings by explicitly naming ask_pipeworx_grounded as a companion and contrasting its use case (searching within already-fetched text vs. other operations).

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 when the record is too big to cram into the prompt' and provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This tells the agent exactly when to choose this tool and how it integrates with 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?

The description goes far beyond the raw annotations by disclosing important behavioral traits such as the OAuth requirement, phone verification, SMS daily cap, webhook signing secret, and auto-disable after 10 consecutive failing runs. It also notes that the subscription ID is returned and that webhook signing secret is shown only once. These details align with annotations (readOnlyHint=false, idempotentHint=true) without contradiction.

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

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

The description is long but every sentence carries essential information: core action, requirement, type examples, delivery channels, and constraints. It is front-loaded with the purpose and returns value, then systematically details prerequisites and optional channels. No filler or redundant phrasing exists despite the complexity.

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

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

Given the tool's complexity (nested objects, multiple subscription types, delivery channels) and that no output schema exists, the description covers what the agent needs: the returned subscription ID, the webhook signing secret, and the disables on repeated failures. It also covers account prerequisites. The schema supplies additional type details, so the description is contextually complete for selection and invocation.

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

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

The schema already has 100% coverage, with detailed descriptions for every parameter and nested examples, so the baseline is 3. The tool description adds some examples and context (e.g., 'sec_8k' item codes), but it actually covers fewer types than the schema does (only 3 of 5), so it does not substantially raise the 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 opens with a clear, specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It immediately identifies the tool's distinct function among siblings like list_subscriptions and unsubscribe, and adds that it returns the subscription ID. The supported types and delivery channels are enumerated, leaving no ambiguity about the tool's purpose.

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

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

The description states when the tool is appropriate, e.g., 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)' and 'Delivery channels: feed (always on…)', implying it's for users who need to persist and receive alerts. It provides clear context but does not explicitly mention alternatives (e.g., 'for listing existing subscriptions use list_subscriptions'), so it stops short of an explicit when/not comparison.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond those hints by disclosing that results are drawn from a 'live catalog of thousands of tools' and that each example includes 'the exact tool + argument shape' that answers it. This is useful behavioral detail without contradicting annotations.

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

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

The description is longer than ideal but front-loaded with example queries and organized with dash-separated category lists. Every sentence carries functional value: purpose, return contents, parameter behavior, and onboarding usage. It is comprehensive without being bloated, though tighter phrasing would improve it.

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

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

For a tool with 1 optional parameter, no output schema, and clear annotations, the description is fully complete. It explains what the tool returns (category-bucketed questions with tool+argument mappings), how to call it (no args or with topic), when to use it (first when onboarding), and what it helps the agent learn (meta-tools). No important context is missing.

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

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

The input schema already provides 100% coverage of the single parameter (topic), including the allowed focus areas and the behavior when omitted. The description repeats these examples ('finance', 'pharma', 'betting') and the omit behavior, adding no new semantic information beyond the schema. This meets the baseline for high schema coverage.

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

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

The description uses a specific verb ('Returns category-bucketed example questions') and clearly identifies the resource (Pipeworx tool catalog) and the onboarding scope. It distinguishes itself from sibling tools by positioning itself as 'the onboarding entry point' and explicitly saying to 'Use this FIRST' when unsure what Pipeworx can do.

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

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

The description gives clear when-to-use guidance ('when you do not yet know what Pipeworx can do for you') and explains the optional topic parameter with example focus areas. It does not explicitly name alternatives such as discover_tools or ask_pipeworx as 'use this instead,' but the 'FIRST' directive and onboarding framing provide strong contextual placement.

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

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

Beyond the annotations, the description discloses important behavior: ownership restriction and that the row is deactivated (not deleted), preserving historical events. This adds meaningful context not covered by annotations, with no contradictions.

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

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

Two sentences, front-loaded with the action, and every sentence provides value. No filler or redundancy.

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

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

For a simple tool with one parameter, no output schema, and useful annotations, the description covers the key aspects: what it does, ownership constraints, side effects (deactivation), and how to keep history. No major gaps.

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

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

The schema fully covers the single parameter 'id' (description: 'Subscription id (uuid) returned by subscribe'). The description merely says 'by id,' adding no extra semantics. With 100% schema coverage, a baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Cancel a subscription by id.' It uses a specific verb ('cancel') and resource ('subscription'), and the title 'Unsubscribe from Alerts' reinforces this. It distinguishes from sibling tools like subscribe (create) and list_subscriptions (list).

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

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

The description provides explicit when-to-use and when-not-to-use guidance: ownership is enforced, so you can only cancel your own subscriptions. It also points to an alternative for historical events via recent_alerts, making the intended use clear.

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

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

Annotations already declare safe/non-destructive behavior; the description adds critical nuance about could_not_verify vs unsupported, including that could_not_verify means the check did not happen and must not be used as evidence. This is high-value behavioral context beyond the structured annotations.

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

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

Although lengthy, the description is front-loaded with trigger phrases and follows a logical flow: trigger examples, use case, pipeline explanation, return values, and caller caveats. Every sentence earns its place; the length is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining outputs. It lists the verdict types (confirmed, refuted, etc.), mentions citations via pipeworx://, and explains the error semantics. It also notes the structured/grounded pipeline, giving the agent enough context to invoke and interpret results correctly.

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

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

Schema coverage is 100% for both params, so baseline is 3. The description adds value by clarifying tolerance_pct default overrides and its role in hallucination detection, and gives concrete claim examples that complement 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 opens with a clear, specific verb-resource pairing: 'natural-language claim verification against authoritative sources.' It also distinguishes the tool from siblings by noting it replaces 4–6 sequential calls and routes company-financial claims through a dedicated SEC EDGAR path.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the decision fork between company-financial and all other claims. This is strong when-to-use guidance, though it does not name specific sibling tools as alternatives, the description implies the alternative of sequential tool calls.

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