Mapbox

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so safety is covered. The description adds valuable behavioral details beyond annotations: the default model (Workers AI Llama-3.3-70b) is free, probing Anthropic costs money via BYO key, and the return structure is disclosed. This gives a clear picture of what the tool does and its side effects (cost).

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 core action and output, and every sentence contributes essential information: purpose, default/cost behavior, return format, and use cases. 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?

Given there is no output schema, the description appropriately details the return structure (per-model score/confidence/signals/raw_response + combined view) and gives concrete examples of when to use it. It does not define what 'confidence' or 'signals' mean, but the overall context is sufficient for an agent to decide to call the tool. Minor gap: it doesn't clarify how scores are computed or how to interpret them.

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 reinforces the _apiKey parameter's role (BYO, pay direct) and explains the context parameter's purpose (disambiguation), but these are largely duplicative of the schema descriptions. The additional cost note is a slight enhancement, but not enough to raise the 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 opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx (which likely answers questions) and scan_competitor_ai_presence (which may focus on competitors). It also gives concrete output details (score, confidence, signals, raw_response) and use cases.

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 it is useful ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides operational context (default model is free, Anthropic requires BYO key). However, it does not explicitly name alternatives or state when not to use it relative to siblings like scan_competitor_ai_presence, leaving some ambiguity.

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 the description adds valuable behavioral context: routes to 5,529 tools across 1,455 verified sources, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. No contradiction with annotations.

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

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

The description is long but well-structured, front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'), followed by capabilities, usage triggers, examples, and alternatives. It is slightly verbose with repetitive phrasing, but every section earns its place given the tool's complexity.

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

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

The tool is complex (routing across thousands of sources) with no output schema, yet the description explains what it handles, how to use it, what it returns (structured answer with citations), and how it differs from alternatives. It provides enough context for an agent to decide and invoke correctly without additional documentation.

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

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

The schema has 100% coverage with clear descriptions and examples for the 'question' parameter and its aliases. The description does not add parameter-specific semantics, but the schema already documents parameter meaning thoroughly, 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 clearly states the tool's purpose as a default entry point for factual questions, using specific verbs like 'routes the question' and listing concrete domains (SEC filings, FDA data, FRED/BLS, patents, etc.). It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, making the unique scope 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?

Explicitly states when to prefer this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), provides trigger phrases ('what is', 'look up', 'find', etc.), and gives clear step-up guidance (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). This is exceptional guidance for an agent deciding between 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?

Beyond the annotations, the description discloses that candidate routing improvements are enabled live when under test, that no candidate is currently active (with a specific retirement date), and that it 'falls back to nothing' — emphasizing it is a full working router. This gives essential behavioral context about its experimental, time-varying nature.

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

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

The description is informative but somewhat verbose, including specific details such as the 5,529 tool count and the retirement date. It is well-structured and front-loaded with the beta status, but could be tightened without losing essential 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 complex router with no output schema, the description sufficiently covers current state, equivalence to ask_pipeworx, usage, and fallback behavior. It references ask_pipeworx for the exact response shape, which is acceptable given the sibling context and the rich annotations.

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

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

The description does not discuss parameters, but the input schema provides descriptions for all 6 parameters, including the main 'question' field and its aliases. With 100% schema coverage, the schema carries the burden, 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?

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It explicitly distinguishes it from the stable ask_pipeworx and positions it as the experimental edge, making the purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. This clearly tells the agent when to choose this tool over 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?

The description discloses critical behaviors beyond annotations: the refusal mechanisms with specific refusal reasons, the return format including evidence and confidence, and the additional LLM call requirement. It also clarifies that the tool will not answer if data doesn't directly contain the answer, which is a crucial non-obvious behavior.

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

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

The description is longer than average but every sentence earns its place: it defines the core mechanism, return format, refusal reasons, use cases, and trade-off. It is well-structured and front-loaded with the most important information.

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

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

Despite having no output schema, the description fully explains what is returned on success and failure, including the structure of refusals. Combined with the detailed process description and usage guidance, the description is complete for safe and correct 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 input schema already provides 100% coverage for the single required parameter 'question' and its aliases. The description adds no additional semantic detail about parameters, so the baseline of 3 is appropriate—the schema does the heavy lifting.

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: a hallucination-resistant answer mode that extracts answers using only tool results, returning evidence, confidence, and source. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded output and explicit refusal behavior, making its role in the toolset 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?

Explicitly specifies when to use this tool (for answers that will be quoted, cited, or acted on, and when the agent must not invent facts) and when not to (casual lookups, for which ask_pipeworx is preferred). It also mentions the extra LLM call cost as a trade-off, guiding cost-conscious selection.

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

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

The description goes far beyond the annotations (which only indicate read-only, open-world, idempotent, non-destructive). It meticulously discloses behavioral traits: the resolver contract with confidence levels and alternatives, the low_confidence_match short-circuit that suppresses analysis, the market_closed_or_inactive path, wide-spread illiquidity handling, news fallback behavior with retry_after_sec, and resolution-rule risk parsing (refund_50_50, etc.). This is exemplary transparency about what happens under various conditions, adding substantial context the annotations cannot provide.

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

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

The description is long, but every section earns its place: purpose, classifiers, fan-out examples, response shapes, resolver contract, parent event, news fields, safety, and resolution-rule risk. It is front-loaded with the core purpose, then systematically detailed. It uses headings and line breaks for readability, and the density is appropriate for the tool's complexity. A slight deduction because it could be tightened without losing value, but it is well organized.

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

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

Given the tool has no output schema, the description carries the full burden of explaining return shapes and edge cases. It covers result.market, result.analysis, result.evidence, result.market_match_confidence, parent_event, news fallback fields, and both blocking statuses (low_confidence_match and market_closed_or_inactive). It also addresses wide-spread markets and cancellation-rule risk. Very few tools provide this level of contextual completeness, making it effectively self-contained.

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

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

Schema coverage is 100%, with each parameter already described. The tool description adds extra meaning by giving concrete examples of the 'market' param (slug, URL, question text) and clarifying the intent of 'include_raw' with byte-size ranges and specific use cases. It also explains that 'depth' controls the fan-out scale, though the schema already covers this. This enrichment plus high schema coverage 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 specific action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies the resource (Polymarket bet), the verb (research), and the scope (one call, data pulling). It also distinguishes itself from sibling tools by framing the use case ('should I bet on X') and listing concrete fan-out examples, 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 guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides examples of when to apply specific fan-outs (BTC, Fed, Hormuz, etc.) and safety rules like checking cancellation risk before sizing sports bets. However, it does not explicitly state when *not* to use this tool or name alternative tools for different cases, so it falls just short of a 5.

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

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

With readOnlyHint and idempotentHint annotations already covering safety, the description adds substantial behavioral context: parallel execution, data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of pipeworx:// citation URIs. No contradictions with annotations.

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

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

The description is dense with examples, rules, and type-specific details, front-loaded with user query examples. While longer than average, every sentence adds functional information for a complex tool, making it efficient rather than verbose.

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

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

For a tool with two entity types, multiple data sources, and no output schema, the description covers the main behaviors: input constraints, data origins, sorting logic, and return elements. Minor omissions like exact response format are offset by the mention of paired data and citation URIs.

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 both parameters with 100% coverage, and the description enriches them by explaining type-specific data retrievals ('company' pulls 10-K financials, 'drug' pulls FAERS/trials) and giving concrete value examples. This exceeds the schema's bare details.

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

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

The description clearly defines the tool as a side-by-side comparison of 2-5 companies or drugs in a single parallel call, with specific verb ('compare') and resource scope. It distinguishes from sequential single-pack lookups and sibling tools like entity_profile by emphasizing the parallel comparison functionality.

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 guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists trigger phrases ('X vs Y', 'which is bigger'). This clearly indicates when to use the tool and its alternative.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: latency (15-60s, up to ~90s), decomposition into facets, parallel routing, gap reporting (gaps[]), contradiction detection, hop field, citation_uri with resolvability guarantee, semantic excerpting behavior, and the account/depth limitations. It also explains the depth tiers' behaviors. This fully discloses what the tool does beyond the annotations.

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

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

The description is long but information-dense, covering account requirements, alternatives, use cases, behavioral details, and depth semantics. Every sentence adds value; there's no filler. The structure flows from prerequisites to core function to alternatives to depth behaviors to output details. It could be slightly trimmed (e.g., the citation paragraph is dense but needed). It's appropriately front-loaded with the account requirement and core definition.

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

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

Given 2 params, 100% schema coverage, rich annotations, and no output schema, the description covers all essential aspects: input expectations, output format (findings packet, gaps[], contradictions[], hop, citation_uri), latency, prerequisites, failure modes, and comparisons to alternatives. The tool's complexity (parallel decomposition, depth tiers) is fully explained. No critical gaps remain.

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

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

Schema coverage is 100% for both parameters. The description adds meaning beyond the schema: it defines the depth levels' behavioral implications ('standard' adds gap-recovery hop and contradictions[] scan, 'thorough' adds lead-chasing and is paid), and clarifies that 'question' should be natural language and broad/multi-part is fine. It doesn't add syntax details but enriches the semantics meaningfully, especially for the depth enum.

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 is explicit: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and 'Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL'. It specifies a precise verb (research/decomposes), a distinct resource (structured data sources vs open-web search), and clearly distinguishes from siblings like ask_pipeworx and bet_research. The scope is well-defined with examples and exclusions.

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: 'Best for broad/multi-part questions over structured data', and direct alternatives: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states when it will fail ('returns mostly empty gaps[] when the topic isn't in the structured catalog') and the account requirement. This is comprehensive usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds context about the underlying Mapbox data, supported profiles (driving, walking, cycling), and returned elements (alternatives, banner/voice instructions), all consistent with annotations.

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

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

Two concise, information-dense sentences cover trigger examples, core functionality, return types, profiles, and data source. There is no fluff or redundancy; every clause adds value.

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

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

Given the output schema enriches return expectations and annotations cover safety, the description is largely adequate for selecting and invoking the tool. Some optional parameters are not explained, but the core invocation (coordinates, profile) is clear, and the examples in the schema provide additional usage patterns.

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?

With 0% schema description coverage, the description partially compensates by explaining coordinates, profile, alternatives, and voice/banner instructions. However, parameters like steps, overview, geometries, annotations, and language remain undocumented in both schema and description, leaving gaps.

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 'turn-by-turn routing between two or more coordinates' and lists concrete output types (geometry, distance, duration, voice/banner instructions). It opens with natural-language trigger examples that clearly define the tool's purpose and distinguish it from the sibling directions_matrix.

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 when-to-use signals through example queries ('Directions from A to B', 'how long does it take to drive from X to Y'). It does not explicitly exclude alternatives like directions_matrix, but the context strongly implies this is the tool for point-to-point routing.

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, covering the safety profile. The description adds behavioral context by specifying that the tool returns both distance and duration, and that it constructs an N×M matrix, which goes beyond the annotations and helps the agent understand the output nature.

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

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

The description is concise, using two sentences and a list of synonyms to convey the core function, followed by concrete use cases. No unnecessary information is included; every part contributes to understanding the tool's purpose and applicability.

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 purpose, use cases, and core behavior well, and an output schema exists to define return values. However, it omits details on optional parameters that affect the matrix semantics, such as how to specify sources/destinations separately. Overall, it is adequately complete for a tool of this complexity, but not exhaustive.

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?

With 0% schema description coverage, the description must compensate for parameters. It clarifies 'coordinates' as the core input and implies 'sources' and 'destinations' through the N×M matrix concept, but it does not explain 'profile' or 'annotations'. The description adds meaning for the most important parameter but leaves others ambiguous, partially compensating for the schema's lack of descriptions.

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

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

The description clearly states the tool computes an N×M distance and duration matrix between coordinates, with synonyms like 'distance matrix' and 'travel times grid'. It distinguishes from the sibling 'directions' tool by focusing on multiple points and all-to-all distances, making the purpose unambiguous.

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

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

The description lists specific use cases such as traveling-salesman, delivery routing, and nearest-warehouse problems, effectively indicating when to use this tool. It doesn't explicitly name alternative tools, but the phrase 'between multiple points' implies a contrast with point-to-point routing tools, providing clear context without explicit exclusions.

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

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

The annotations already cover read-only/idempotent/non-destructive traits. The description adds valuable behavioral details: returns top-N tools with full input schemas and 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations to explain the exact output wrapper. No contradiction.

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

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

The description is front-loaded with the core purpose and usage context. The long list of covered domains earns its place by setting expectations for the tool's scope, though it could be trimmed slightly without losing meaning. Overall efficient for the information it conveys.

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 straightforward discovery tool with no output schema, the description is complete. It explains the return format (names, descriptions, schemas) and the intended first-call pattern. Combined with the comprehensive schema and annotations, the agent has everything needed to select and invoke this tool.

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

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

Schema description coverage is 100%, so all six parameters (query and its aliases, limit) are already adequately described. The description does not add any parameter-specific semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly states the verb and resource. It distinctively frames the tool as a discovery/browsing utility, and the phrase 'Call this FIRST when you have many tools available' helps distinguish it from sibling tools that answer directly.

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

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

It provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This is strong guidance, though it does not explicitly name alternative tools or state when not to use it beyond the 'not just one answer' clue.

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, openWorld), the description discloses fan-out across multiple sources, specific return fields, USPTO API sunset soft-fail, GDELT→GNews fallback, and unsupported name input. This is rich behavioral context that annotations alone don't provide.

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

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

The description is one dense paragraph but every sentence contributes valuable context: examples, usage preference, behavioral details, and parameter restrictions. It's not particularly scannable, but it's not padded with filler either.

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, yet the description enumerates all return groups (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and explains failure modes (USPTO sunset, GDELT→GNews fallback). It also covers input constraints, making the tool's behavior fully self-contained.

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

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

The schema already documents both parameters with 100% coverage, including the 'Names not supported' note. The description adds example values (AAPL, 0000320193) and reiterates the zero-padding requirement, but this is largely redundant with the schema, 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 explicitly states it produces a 'full cross-source profile of a US public company in ONE parallel call' and provides concrete example queries ('Tell me about X', 'brief me on Tesla'). It clearly distinguishes from single-pack SEC/XBRL/news lookups, making the tool's intent specific and 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?

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use resolve_entity first if only a name is available. This gives clear when-to-use and alternative guidance.

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

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

Annotations already communicate readOnly false, destructive true, and idempotent true. The description aligns with these (delete/destructive) and adds context about 'previously stored' and 'sensitive data', but it does not disclose behaviors like what happens if the key doesn't exist or whether deletion is permanent. Since annotations cover the core safety profile, the description adds limited extra value.

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 and front-loaded with the primary action. It uses three short sentences, each adding relevant information: purpose, usage conditions, and related tools. No wasted words.

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

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

For a simple one-parameter deletion tool, the description provides enough context: what it does, when to use it, and related tools. It doesn't detail return values, but there is no output schema, and the destructive annotation handles the main risk. Minor gap: it doesn't explicitly state that deletion is irreversible, though this is implied.

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 the parameter 'key' already described as 'Memory key to delete'. The description doesn't add additional parameter semantics beyond echoing 'by key'. Baseline of 3 applies because the schema already documents the parameter fully.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes itself from sibling tools like remember and recall by focusing on deletion, and the phrase 'previously stored' clarifies the target.

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 provides when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, effectively guiding the agent on related tools without overcomplicating.

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 safe operations; description adds the mechanism (fetches the page, extracts title/description/key links) and output format (single text blob), giving the agent a clear model of how the tool behaves 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?

Three tightly written sentences: purpose, process, and use cases. Each earns its place and the most critical 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?

Despite no output schema, the description tells the agent what to expect (a single text blob in llms.txt format) and covers the full workflow. Combined with robust annotations and schema, the description is sufficiently complete for this simple tool.

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

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

Schema covers 100% of parameters, so the description doesn't need to explain them. It adds only marginal context like 'any URL' and 'standard markdown format,' which doesn't meaningfully enhance parameter understanding beyond the schema.

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

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

First sentence clearly states the tool generates a production-ready llms.txt file for any URL, with explicit mention of AI crawlers. This distinguishes it from siblings like ai_visibility_check which focus on checking presence, not 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 includes a 'Useful for' section listing three concrete contexts: client site indexing, drafting for own project, and auditing competitors. This provides clear situational guidance, though it does not explicitly name alternative tools for exclusion.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds scope context (any street, POI, administrative area worldwide) and the use of Mapbox, but does not disclose rate limits, response details, or other behavioral traits beyond what annotations already provide.

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

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

The description is compact (two sentences plus an example), front-loaded with trigger phrases, and every element contributes to understanding the tool's core function. No wasted words or redundant information.

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

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

The output schema exists, so return values are covered elsewhere. However, with 9 parameters and zero explanatory coverage in the description, an agent is unlikely to know how to use optional parameters like bbox or proximity. The description is adequate for the basic query case but incomplete for advanced usage.

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

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

The schema has 0% coverage, and the description only illustrates the 'query' parameter with an example. It does not explain the meaning or use of the other 8 optional parameters (bbox, limit, types, country, language, proximity, fuzzyMatch, autocomplete), leaving the agent to infer from parameter names.

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

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

The description clearly states that the tool converts a street address, city, or place name to GPS coordinates using Mapbox's global geocoder. It also includes natural language examples ('What are the coordinates of...') and distinguishes it from reverse geocoding by using 'forward' and listing sibling geocode_reverse.

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 usage context through example user queries and states it works 'worldwide' on various place types. It does not explicitly contrast with geocode_reverse or other siblings, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by disclosing behavioral details: it returns the 'nearest' result via Mapbox, works globally, and can yield various geographic granularities. No contradictions with annotations.

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

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

The description is a single, focused sentence with helpful natural language aliases. It is front-loaded and efficient, though the list of example queries is slightly redundant and could be trimmed without losing meaning.

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

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

The tool has an output schema and safe-read annotations, so the description doesn't need to explain return values. It covers global scope and result types, but misses semantic details for optional parameters. The schema examples partially offset this gap.

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 0%, and the description only references latitude and longitude implicitly. Optional parameters like limit, types, country, and language are not explained at all, leaving the agent to guess their meaning from the schema examples 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 converts latitude/longitude into the nearest address, neighborhood, city, region, or country. It distinguishes itself from the sibling 'geocode_forward' by explicitly calling 'reverse geocode' and providing natural language examples that align with the tool's direction.

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?

Usage context is well implied through example queries like 'What's at [lat,lng]' and 'reverse geocode coordinates'. It does not explicitly mention alternatives or exclusions, but the purpose is unique relative to sibling tools and the description makes when-to-use obvious.

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?

Despite strong annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral context: it generates polygons, supports time/distance contours, and profiles. It does not explain data sources or caveats, but with annotations already covering safety, this is adequate.

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 bit verbose with natural language query examples, but the structure is effective: it opens with example queries, then gives the core definition and use cases. Every part adds context, though it could be trimmed without losing meaning.

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

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

The description covers the main functionality, input semantics, and typical use cases. Since an output schema exists, return details are not needed here. It is sufficiently complete for an agent to decide when and how to use the tool, despite some param gaps.

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

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

Schema coverage is only 13%, so the description must compensate. It explains key parameters: profile (car/walking/cycling), coordinates (start point), contours_minutes/meters (time/radius), and polygons (output type). However, denoise, generalize, and contours_colors are left undocumented, leaving gaps for those parameters.

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

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

The description clearly states the tool computes isochrone polygons (reachable area within X minutes or meters) from a starting coordinate, with explicit mention of transport modes (car, walking, cycling). It distinguishes this from sibling tools like directions by focusing on area/reachability rather than routes.

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

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

Explicit use cases are given: site-selection, delivery-zone, commute-shed, and catchment questions. While it doesn't explicitly mention alternatives, the purpose and examples strongly convey when this tool is appropriate relative to routing tools.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds the specific return fields, which helps the agent anticipate the response. 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: the first states action and return fields, the second gives usage context. No redundant wording, 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 read-only list tool with one optional parameter and no output schema, the description covers purpose, return shape, and typical use cases. Pagination is not mentioned but likely unnecessary here.

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 provides a full description of the single parameter include_inactive with default false. The tool description doesn't add new semantics but harmonizes with 'active subscriptions' in the description. Baseline 3.

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

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

The description clearly states the verb 'List' and the resource 'subscriptions', specifies that it returns the caller's active subscriptions, and enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like 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?

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use guidance. It doesn't explicitly name alternatives, but the sibling list makes the distinction obvious.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds the 'most likely path' probabilistic nuance and noise-cleanup intent, but lacks details on road network coverage, accuracy, or rate limits. No contradiction with annotations.

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

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

The description is a single, well-structured sentence with front-loaded problem framings. Every phrase adds value, and it avoids any redundant repetition of schema or annotation info.

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

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

While an output schema exists, the tool has 9 parameters with zero descriptions in the schema and almost no parameter guidance in the description. The agent can understand the tool's purpose but cannot confidently configure optional inputs like profile or overview, making the description incomplete 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 0%, and the description only references 'a sequence of GPS points', which vaguely maps to the required coordinates parameter. It provides no explanation for the other 8 parameters (profile, overview, radiuses, tidy, steps, etc.), leaving the agent without critical configuration guidance.

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

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

The description explicitly states the tool takes a sequence of GPS points and returns the most likely path along the road network. The alternative phrasings ('Snap GPS trace to roads', 'clean up noisy GPS coordinates') clarify intent and distinguish it from sibling tools like directions or geocoding.

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: vehicle telematics, fitness-tracker cleanup, and 'what road did this driver actually take' questions. This gives the agent strong contextual signals for when to use the tool, though it does not explicitly mention when not to use it.

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

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

Annotations provide no useful hints (all false), so the description carries full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), free usage, the claim_token workflow for following up, and that the team reads digs daily and uses signal for roadmap. This is rich beyond annotations.

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

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

The description is long but every sentence earns its place, covering usage rules, cross-server exclusions, claim_token flow, rate limits, and authorship guidance. It is moderately over-explained for a simple feedback tool, but the density is justified by the need to prevent misuse.

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 4 parameters, nested context, no output schema, and nuanced behavior, the description fully covers what an agent needs: how to file, what types mean, the token-based follow-up, exclusions, and policy details. No critical gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable semantics: it warns against pasting end-user prompts, asks to describe issues in terms of Pipeworx tools/packs, and explains how to use claim_token with a concrete example. 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 first sentence states a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings like ask_pipeworx by focusing on feedback rather than questions or research.

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

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

Provides explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server ... file it with that server instead.'

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 read-only/open/idempotent; description adds meaningful behavioral context: self-aggregating signal, derived from CF analytics-engine, no PII, only (pack, tool, count), and cache TTL. This helps the agent understand freshness and privacy implications.

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 well-structured sentences with a scannable 'Useful for' list. Every sentence contributes—purpose, use cases, and behavioral traits. 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?

For a single-optional-param tool with no output schema, the description fully covers what's returned, how it's derived, privacy, and caching. It also positions the tool among siblings. Very complete for its complexity.

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

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

Schema has 100% coverage with enum and explanatory text describing window trade-offs. The tool description merely references the window values without adding additional meaning, 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 opening line 'What other AI agents are calling on Pipeworx right now' instantly conveys purpose; then it states it returns top tools, top packs, and call volume over a window. This clearly distinguishes from siblings like discover_tools or recall, which list/find individual resources rather than aggregate trending signal.

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 three explicit 'Useful for' scenarios covering discovery, validation, and alignment. However, it does not explicitly name alternatives or when NOT to use it, so falls short of the highest benchmark.

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 readOnlyHint annotations, the description discloses detailed behaviors: the semantic anchor requires ≥0.30 Jaccard similarity, partitions with >20% placeholder fraction return a null arb signal, and the fill check 'prices it against live CLOB depth' with guidance not to trade if realizable_edge_pp ≤ 0. It also reveals that deviations >3pp emit a BUY/SELL EVERY LEG 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 long but highly structured with labeled sections for modes, semantic anchor, partition filter, response, and fill check. Every sentence adds specific information without redundancy, and the main purpose is front-loaded in the first sentence. The density is justified for the tool's complexity.

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

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

With no output schema, the description fully specifies the response shape, including opportunities[] fields and partition_check fields. It covers edge cases like low similarity, placeholder filters, and fill check results, making it complete for the tool's complexity.

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

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

Although the schema already documents the two parameters, the description adds meaningful context: event accepts slugs or URLs and 'walks child markets', while topic is for cross-event scanning and 'searches related events across the platform'. It provides concrete examples like 'fed-decision-may-2026' and explains the trade-off between modes, enriching the schema beyond field names.

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

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

The description opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', clearly identifying the tool's purpose with a specific verb and resource. It distinguishes itself from sibling tools by focusing on arbitrage detection versus edge tracking or fill risk.

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

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

The description gives explicit instructions for when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also directs users to 'use polymarket_fill_risk' for custom sizing, naming an alternative tool for a different need.

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, and destructiveHint=false. The description adds substantial behavioral context beyond these: it discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure with diagnostics for empty segments ('_diagnostics... so callers can see WHY a segment is empty'), a 24h-move warning that flags when recent movement already exceeds the edge, and filtering rules like the placeholder-slug filter and >20% placeholder fraction skip. This far exceeds what annotations alone provide.

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

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

The description is long but well-structured with clear section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It front-loads the core purpose and then organizes detail hierarchically. While some specifics (e.g., per-sport α values, exact gate thresholds) could be considered excessive for an agent just selecting the tool, they are relevant for understanding output semantics. It earns its length through density, but could be trimmed without losing essential guidance.

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

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

Given there is no output schema, the description compensates by thoroughly specifying the response structure: 'by_segment{model_driven,structural_arbitrage,concentrated_longshot}, fed_candidates/fed_note... and _diagnostics...'. It also details per-opportunity fields ('edge_pp_net (after slippage), kelly_fraction + kelly_fraction_half (capped at 0.25), market.liquidity, market.spread_pp, market.volume'). The description covers edge cases (empty segments, stale data, knob interactions) and performance characteristics (caching), making it complete for an agent to predict behavior without prior tool experience.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond field comments. It explains the practical effect of tradeable-edge knobs: 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable'. It also clarifies a non-obvious interaction: 'Partition arbs always return kelly_fraction_half=0 at the parent level by design... so min_kelly never filters them — this knob applies to the per-leg Kelly inside top_legs instead.' This goes beyond the schema and helps the agent select and set parameters correctly.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes the tool from siblings like polymarket_arbitrage by framing it as a broad opportunity scanner for 'what should I bet on today' rather than a pure arbitrage tool. The segmentation into MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT further clarifies its multi-purpose 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 explicitly states its intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when knobs like min_liquidity and max_spread_pp should be used ('Set to 2 to require tight books'), and provides an explicit exclusion for Fed bets ('excluded from ranking — 1m-T vs EFFR signal is unreliable'). However, it does not explicitly name sibling tools as alternatives (e.g., suggesting polymarket_arbitrage for pure arbitrage), so it stops short of a full when-not/alternatives guide.

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

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

Annotations already declare readOnly and non-destructive, but the description adds valuable behavioral context: snapshots are written only on cache-miss, so gaps indicate no scan; decay is computed on daily closes of edge_pp_net with default slippage, not intraday; and history is bounded by a 60-day TTL. These details inform interpretation of results and are not covered by annotations.

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

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

The description is well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loads the primary purpose. Every sentence contributes meaningful information, from the core question to response schema details and data-retention caveats, without 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?

With no output schema, the description fully compensates by documenting the response structure: tracked[] with full time-series and trend labels, expired[] with lifespan_days, and snapshot_dates[]. It also covers data limitations (TTL, snapshot granularity), making the tool's behavior and output completely understandable.

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

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

Schema description coverage is 100%, with both 'days' and 'window' already described in detail (defaults, clamps, allowed values). The description restates these ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') without adding new semantic meaning, 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 opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the core question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence 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 implies when to use this tool by contrasting 'a fresh wide edge and a 3-week-old wide edge are different trades', suggesting it is for assessing edge persistence over time. It provides clear context and even notes data-availability caveats ('gaps mean nobody scanned that day'), but it does not explicitly name alternatives or state 'use polymarket_edges for current edges', so it lacks an explicit exclusion.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond this by describing the ladder-walking behavior, interpreting size_usd differently for buys vs sells and basket mode, and detailing output such as thin_legs[] and forced_directional_risk. No contradictions with annotations.

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

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

The description is long but well-structured with clear SINGLE-MARKET and BASKET sections. Every sentence adds value, though the density might be heavy for an agent. It is front-loaded with the core purpose and then details mode-specific behavior.

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

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

Given no output schema, the description comprehensively enumerates all returned fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, capture_ratio, thin_legs[]). It also covers edge cases like forced_directional_risk and max_clean_notional_usd, making it complete for the tool's complexity.

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

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

With 100% schema description coverage, the baseline is 3. The description adds meaningful semantics: explains side defaults per mode, clarifies size_usd as max spend on buys vs target proceeds on sells, and defines basket size as settlement notional per leg. This goes beyond the schema, but some redundancy remains.

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

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

The description clearly states the tool performs a fill-risk check comparing realizable vs theoretical edge against live order-book depth. It explicitly distinguishes between single-market and basket modes, and names the specific output fields, making its purpose unambiguous and distinct from siblings like polymarket_arbitrage.

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

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

Provides explicit usage instructions: use before polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500. It also explains the consequences of not using it (partial fills converting an arb into unhedged directional positions), which is strong when-to-use and why guidance.

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

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

Annotations already declare readOnlyHint=true, but the description goes far beyond by explaining specific behavioral nuances: compatibility_warning conditions (non-equivalent bet shapes, semantic mismatch), temporal_alignment semantics, skipped_cross_type/subtype counters, and what matched_pairs:0 means. 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?

While long, the description is densely packed with value and well-structured: it front-loads the core purpose, then breaks out modes, response fields, safety fields, and a contextual caveat. Every sentence earns its place, and list-style formatting aids 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, so the description must explain return values—and it does: leg-by-leg prices, matched spreads, top_spreads_pp, compatibility warnings, temporal alignment, and skip counters. It covers edge cases and gives enough context to correctly interpret results.

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

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

Schema covers all three parameters, but the description adds crucial operational meaning: topic auto-fetches pre-mapped events, explicit ticker/slug override the topic-mapped side, and it clarifies the expected formats (e.g., Kalshi ticker vs Polymarket slug). This significantly enhances schema understanding.

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

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

The description clearly states a specific verb+resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparisons rather than intra-venue arbitrage, and explains two operating 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?

Provides explicit usage guidance: when to use the `topic` shortcut mode vs explicit `kalshi_event_ticker`/`polymarket_event_slug`, and explicitly warns that most pre-mapped topics return compatibility warnings and pre-mapped does not mean tradeable. This is strong when/when-not 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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds critical behavioral context: the ability to list all keys by omitting the parameter, and scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)'. This discloses privacy and scoping behavior not captured in 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 well-structured and front-loaded, starting with the primary action in the first sentence. Each of the four sentences contributes distinct value (action, usage, scoping, pairing with siblings), with no wasted words or tautological filler.

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

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

For a tool with one optional parameter, no output schema, and clear annotations, the description is remarkably complete. It covers the dual behavior (single key vs. list all), privacy scoping, and contextual usage examples. There is no missing information that an agent would need 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 schema provides 100% coverage for the single 'key' parameter, but the description adds significant semantic depth by explaining the behavior when omitted: 'list all saved keys (omit the key argument)'. This directly explains the parameter's optionality and its effect on the operation, exceeding what the schema alone conveys.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb ('retrieve') and resource ('value previously saved'), and differentiates from siblings by explicitly naming 'remember' and 'forget' as companion tools.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also explains the tool's relationship to siblings ('Pair with remember to save, forget to delete'), giving clear guidance on when to use it.

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

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

The description discloses the mark_read side effect (flags returned events read, so next call only shows newer ones), which goes beyond the readOnlyHint annotation. It also reveals return payload composition (source, citation_uri, raw event payload) and the alternative HTTP endpoint, adding substantial value beyond 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?

Four sentences packed with relevant information. Front-loaded with 'Pull fired events from your subscription feed', then immediately covers return format, filtering, mark_read side effect, and alternative access. No wasted words.

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

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

For a fairly simple polling tool with 5 params and no output schema, the description explains the return format, filtering, and stateful behavior. It doesn't explicitly mention limit or unread_only, but those are documented via the schema, so completeness is high given richness.

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

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

Schema coverage is 100% and the description adds semantic examples (type like sec_8k, since as ISO timestamp) and explains mark_read behavior. Limit and unread_only are covered by the schema, so the description compensates well where needed.

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

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

Description clearly states the tool pulls fired events from the subscription feed, which is a specific verb+resource. It distinguishes from siblings like list_subscriptions, subscribe, and unsubscribe by focusing on retrieving alerts already written to the feed.

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

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

Provides clear context: says polling works fine, mentions filtering by type and since, and describes mark_read behavior. It does not explicitly name sibling alternatives or when-to-use vs not, but the usage context is strong enough for an agent to decide when to invoke.

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?

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds significant behavioral detail: it fans out to SEC EDGAR, GDELT→GNews with fallback logic, and USPTO with a soft-fail note. It also discloses return structure (changes[], total_changes, citation URIs). No contradictions with annotations.

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

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

The description is dense and well-structured, front-loading examples and then explaining sources, parameters, output, and an alternative. The six quoted example phrases at the start are slightly redundant, but the overall 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?

For a multi-source tool with no output schema, the description covers sources, fallback behavior, since syntax, and return fields. It does not mention pagination or exact error handling, but these are not critical for basic usage. The description is sufficiently complete for an agent 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?

Input schema covers all 3 parameters with detailed descriptions (since formats, value as ticker/CIK, type enum). The description repeats some of this information but adds little new meaning about parameters themselves. While it provides illustrative examples, the schema already does the heavy lifting.

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 ('change feed'), names the resource (company), and clearly defines scope (last N days/weeks/months). It starts with natural-language examples that map directly to the use case, and explicitly differentiates from the sibling tool entity_profile. This makes the tool's 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 clear usage context via examples and explicitly points to entity_profile as an alternative for static profiles. It does not enumerate other exclusions or when not to use this tool, but the provided alternative and the example queries give strong guidance.

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

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

Annotations already indicate the tool is non-read-only, idempotent, and non-destructive. The description adds valuable behavioral context: key-value scoping by identifier, persistence differences between authenticated and anonymous sessions, and the 24-hour retention for anonymous sessions. It does not contradict annotations, and the additional context goes beyond what annotations provide.

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

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

The description is a compact three sentences, front-loaded with purpose and followed by usage and behavior. Each sentence contributes useful information without redundancy. Slightly longer than strictly necessary, but all content earns its place.

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

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

For a simple memory-write tool with two required parameters and no output schema, the description covers essential context: what to store, when to use, how data is scoped/persisted, and lifecycle (pairing with recall/forget). No critical gaps remain.

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

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

Schema descriptions cover 100% of parameters with clear examples for key and value. The description reinforces the key-value nature but does not add meaning beyond the schema. Since schema coverage is high, the baseline of 3 applies, and the description does not need to compensate.

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 ('Save data the agent will need to reuse later') and clearly distinguishes from siblings by naming complementary tools (recall, forget). It also clarifies scope (conversation or sessions) and value examples, leaving no ambiguity about the tool's function.

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 the tool ('Use when you discover something worth carrying forward') with concrete examples, and also mentions pairing with recall and forget. This gives clear guidance on usage and alternatives, satisfying the 'when-to-use vs alternatives' criterion.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds substantial behavioral details beyond this: it cascades through several lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, labels identifiers with their source, and explicitly lists unresolved identifiers. This is rich, non-contradictory context that goes well beyond the annotations.

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

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

The description is long but well-structured, opening with user intents, followed by supported types and edge-case behavior. Every section provides value and the layout aids scanning. It could be slightly tightened but remains appropriately sized for the tool's complexity.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does so thoroughly: it lists the identifiers returned for companies and drugs, mentions source labelling, handles unresolved identifiers explicitly, and describes graceful degradation. It also notes that using this tool replaces 2-3 manual lookups, setting complete expectations for the agent.

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

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

Schema coverage is 100% for both parameters. The description reinforces and expands on parameter meaning by providing concrete examples (AAPL, 0000320193, ozempic) and clarifying accepted input formats for each type. It also explains what resolution returns for each type, adding practical context beyond the schema's enum and string descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with specific examples like ticker, CIK, LEI, and RxCUI. It distinguishes itself from the sibling tools by explicitly saying 'Use FIRST whenever you have a name but need an ID,' making its 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 FIRST whenever you have a name but need an ID') and includes example queries. However, it does not explicitly name alternative tools or state when not to use it, though the 'Use FIRST' phrasing implicitly excludes cases where an ID is already known. This is clear context but lacks formal exclusion criteria.

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, so the description adds valuable behavioral context: it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with specific fields. It does not contradict annotations and goes beyond them by describing the internal process and output structure.

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

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

The description is three sentences long, front-loaded with the core action, then explains the mechanism, provides a use case, and states the output. Every sentence serves a distinct purpose without redundancy, making it highly efficient and scannable.

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 (4 params, no output schema), the description provides a complete picture: what it does, how it works (probing with ai_visibility_check), why to use it (competitive audits), and what it returns (ranked list with score, confidence, signal density). No critical operational aspect is left unexplained.

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% per context, with each parameter (models, _apiKey, context, entities) having a description. The tool description adds limited parameter-level meaning beyond what the schema already provides, only reinforcing the 'first entry treated as subject' behavior. It meets the baseline but does not substantially elevate parameter understanding.

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

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

The description clearly states a specific verb ('compare') and resource ('AI visibility across multiple entities side-by-side'). It distinguishes itself from the sibling ai_visibility_check tool by explicitly focusing on multi-entity comparison and ranking, which ai_visibility_check presumably handles a single entity.

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 a concrete use case ('competitive AI-marketing audits') and an example question, making it clear when to use this tool. It implicitly names the alternative (ai_visibility_check) as the underlying probe, but does not explicitly state when NOT to use this tool versus alternatives like compare_entities.

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

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

Annotations mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: it fans out to multiple services, handles partial failures gracefully, notes that bundlephobia's first measurement can take 5-30s, and explains that sources_failed will report timeouts. No contradictions.

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

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

The description is dense but well-structured: it opens with a clear one-line summary, then details data sources, usage triggers, return contents, limitations, and failure behavior. Every sentence adds value, though it is somewhat long; 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?

No output schema exists, so the description carries the full burden of explaining return values. It lists the summary block fields (is_latest, license, etc.), mentions per-advisory detail, links, and alternative versions. It also covers ecosystem scope and partial failure behavior, making it complete for a composite tool.

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

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

Schema coverage is 100%, so parameters are well-documented in the schema. The description adds a little context (e.g., default behavior for version, ecosystem scope) but does not substantially extend the schema's param descriptions. Baseline of 3 is appropriate.

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

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

The description clearly states a specific purpose: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It identifies the resource (npm package), the verb (scan), and differentiates from siblings by specifying the ecosystem and the data sources.

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

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

Explicitly tells when to use the tool ('use whenever an agent asks is X safe / popular / small') and provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear context and a pointer to an alternative approach.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses BGE-base-en embeddings, 500-char overlapping windows, a 200K char cap with truncation flagging, and output offsets for verification. 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?

Five sentences, each delivering distinct value: purpose, mechanism, usage trigger, pairing, and technical constraints. The structure front-loads the core verb and resource, but the density of technical details could be slightly streamlined. Overall efficient.

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

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

With no output schema, the description compensates by specifying return values (passages, character offsets, similarity scores). It covers input expectations, size limits, truncation behavior, and usage context, fully preparing an agent to select and invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces that 'text' is previously fetched content and gives examples, but these are already implied in the schema's field descriptions. No additional parameter semantics are provided beyond schema.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' clearly stating the tool's verb, resource, and scope. It then details inputs (text + query) and outputs (top-N passages with offsets and scores), distinguishing it from sibling search/grounding tools.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context). It also pairs with ask_pipeworx_grounded, articulating when to use this tool versus grounding over the whole document.

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 behavior. The description adds that it returns a 'fetchable PNG URL' and requires no JS, but does not mention rate limits, auth, or other potential side effects. It adds some context beyond annotations but is not rich.

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

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

The description is two sentences, front-loaded with query examples, and contains no filler. Every sentence adds value, making it highly concise and well-structured.

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

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

With an output schema present and good annotations, the description covers purpose, use cases, return type, and required param semantics. Optional params are left for examples, but overall this is sufficient for a simple URL-generation 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 0%, and the description maps 'style + coords + zoom + width/height' to required params (style_id, lon/lat, zoom, width, height). However, optional params like pitch, bearing, and retina are only shown in examples without explanation, so the description only partially compensates for the coverage gap.

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 'generates a Mapbox static-tile image URL' and provides example user queries like 'Static map image of [location]'. This distinguishes it from interactive or other map tools, giving a specific verb and resource.

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 lists concrete use cases ('embedding in slack, docs, emails, or dashboards') and notes 'No client-side JS or interactivity required', which signals when to prefer this static approach. However, it does not explicitly name alternative 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: annotations declare idempotentHint=true, but the description says 'Create' and 'Returns the new subscription id', implying each call creates a distinct new subscription. No mention that repeated calls with identical parameters return the same subscription. This directly contradicts the idempotency guarantee and misleads the agent.

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 structured: purpose, return value, auth requirement, three supported types, and delivery channels. Each sentence adds useful detail without fluff, though it is a bit long and could be tightened by removing repetition with the schema.

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

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

Covers many key aspects: return value, auth, delivery channels, feed consumption via recent_alerts, sms limits, and examples. Missing details: webhook delivery is only in schema, two enum types are absent from the description, and idempotency behavior is not explained (and is contradicted). Overall, for a tool with no output schema, it is fairly complete but has notable gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with concrete examples: items:['5.02'] = officer change, topic:'fed' for polymarket_edge, series_id:'UNRATE' for fred_series. It also clarifies the sms cap and verification. However, it omits patent_grant and clinical_trial types, which the schema does explain.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation, and even references recent_alerts for consuming the feed.

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

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

The description provides clear context: requires an OAuth account, anonymous/BYO cannot persist, and it lists supported subscription types with concrete examples. It also references recent_alerts as the way to pull the feed, but does not explicitly contrast with list_subscriptions/unsubscribe or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds behavioral context by noting that results are drawn from the live catalog of thousands of tools and that examples include exact tool+argument shapes, which goes beyond the 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 a single dense paragraph but well-structured with lists and examples. Every sentence earns its place, covering purpose, behavior, parameter usage, and when to use it. It is slightly long but not wasteful, and the front-loaded example queries make it easily scannable.

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

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

For a tool with only one optional parameter, no output schema, and rich annotations, the description adequately covers what the tool returns (category-bucketed examples with tool shapes), how to invoke it, and when to use it. It is complete for the tool's complexity and even provides guidance on meta-tool usage.

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

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

Schema coverage for the single parameter `topic` is 100%, so the baseline is 3. The description adds value by providing concrete example values ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a cross-category spread, which complements the schema description and helps the agent construct valid invocations.

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

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

The description clearly states the tool as an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It provides specific example queries and distinguishes itself from meta-tools like ask_pipeworx, entity_profile, and compare_entities by being the first-stop for users who don't know 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?

Explicit usage guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also describes when to call with no arguments (full spread) versus when to pass topic for focus, and mentions the meta-tools as alternatives/next steps.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds contextual behavior: it queries 'inside a Mapbox vector tile around a coordinate' with 'a radius of a point,' and is 'against a specific tileset_id.' This goes beyond the annotations by describing the spatial scope and specialization. It doesn't contradict annotations. Some behavioral details (e.g., exact feature types returned) are covered by the output schema, so a 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 two sentences and front-loaded: the first sentence states the core function and scope, the second adds specialization and alternatives. Every word earns its place, with no repetition of schema or annotations. It is concise while carrying significant 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?

The tool has 8 parameters and is specialized, but the output schema exists and annotations cover safety and idempotency. The description explains what the tool does, what types of features are relevant, the need for a tileset_id, and when to prefer alternatives. It does not enumerate all parameters, but the implicit coverage plus output schema reduces the need. Given the complexity, it is mostly complete, though not exhaustive—hence a 4.

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 provides zero descriptions (0% coverage), so the description must compensate. It covers several key parameters implicitly: lat/lon ('around a coordinate'), radius ('within a radius of a point'), tileset_id ('specific tileset_id'), and layers ('POIs / roads / boundaries / buildings'). However, it does not address limit, dedupe, or geometry, and with 8 total parameters the coverage is partial. This is similar to the update_drive case where schema coverage is incomplete, warranting a 3.

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

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

The description starts with a specific verb+resource: 'Query features inside a Mapbox vector tile around a coordinate,' and further elaborates with example feature types (POIs, roads, boundaries, buildings). It explicitly distinguishes itself from siblings by calling it a 'Specialized GIS query' and noting that 'most users want geocode_reverse or directions instead.' This clearly differentiates it from the listed geocoding and routing tools.

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

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

The description explicitly gives usage context: it is for querying vector tiles by a coordinate and radius, restricted to a specific tileset_id. It also provides an explicit when-not-to-use: 'most users want geocode_reverse or directions instead,' naming the preferred alternatives for typical use cases. This is actionable guidance beyond what any structured field provides.

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

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

Beyond the annotations (which already indicate mutation, idempotency, and non-destructiveness), the description adds meaningful behavioral context: ownership enforcement and the deactivation-not-deletion mechanism. It explicitly explains that the row is deactivated to preserve historical events, which directly complements the destructiveHint=false annotation. This is valuable non-redundant disclosure.

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 clear sentences: the first states the core action, the second covers ownership and side effects. Every sentence earns its place with zero wasted words, and the key verb 'Cancel' is front-loaded.

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

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

The tool is simple (one parameter, no output schema, no nested objects), and the description fully covers its purpose, ownership rules, and behavioral consequence (deactivation). It also links to recent_alerts for historical events, making the tool's place in the larger workflow clear. The description is complete for this level of 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?

The input schema already covers 100% of parameter descriptions, with 'id' documented as 'Subscription id (uuid) returned by subscribe.' The description adds only the ownership nuance ('you can only cancel your own subscriptions'), which is a behavioral note rather than parameter syntax or format details. This does not significantly exceed schema coverage, so the baseline of 3 is appropriate.

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

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

The description opens with 'Cancel a subscription by id,' which uses a specific verb ('Cancel') and resource ('subscription'), and clearly distinguishes this from siblings like subscribe (create) and list_subscriptions (list). The ownership constraint further clarifies the exact 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 states ownership is enforced and explains the deactivation behavior ('deactivated not deleted'), giving clear context for when to use this tool vs alternatives. It implies use for canceling your own subscriptions and notes historical events remain via recent_alerts, but it does not explicitly name sibling alternatives or when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the bar is lower, yet the description adds substantial behavior: two verification pipelines, the verdict taxonomy, citation format, and the critical caller warning that could_not_verify is not evidence and carries verification_error{stage,detail}. This goes well beyond what structured fields provide.

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

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

The description is long but densely packed with high-value trigger phrases, routing logic, verdict semantics, and a caller warning. It is front-loaded with purpose and every sentence contributes meaning, though it is slightly verbose and could be tightened without losing value.

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

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

Despite having no output schema, the description compensates by explaining return verdict types, actual value with citation, reasoning, and error semantics. It covers the two major branching scenarios and clarifies ambiguous outcomes, making the tool nearly self-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?

Input schema has 100% coverage and already fully documents both parameters, including tolerance_pct ranges, default, and usage guidance. The tool description does not add extra parameter semantics beyond what the schema already provides, so a 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 concrete natural-language trigger phrases and states the core action: verifying factual claims against authoritative sources. It clearly distinguishes itself from sibling tools by covering both a structured SEC EDGAR fast path and a general grounded pipeline, so an agent knows exactly what this tool is for.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a strong usage signal. It also explains routing between company-financial claims and other claims, but does not name alternative sibling tools or state explicit when-not-to-use scenarios, so it is clear though not exhaustive.

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