Mapbox

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

Annotations already declare read-only, idempotent, and non-destructive. Description adds behavioral details: returns per-model {score, confidence, signals, raw_response} + combined view, explains API key passthrough, and default free model. No contradiction.

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

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

Two sentences, front-loaded with main purpose. The second sentence is longer but packs essential details. No fluff, every sentence adds value.

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

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

Given complexity (4 parameters with dependencies, no output schema), description covers core behavior, parameters, default, and return shape. Lacks mention of error handling or limits, but annotations cover safety profile.

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 describes all 4 parameters fully (100% coverage). Description adds value by explaining defaults (workers-ai), interdependencies (_apiKey needed only for anthropic), and context helps disambiguate. Provides usage guidance beyond schema.

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

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

The description clearly states the tool probes LLMs to score visibility for a given entity, with specific verb 'Probe' and resource 'LLMs for visibility'. It differentiates from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring per model.

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

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

The description explicitly mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to provide `_apiKey` for Anthropic and default model. Lacks explicit exclusion criteria but usage context is clear.

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

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

Discloses that the tool routes to 3,744 tools across 884 sources and returns structured answers with stable citation URIs. This adds significant context beyond the annotations (readOnlyHint, idempotentHint), which are consistent with the description.

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

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

Description is detailed and well-structured, starting with a bold preference statement, listing domains, explaining routing, providing usage triggers, and examples. Slightly verbose but every sentence serves a purpose.

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

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

For a complex tool with no output schema, the description covers input expectations, behavior (routing, citations), and practical usage examples. It sufficiently equips an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with each parameter described as an alias for 'question'. The description adds examples and context about the type of questions to ask, but the parameter itself is straightforward. The added value is moderate.

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 identifies the tool as a question-answering system for authoritative structured data. It contrasts with web search and lists specific domains (SEC filings, FDA data, etc.), making the purpose unambiguous and distinguishing it from siblings.

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

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

Explicitly states preference over web search and provides concrete triggers like 'what is', 'look up', 'find', 'get the latest'. Includes examples such as 'current US unemployment rate' and 'Apple's latest 10-K', giving clear guidance on when to use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true. Description adds value by disclosing the extra LLM call cost, specific refusal reasons, and the extraction logic (quotes from tool result). 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 well-structured with clear sections (behavior, return format, usage context). It front-loads key information, though slightly lengthy. Every sentence provides value.

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

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

Given the complexity of the grounded mode, lack of output schema, and need to explain refusal reasons, the description is complete. It covers what the tool does, how it differs, return format, and when to use alternative.

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

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

Schema description coverage is 100%, with all 6 parameters (including aliases) documented. The description mentions the aliases but adds no new meaning beyond what the schema provides, which is sufficient.

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 hallucination-resistant answer mode for high-stakes reads, contrasting it with ask_pipeworx. It states it extracts answers only from tool results, returns evidence and explicit refusals, and is for situations where answers must not be invented.

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

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

Explicitly states 'Use whenever an answer will be quoted, cited, or acted on' and 'Prefer ask_pipeworx for casual lookups,' providing clear when-to-use and when-not-to-use guidance with an alternative named.

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

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

Discloses extensive behavioral traits beyond annotations: low-confidence short-circuit, closed market handling, wide-spread warnings, resolution-rule risk parsing, parent event extraction, and news fallback mechanisms. No contradiction with annotations (all readOnly, idempotent hints respected).

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 lengthy but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety). Front-loaded with purpose. Some redundancy could be trimmed, but most sentences add value.

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

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

Despite no output schema, the description comprehensively covers input, process, output structure, safety controls, edge cases (closed markets, low confidence), and resolution risks. Sufficient for an AI agent to invoke correctly.

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

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

Schema description coverage is 100%, but the description adds significant value: explains market input types (slug, URL, question), depth options with defaults, and include_raw behavior with size implications and use cases. Examples in schema further clarify.

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 researches Polymarket bets by pulling Pipeworx data, with specific verbs and resources. It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive research.

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

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

Explicitly states when to use: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides concrete examples and distinguishes from alternatives implicitly through context.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, and the description enriches transparency by detailing data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), specific financial fields (revenue, net income, cash, debt), fiscal year handling, and result ordering. No contradiction with annotations.

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

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

The description is information-dense but slightly verbose. It starts with trigger phrases and logically progresses from purpose to details. Every sentence adds value, but some phrasing could be tightened (e.g., parenthetical asides).

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

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

There is no output schema, so the description must explain return data. It covers financials for companies, adverse events and trial counts for drugs, and mentions citation URIs. Missing edge case details (e.g., error handling for invalid tickers) but sufficient for typical use.

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

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

Schema description coverage is 100%, but the description adds significant context: explains what each 'type' returns, includes example values, and clarifies that results are sorted by primary metric. This goes beyond the schema's basic descriptions.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs, using clear trigger phrases like 'Compare X and Y' and 'X vs Y'. It distinguishes itself from sibling tools (e.g., entity_profile) by emphasizing it replaces multiple sequential lookups with one parallel call.

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 strong guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It gives specific use cases (comparing companies, drugs, ranking) and example queries. While it doesn't explicitly list when not to use, the priority instruction is clear.

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

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

Annotations already mark as readOnly, openWorld, idempotent, non-destructive. Description adds that it never invents, provides gaps[], and returns evidence with citations. 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?

Dense paragraph with all key info front-loaded. Slightly verbose in middle but still efficient. Every sentence adds value.

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

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

Covers output format (findings with evidence, confidence, source, gaps), expected runtime (15-60s), prerequisites, and limitations. No output schema exists but description sufficiently explains what to expect.

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

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

Schema coverage is 100%. Description adds meaning: depth values mapped to facet counts (quick=3, standard=5, thorough=8) and notes paid plan for thorough. Question param described as natural language and multi-part capable.

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 'Grounded multi-source research in ONE call' and explains decomposition and parallel routing. Distinguishes from sibling `ask_pipeworx` by mentioning single lookups vs multi-part questions.

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

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

Explicitly advises use for broad/multi-part questions and alternative `ask_pipeworx` for single lookups. Also mentions prerequisites (Pipeworx account, paid plan for thorough depth).

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

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

Annotations already provide safety hints (readOnly, idempotent, not destructive), so the bar is low. The description adds value by specifying the return fields (geometry, distance, duration, voice+banner instructions, alternatives) and the data source (Mapbox commercial traffic data), which goes beyond the structured fields.

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

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

The description is a single paragraph with front-loaded examples and clear structure, but it could be slightly more concise by separating output details from usage examples. Nonetheless, it remains efficient and easy to read.

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 10 parameters and no schema descriptions, the description provides a high-level overview but neglects to explain many parameters like 'overview', 'geometries', 'annotations'. However, the presence of an output schema reduces the need to explain return values, making the description adequate but not complete.

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

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

Schema description coverage is 0%, leaving all 10 parameters undocumented. The description mentions only a few parameters implicitly (profile, steps, language, alternatives, voice_instructions, banner_instructions) but does not explain their purpose or valid values. With such low coverage, the description fails to adequately 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 clearly states it provides turn-by-turn routing between coordinates, listing specific outputs (geometry, distance, duration, instructions, alternatives) and profiles. Example queries show natural language use cases, effectively distinguishing from sibling tools like 'directions_matrix' which likely handles multiple origins/destinations.

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 example natural language prompts and mentions supported profiles (driving, walking, cycling), giving clear context for when to use the tool. However, it does not explicitly exclude usage or compare to alternatives like 'directions_matrix', so it's not 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 read-only, idempotent, non-destructive behavior. The description adds that the output is a matrix of distances and durations, which is consistent and adds specificity.

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

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

The description is a single, efficient sentence with aliases and use cases. No superfluous content.

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

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

Despite strong annotations and output schema, the description omits parameter semantics, which are critical for correct invocation of a matrix tool with 5 parameters. The use cases are helpful but do not fully compensate.

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 does not explain any of the 5 parameters (e.g., meaning of 'sources', 'destinations', 'profile'). The examples in the schema provide limited clues, but the description lacks direct parameter 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 provides multiple aliases and explicit use cases (traveling-salesman, delivery routing, etc.) clearly distinguishing the tool from siblings like 'directions' and 'isochrone'.

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

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

The description explicitly lists appropriate use cases, but does not mention when to avoid it or suggest alternative tools for single-route queries.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which align with the description. The description adds value by stating that results 'include names, descriptions, and full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed,' providing behavioral context 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 reasonably concise but slightly verbose with the long list of domains. The main action is front-loaded, but some repetition could be trimmed. Effective overall.

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 discovery tool with a well-specified input schema and clear annotations, the description covers what it returns (tools with schemas and examples) and how to use it. No output schema exists, so the description appropriately explains the return value. It is complete enough for an agent to use correctly.

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

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

The input schema has 6 parameters (with aliases) and 100% schema description coverage, so the description doesn't need to add much. It mentions 'top-N' but doesn't elaborate on parameter details beyond what the schema provides, which is adequate.

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

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

The description clearly states the purpose: 'Find tools by describing the data or task.' It lists numerous specific domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes from sibling tools by framing itself as the discovery tool to call first.

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

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

The description provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It gives concrete examples of when to use it (e.g., 'analyze housing market trends'). While it doesn't explicitly state when not to use it, the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about internal fan-out across multiple sources, the inclusion of specific return fields (e.g., recent_filings with URIs, fundamentals), and a soft-fail notice for patents. 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 but well-structured, front-loading example queries and a clear action verb. Every sentence adds value—purpose, usage preference, data sources, return details, and limitations. Slightly verbose due to listing all sources and fields, but effective for a complex tool.

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

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

With no output schema, the description must explain return values, and it does: lists cik, company_name, recent_filings (with URIs), fundamentals (specific fields with ordering), patents (with caveat), news, and LEI. Covers major aspects but omits details like whether fundamentals are multi-year; still very complete for the tool's complexity.

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

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

Schema coverage is 100%, with both 'type' and 'value' described. The description reinforces that 'value' accepts ticker or zero-padded CIK and that names are unsupported, adding practical usage constraints beyond the schema's basic description. This adds meaningful guidance for parameter selection.

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 example queries ('Tell me about X', 'research Acme'), states the tool returns a 'full cross-source profile of a US public company', and lists specific data sources and returned fields. It explicitly distinguishes itself from single-pack lookups, 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 states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' directly guiding when to use. It also notes that names are not supported and instructs to 'use resolve_entity first if you only have a name,' providing clear when-not-to-use guidance with an alternative sibling tool.

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

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

Annotations already indicate destructiveHint (true) and idempotentHint (true). Description adds useful context about clearing sensitive data and stale context, but does not elaborate on irreversible behavior beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with purpose, followed by usage guidance. No redundant or filler content. Every sentence earns its place.

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

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

Given the simple tool (1 required param, no output schema, good annotations), the description is fully complete: explains what, when, and how to use.

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

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

Schema covers the single parameter fully (100% description coverage) with a clear description 'Memory key to delete'. Description doesn't need to add much; the example in schema provides context. Baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key.' Verb (delete) and resource (memory by key) are specific. Clarifies scope by distinguishing from sibling tools 'remember' and 'recall'.

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

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

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

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the process: fetches page, extracts title/description/key links, emits standard format. 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 concise, well-structured with clear sections: purpose, process, output, use cases. Every sentence adds value with no redundancy.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, process, output format, and use cases. It is complete enough without needing to explain error handling or edge cases.

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

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

Schema coverage is 100% and description does not add significant meaning beyond schema. It mentions 'Full URL' and 'Maximum number of link entries' but essentially repeats schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file for any URL', and the purpose for AI crawlers. It is specific and distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on file generation.

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

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

The description lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor). It provides context but does not explicitly tell when not to use or mention alternatives. Still, it offers good situational guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that it uses Mapbox's global geocoder, but does not cover rate limits or other behavioral details. 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 concise and front-loaded with user query patterns, followed by a clear explanation and code example. Every line adds value, though it could be slightly more structured.

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

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

Given 9 parameters and no schema descriptions, the description is incomplete. It only covers the query parameter, leaving the other 8 parameters unexplained, which is insufficient for a tool with 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%, meaning parameter descriptions are missing. The description only mentions the 'query' parameter implicitly via example, and does not explain other parameters like bbox, limit, types, country, language, proximity, fuzzyMatch, autocomplete.

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 addresses/places to GPS coordinates, with explicit example queries and a code example. It distinguishes from the sibling geocode_reverse by focusing on forward 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 example query patterns and states it works on various location types worldwide. It could explicitly mention when to use reverse geocoding instead, but the context is clear enough.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds no additional behavioral traits such as accuracy, rate limits, or coverage details. It is sufficient but does not go 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 single, front-loaded sentence that effectively conveys the core functionality with example queries. It is concise and readable, though it could benefit from a slightly more structured breakdown for optional parameters.

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

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

Given the tool's complexity (6 parameters, simple reverse geocoding) and the presence of an output schema, the description is adequate but not fully complete. It covers the primary inputs but omits details on optional parameters and their effects. The input schema examples partially compensate.

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?

Despite having 6 parameters and 0% schema description coverage, the tool description only explains 'lat' and 'lon' implicitly. Parameters like 'limit', 'types', 'country', and 'language' are not described, leaving ambiguity for the agent. The examples in the schema provide some context, but the description fails 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 clearly states the tool's purpose: reverse geocoding coordinates into addresses/places. It provides example queries and specifies the source (Mapbox global geocoder), distinguishing it from the sibling tool 'geocode_forward'.

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 is implied by the examples and context of reverse geocoding, but there is no explicit guidance on when to use this tool versus alternatives like 'geocode_forward' or other spatial tools. No prerequisites or limitations are mentioned.

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 destructiveHint, so the agent knows it's safe. The description adds that the tool returns polygons and the types of travel (car, walking, cycling). It does not contradict annotations and provides additional context beyond the structured fields.

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

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

The description is front-loaded with example queries and use cases, making it efficient. It could be slightly more concise but every sentence adds value, balancing detail with readability.

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

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

Given the tool's complexity (8 parameters, low schema coverage, output schema exists), the description covers the main purpose, typical parameters, and use cases. It could clarify the relationship between contours_minutes and contours_meters, but overall it is sufficiently complete.

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

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

Schema description coverage is only 13%, but the description adds meaning for key parameters like coordinates, profile, contours_minutes, and contours_meters through examples and text. However, parameters like denoise, generalize, and polygons are not explained, so coverage remains incomplete.

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 generating isochrone polygons from a starting coordinate, with explicit use cases like site-selection and commute-shed analysis. It distinguishes itself from siblings such as directions and map_matching by focusing on reachable area polygons.

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 with examples of when to use the tool (e.g., delivery-zone, catchment analysis). It does not explicitly state when not to use it or list alternatives, but the implied usage is strong.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by specifying the returned fields and the default behavior (active subscriptions only) with the include_inactive parameter to toggle canceled ones. 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 two sentences, efficiently front-loaded with the return value and usage guidance. Every sentence provides essential information without redundancy.

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

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

Given the tool's simplicity (one optional boolean parameter, no output schema, and comprehensive annotations), the description fully covers the purpose, behavior, and usage context. It explicitly lists return fields, compensating for the lack of an output schema.

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

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

The schema provides complete description (100% coverage) for the single boolean parameter 'include_inactive'. The description implicitly reinforces the default behavior by mentioning 'active subscriptions', but does not add new meaning beyond the schema's explicit description. 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 it lists the caller's active subscriptions, specifying the returned fields (id, type, params, etc.). It distinguishes itself from sibling tools like subscribe and unsubscribe by being a read-only listing tool.

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

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

The description explicitly advises when to use it: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for appropriate usage and implies when not to use (e.g., when modifying subscriptions).

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it returns the most likely path, which complements the behavioral context. No contradictions.

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

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

The description is very concise: a lead-in of synonyms followed by two sentences. It front-loads the core action and keeps every sentence useful.

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

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

Given the complexity (9 params, 0% schema coverage), the description covers overall purpose and use cases but lacks details on parameter effects and output schema. Output schema existence partially compensates, but more parameter guidance would improve completeness.

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

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

Schema description coverage is 0%, so the description carries the burden. It only describes coordinates implicitly as 'sequence of GPS points' but does not explain other 8 parameters like profile, steps, etc. Examples partially illustrate usage but lack semantics.

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 snaps GPS traces to roads, matches tracks to road network, and provides synonyms like 'clean up noisy GPS coordinates'. It distinguishes from siblings like directions or geocoding by focusing on sequential point matching.

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 specific use cases (vehicle telematics, fitness-tracker cleanup, road identification) which imply when to use. However, it does not explicitly state when not to use or compare to alternatives like directions.

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

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

Discloses rate limit (5 per identifier per day), cost (free, no quota count), and impact (team reads daily, affects roadmap). Annotations default to false, so description carries full behavioral burden and does so thoroughly.

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

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

Single paragraph, four sentences, front-loaded with purpose. Every sentence earns its place—purpose, usage, constraints, and behavioral rules. Zero wasted words.

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

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

Covers purpose, usage, parameters, constraints, and organizational impact. No output schema but return value is likely a simple acknowledgement; description suffices for agent decision-making. Could briefly mention return type but not required.

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 with descriptions. Description adds value by specifying message length (1-2 sentences, 2000 char max) and reinforcing context guidelines. Exceeds baseline 3 by not merely repeating 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?

Describes a specific verb ('Tell') and resource ('the Pipeworx team') with clear categories (bug, feature, data_gap, praise). Uniquely distinguishes from siblings as the only feedback tool.

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

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

Explicitly states when to use (bug, feature, data_gap, praise) and provides content guidelines (describe in terms of tools/packs, don't paste user prompts). No direct alternative mentioned, but the tool's uniqueness makes that less critical.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds beyond: no PII, derived from CF analytics-engine, caching 5min-1h. No contradictions.

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

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

Four sentences, front-loaded with purpose, then use cases, then data source and caching. Every sentence adds value; no redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema), the description fully covers functionality, windows, use cases, data source, privacy, and caching. Complete and self-contained.

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

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

Schema coverage is 100% and the enum values are described in the description (24h default, shorter windows surface what's hot, longer show steady-state demand). Adds semantic guidance beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window (24h, 7d, 30d). It differentiates from siblings like 'discover_tools' by focusing on trending data and call volume.

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

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

Provides three explicit use cases: discovering hot data sources, confirming a popular tool is canonical, and seeing if your use case aligns with most agents. Mentions caching behavior and what different windows surface.

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

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

Discloses details like monotonicity checks, partition_sum, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder drops), fill check with live CLOB depth, and conditions when not to trade. Annotations (readOnly, openWorld, idempotent) are consistent; description adds significant behavioral context beyond annotations.

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

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

The description is lengthy but front-loaded with the critical requirement (one of event/topic). Well-structured with separate sections for modes, constraints, response format, and fill check. Every sentence adds value, though could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains the response structure (opportunities[] with gap_pp, suggested_trade, etc.), fill check behavior, and references sibling tool for custom sizing. Covers prerequisites, constraints, and caveats, making it 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 covers 100% with good descriptions for `event` and `topic`. The description adds substantial context about how each mode operates internally (walking child markets, searching, flattening, comparator), which enhances understanding beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between single-event (`event`) and cross-event (`topic`) modes, which are unique among sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly requires one of `event` or `topic`, warns call with no args fails. Recommends `event` for specific markets and `topic` for cross-event scanning, noting cross-event catches patterns single-event misses. Also directs to polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint (all safe). The description adds extensive behavioral detail: caching at KV-level, model families, filtering logic, diagnostics, and knobs. 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 quite long and dense, packing a lot of information into a single paragraph. While it front-loads the purpose, the lack of structure (e.g., bullet points or sections) reduces readability.

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

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

Given the complexity (9 parameters, three segments, diagnostics), and no output schema, the description thoroughly explains the response structure, including edge cases (e.g., empty segments) and diagnostics. It covers the necessary context for an agent to use the tool effectively.

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

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

Schema coverage is 100% with each parameter already described. The tool description does not add significant new semantic meaning beyond these existing descriptions; it focuses on model and segment 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 states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market prices. It specifies the intended use case ('what should I bet on today') and distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description explicitly frames the tool as a daily opportunity scanner, providing guidance on when to use it (e.g., discover opportunities without paging hundreds of markets). It also discusses caching and knob usage. However, it does not explicitly state when not to use it or compare with alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details beyond annotations: 60-day snapshot TTL, cache-miss-driven snapshot creation, and gaps in data. No contradictions.

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

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

The description is a single paragraph but well-structured: starts with the core question, then details response fields and limits. It is relatively concise given the complexity, though slightly 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?

Despite no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and limitations. It covers all necessary aspects for an agent to use the tool correctly.

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

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

Input schema has 100% coverage, so baseline is 3. The description adds context for 'window' as 'snapshot family' and notes default and clamp for 'days', providing meaning beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry. It uses a specific question ('how long has this edge existed and is it shrinking?') to convey the function. It distinguishes from the sibling tool 'polymarket_edges' by focusing on historical time-series rather than just current edges.

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

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

The description gives contextual guidance by contrasting a fresh wide edge with a 3-week-old wide edge, implying when to use the tool for historical decay analysis. However, it does not explicitly state alternatives or 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 mark it as readOnly, idempotent, not destructive. Description adds details about walking the ladder, return verdict (clean|degraded|cannot_fill), and forced directional risk warnings. 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?

Structured with headings (REQUIRES, SINGLE-MARKET, BASKET) and a usage note. Somewhat long but each sentence adds value. Could be slightly tighter but 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?

Covers all 4 parameters, both modes, defaults, and critical warnings (partial fills, directional risk). No output schema but return fields are described. Complete for agent to decide when and how to use.

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

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

Schema coverage is 100% (baseline 3). Description adds context: side defaults and interpretations for both modes, size_usd meaning for buys vs sells, and basket size_usd as settlement notional. This exceeds schema information.

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

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

Clearly defines as realizable-vs-theoretical edge check against live order-book depth. Specifies two modes (single-market and basket) and lists return fields (top_of_book, vwap_fill_price, etc.), distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable, partial fills create directional risk). Also notes requirement for one of market or event.

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

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

Annotations already indicate readOnly, openWorld, idempotent. The description goes further by detailing compatibility warnings (bet shape mismatches, temporal misalignment), skipped cross-type/subtype counters, and when spreads are meaningless. This adds significant behavioral context beyond annotations.

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

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

The description is verbose but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. Minor redundancy could be trimmed, but overall it's appropriate for the complexity.

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

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

No output schema exists, so the description compensates by detailing the response structure (leg-by-leg prices, spread array, safety fields). It covers return values, edge cases, and error conditions (compatibility_warning), making it fully actionable.

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

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

Schema coverage is 100%, and the description adds value by listing the 10 pre-mapped shortcuts for the 'topic' parameter and explaining how explicit tickers override the mapped side. It clarifies that not all topics yield meaningful spreads.

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 cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes and distinguishes the tool from siblings like polymarket_arbitrage by mentioning 'real signal' vs 'no arb exists' scenarios.

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

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

The description provides explicit guidance on when to use topic shortcuts vs explicit tickers, and warns about compatibility and temporal alignment issues. However, it does not directly compare to sibling tool polymarket_arbitrage, which could cause confusion.

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

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

Adds scoping details (anonymous IP, BYO key hash, account ID) and pairing with remember/forget beyond annotations that already declare read-only, idempotent, non-destructive. 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?

Three sentences, no wasted words, purpose front-loaded, 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?

Complete for a retrieval tool with one optional parameter and no output schema; covers behavior, scoping, and sibling relationships.

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

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

Schema coverage is 100%; description repeats schema's note that omitting key lists all keys, adding no new meaning beyond what schema provides. Baseline 3 appropriate.

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

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

Clearly states it retrieves a value saved via remember or lists all keys if omitted. Distinguishes from sibling tools (remember, forget) by naming them explicitly.

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

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

Explicitly advises when to use (look up stored context) and implicitly when not (saving uses remember, deleting uses forget). Also notes scoping to identifier.

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

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

Description discloses mark_read:true flags events as read (a write side-effect), but annotations declare readOnlyHint=true, which implies no state change. This is a direct contradiction, hence score 1 as per guidelines.

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

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

Concise paragraph with about 80 words, front-loaded with the core action. Every sentence adds distinct information without repetition or fluff.

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

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

Despite the absence of output schema, description sufficiently covers what is returned (fields like source, citation_uri, raw payload). Also describes filtering, mark_read implications, and alternative access. No gaps for a read-oriented tool with 5 optional parameters.

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

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

Schema already covers all parameters with descriptions (coverage 100%). Description adds value by providing concrete examples (e.g., 'sec_8k' for type), explaining mark_read behavior, and specifying ISO format for since. This enriches the schema information.

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

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

Clearly states the tool pulls fired events from the subscription feed, sets scope to 'most recent alerts', and lists typical fields returned. Distinct from sibling tools like list_subscriptions which manage subscriptions, not alerts.

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

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

Describes when to use with optional filters (type, since, unread_only) and side-effect of mark_read. Mentions polling is fine and gives an alternative HTTP endpoint for scripts. However, does not explicitly contrast with other tools like subscribe or unsubscribe.

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 signal readOnly, not destructive, and idempotent. The description adds substantial detail: it fans out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), explains fallback logic, soft-failure for USPTO, and describes the return structure including citation URIs.

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

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

The description is front-loaded with example queries and is information-dense without unnecessary words. It is slightly lengthy but every sentence adds value, justifying the length.

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

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

Despite no output schema, the description clearly explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It covers all relevant behavioral details: sources, fallback, date formatting, parameter guidance, and sibling tool differentiation.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining accepted date formats (ISO or relative) with examples, accepting ticker or zero-padded CIK, and recommending '30d' or '1m' as default for since.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with specific examples of queries. It explicitly distinguishes from sibling tool entity_profile, which handles static profiles regardless of time window.

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 example usage patterns and explicitly contrasts with entity_profile. It also explains fallback behavior between GDELT and GNews. However, it doesn't specify when not to use it beyond the entity_profile case, though the differentiation is strong.

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

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

Annotations indicate write, idempotent, non-destructive. Description adds persistence details (authenticated vs anonymous, 24h) and scoping by identifier, going beyond annotations. No contradiction.

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

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

Four sentences, no wasted words, front-loaded with purpose, then usage, then technical details. 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?

For a simple 2-param tool with no output schema, description covers purpose, usage, behavior, persistence, and sibling context. Complete and sufficient.

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

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

Schema coverage 100% with detailed parameter descriptions. Description adds context ('Save data...') but no additional parameter-level meaning beyond schema.

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

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

Description clearly states verb 'save' and resource 'data the agent will need to reuse later', defines key-value pair scoped by identifier, and distinguishes from sibling tools recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and mentions pairing with recall and forget. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that internal calls cascade through multiple endpoints, replacing 2-3 manual lookups, which provides valuable behavioral context beyond annotations.

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

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

The description is front-loaded with clear examples and structured information. It is concise without being terse, and every sentence adds value. Could be slightly more structured with bullet points, but overall good.

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

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

Given no output schema, the description thoroughly covers what is returned for each entity type, including citations and auto-disambiguation. It also explains the tool's efficiency, making it complete for the agent to understand expectations.

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

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

Schema coverage is 100% and description adds extra meaning: for 'type', it details what each returns; for 'value', it provides examples and mentions auto-disambiguation. This adds significant value beyond the schema.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, with specific examples like ticker, CIK, RxCUI. It distinguishes itself from siblings by indicating other tools require these IDs as input.

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 FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It also lists supported types (company, drug) and what each returns, but does not explicitly mention when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context: it probes each entity with 'ai_visibility_check' and returns a ranked list with score, confidence, and signal density. No contradictions.

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

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

The description is three sentences with no redundant information. It is front-loaded with the primary action and efficiently communicates purpose, usage, and output.

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

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

Despite lacking an output schema, the description sufficiently explains the return structure (ranked list with score, confidence, signal density). For a comparison tool with clear annotations, this is complete.

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

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

Schema description coverage is 100%, but the description adds value by explaining that the first entity is treated as the 'subject' for narrative and that models parameter has options. This enriches meaning beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, ranks by score, and identifies most/least recognized. It uses specific verbs ('compare', 'probes', 'ranks', 'surfaces') and distinguishes from similar sibling tools like 'compare_entities' by focusing on AI presence.

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. While it doesn't explicitly state when not to use, the sibling context (e.g., 'ai_visibility_check' for single entities) helps differentiate.

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

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

Discloses graceful partial failures, bundlephobia latency (5-30s), and return structure (summary, advisories, links, alternatives). Adds value beyond annotations which already declare read-only and idempotent 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?

Though lengthy, the description is well-structured with front-loaded purpose, usage guidance, return info, and edge cases. Each sentence adds value; slight tightening possible but highly informative.

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

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

Given complexity (composite tool, no output schema), description thoroughly covers return structure, external sources, partial failure behavior, and ecosystem scope. No gaps for effective tool selection and invocation.

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

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

Schema already describes both parameters with 100% coverage. Description adds minimal extra meaning (e.g., version defaults to latest), but mostly repeats schema info. Baseline 3 is appropriate as no significant semantic enhancement.

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

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

Description clearly states it is a composite check for assessing npm packages, specifying verb ('scan'), resource ('npm package'), and scope ('safety, popularity, size'). Distinguishes from siblings by limiting to NPM ecosystem and mentioning alternatives for other ecosystems.

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

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

Explicitly describes when to use (agent questions about safety/popularity/size) and when not to (other ecosystems via deps.dev directly). Provides clear context and alternatives.

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

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

Adds specific technical details beyond annotations: BGE-base-en embeddings, 500-char windows, 200K char limit with truncation flag, and offset for verification. Annotations already cover readOnly/idempotent, so description adds significant behavioral context.

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

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

Well-structured: purpose first, then usage guidance, then technical details. Every sentence provides unique information. No redundancy or fluff.

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

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

Despite no output schema, description explains return format (passages with offsets and scores) and behavior (truncation flag). Pairs with sibling tool. Complete for a read-only search tool with few params.

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

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

Schema has 100% coverage with descriptions. Description adds value by giving natural-language query examples, specifying default limit (5), and reiterating the character cap. Enhances understanding beyond schema alone.

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

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

Description clearly states 'semantic search INSIDE a fetched record' with specific verb and resource. Differentiates from siblings by naming ask_pipeworx_grounded and explaining the fetch-then-search workflow.

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 to use when record is too large for the prompt, saving context. Provides example (SEC 10-K). Implicitly suggests not using for small records. Lacks explicit when-not-to-use but still strong.

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

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

Annotations already declare readOnly, openWorld, idempotent; description adds the output is a fetchable PNG URL and no client-side JS required, complementing the annotations without contradiction.

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

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

Single sentence front-loading use cases and purpose, no wasted words, easy to scan.

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

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

Given 9 params and output schema exists, description covers primary parameters and output type; examples in schema supplement missing detail.

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 0% description coverage; description mentions style, coords, zoom, width/height but omits pitch, retina, bearing. It gives a high-level pattern but insufficient detail for all 9 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 it generates a Mapbox static-tile image URL for embedding, listing specific use cases (static map, embed, screenshot, thumbnail) and differentiating from interactive map tools among siblings.

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

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

Provides clear context for when to use (embedding in slack, docs, emails, dashboards) and implies use when no interactivity is needed, but does not explicitly exclude alternatives or mention when not to use.

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

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

The description discloses important behavioral traits beyond annotations, such as OAuth requirement, return of subscription id, specific type examples, delivery constraints (SMS cap, webhook auto-disable), and always-on feed. This adds significant 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 dense but well-structured, with clear sections for types and delivery channels. Every sentence adds value, and it is front-loaded with the core purpose. No wasted words.

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

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

Given the complexity of the tool (3 parameters, nested objects, no output schema), the description is complete. It covers requirements, return value, all supported types and delivery options, and specific constraints, leaving no gaps for an agent.

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

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

Despite 100% schema coverage, the description adds substantial meaning with detailed examples for each 'type' and 'delivery' parameter, including item codes, topic parameters, and webhook signing secret. This goes well beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description specifies the requirement for a Pipeworx OAuth account and lists supported types and delivery channels, providing clear context for when to use. It also contrasts with 'recent_alerts' for reading alerts, though not exhaustive.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds context as the onboarding entry point and what it returns (example questions with tool shapes). No contradictions, but little extra behavioral detail 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 well-structured with front-loaded key info and a list of topics. It is slightly verbose but each sentence adds value. Could be trimmed slightly while retaining clarity.

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

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

Given the tool has one optional parameter, rich annotations, and no output schema, the description fully covers purpose, usage context, parameter behavior, and expected output (example questions with tool shapes). No gaps.

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

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

Schema has 100% coverage with one optional parameter. Description adds value by explaining omission gives cross-category spread and listing specific topic focus areas (finance, pharma, etc.), going beyond the schema's brief description.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself as the onboarding entry point for new agents, mentioning specific meta-tools like ask_pipeworx and entity_profile for learning.

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

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

The description explicitly says to use this tool FIRST when uncertain about Pipeworx capabilities or to learn how to call meta-tools. It explains optional topic parameter behavior. However, it does not explicitly state when not to use it or provide alternatives for other scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. Description adds context that it's a specialized GIS query using vector tiles, which complements annotations without contradiction. No rate limit or auth details mentioned, but acceptable given annotation coverage.

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

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

Two sentences, front-loaded with purpose and usage guidance. Every word adds value; no filler.

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

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

Given 8 parameters and specialized nature, description covers purpose and usage well, but parameter semantics are incomplete. Output schema exists but is not elaborated. Overall sufficient for an experienced user with annotations and examples.

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%, so description must explain parameters. It implies lat, lon, radius, layers, and tileset_id but does not explicitly define each parameter's format or constraints. Examples in schema provide some help, but description lacks direct parameter documentation.

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

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

Description clearly states it queries features inside a Mapbox vector tile at a coordinate, listing specific feature types (POIs, roads, boundaries, buildings). It distinguishes from sibling tools by explicitly saying most users want geocode_reverse or directions instead.

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

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

Explicitly states when to use (specialized GIS query against a specific tileset_id) and when not to (most users want alternatives), providing clear context for selection.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds critical detail: the row is deactivated not deleted, and historical events remain available via recent_alerts. This clarifies the tool's side effects and lifecycle impact.

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 efficiently convey purpose, ownership, and behavioral effect. Every sentence adds value with no redundancy. Front-loaded with the verb and resource.

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

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

For a simple tool with one parameter, the description adequately covers purpose, ownership, and behavior. It could optionally mention the return type, but given no output schema and idempotent hint, this is not critical.

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

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

Schema coverage is 100% and the schema already describes the 'id' parameter as a UUID from subscribe. The description adds only 'by id', which does not enhance meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses the verb 'Cancel' and resource 'subscription', clearly distinguishing from siblings like 'subscribe' (creation) and 'list_subscriptions' (listing). The action and scope are unambiguous.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when the tool is applicable. It lacks explicit mention of alternatives or when not to use, but the ownership constraint serves as a strong guideline.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds detailed behavioral info: the return value structure (verdict with categories, extracted form, actual value, citation, delta) and the data source (SEC EDGAR + XBRL). No contradiction with annotations.

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

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

The description is front-loaded with example queries and concise phrases. Every sentence adds value: usage context, return values, efficiency claim, and domain scope. No wasted words.

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

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

Given no output schema, the description thoroughly explains the return value format (verdict categories, extracted structure, citation, delta). It also covers the domain limitation and parameter semantics, making it complete for an agent to use.

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

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

Schema description coverage is 100% with a clear parameter description and examples. The tool description essentially repeats this, adding no new semantic meaning. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources. It provides specific example queries and states it replaces multiple sequential calls, distinguishing it from siblings like ask_pipeworx_grounded.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims) and notes efficiency gains, though it does not name specific alternative tools for when not to use.

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