Google_maps

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds important behavioral context: default model is free, passing _apiKey enables Anthropic probing with direct billing, and returns per-model fields. No contradictions.

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

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

Three sentences, front-loaded with the core action, no wasted words. Each sentence earns its place: purpose, model options, return format, and use cases.

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 explains return structure per model and combined view. All 4 parameters are well-documented in schema and description. Use cases are clearly stated, making the tool complete for an agent to decide and invoke.

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% parameter descriptions, so baseline is 3. The description adds value beyond schema by explaining billing implications for _apiKey, default model selection, and the return format (score, confidence, signals, raw_response). This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility 0-100. The verb 'probe' and resource 'LLMs' are specific, and the tool is well-differentiated from sibling tools like deep_research or ask_pipeworx by focusing on AI visibility and scoring.

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 usage context: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains default behavior and optional anthropic probing. However, it does not explicitly contrast with sibling tools or state when not to use it, though the unique purpose makes this 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context beyond these: it routes to 5,529 tools, returns stable pipeworx:// citation URIs, works on every tier, and makes only one fast call. It does not contradict annotations, and the additional operational details give the agent a clearer picture of the tool's behavior.

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

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

The description is long but every sentence serves a purpose, front-loading the core 'PREFER OVER WEB SEARCH' message and then layering alternatives, examples, and context. It is well-structured with clear signposts ('START HERE', 'Step up only when needed'), though it could be trimmed slightly without losing essential guidance.

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

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

For a complex tool with many siblings and aliases, the description is remarkably complete. It explains scope (which domains it covers), behavior (routing, citations), usage context (works on every tier, fast), and provides exclusions for alternatives. It even addresses breaking-news use cases. Despite lacking an output schema, the description states the return format sufficiently.

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

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

The input schema already covers all parameters at 100%, with question and its aliases described. The description adds value by providing concrete examples of valid questions ('current US unemployment rate', 'Apple's latest 10-K'), which illustrate the expected natural language format and scope. This goes slightly beyond the schema's generic 'Your question or request in natural language'.

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

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

The description clearly states the tool's function: it routes questions to one of 5,529 tools across 1,455 sources and returns structured answers with citations. It uses specific verbs ('routes', 'returns') and differentiates from siblings by naming alternatives like ask_pipeworx_grounded and deep_research, as well as explicitly positioning itself as the default entry point.

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

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

The description provides explicit when-to-use guidance, starting with 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also gives clear when-not-to-use instructions by naming alternatives: 'use ask_pipeworx_grounded' for hallucination-resistant answers and 'use deep_research' for multi-part questions. This distinguishes it from siblings effectively.

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 a non-destructive, read-only, idempotent operation. The description adds valuable context about the beta nature, live candidate testing status, and that it currently matches ask_pipeworx exactly. It also clarifies that it is a full working router, not a stub, and explains how results are compared to the stable router. This goes beyond the annotations by describing the operational state and testing methodology.

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

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

The description is three sentences, front-loaded with the core identity ('Beta version of ask_pipeworx'). It efficiently explains the relationship to the stable tool, current experimental status, and usage guidance. The inclusion of specific details like '5,529 tools' and the retirement date adds credibility and context without bloating the text. No unnecessary fluff, though the final sentence 'Falls back to nothing' could be slightly clearer.

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 and the presence of rich annotations, the description covers all critical aspects: what it is, how it differs from stable, current state, usage, and comparison behavior. It does not describe return values, but since it explicitly states the response shape is identical to ask_pipeworx, and no output schema exists, this is sufficient for an experimental variant. It might benefit from linking to ask_pipeworx docs, but is complete for its purpose.

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

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

The input schema already provides 100% coverage of all 6 parameters, each documented as an alias for 'question'. The description says 'same arguments' as ask_pipeworx, but does not add additional semantics beyond what the schema already covers. Since the schema fully documents the parameters, the description does not need to repeat them; 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 this as a beta version of ask_pipeworx with identical routing capabilities, explicitly noting it replicates all 5,529 tools, same arguments, and same response shape. It distinguishes itself from the stable ask_pipeworx by highlighting its experimental routing improvements and current status, so there is no ambiguity about its role.

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 to 'use it exactly like ask_pipeworx when you want the newest routing', establishing a clear condition for when to choose this tool. It also implies that stable behavior would come from ask_pipeworx, though it does not explicitly name that as the alternative for non-experimental use. This is strong guidance without being 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?

The description adds substantial behavioral detail beyond annotations: it guarantees extraction 'using ONLY what the tool result contains,' defines the success return shape with evidence and confidence, and enumerates explicit refusal reasons. Annotations already declare read-only, idempotent, non-destructive behavior, and the description does not contradict them. It also discloses the extra LLM call cost, providing complete transparency.

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

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

The description is dense but well-structured, opening with a purpose summary, then mechanics, return format, use cases, and cost comparison. Every sentence provides distinct value, with no repetition of schema fields. It earns maximum points for efficiency.

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

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

The tool is complex (routing across 5,529 tools) with no output schema, but the description fully covers return values, refusal reasons, and use guidance. It mentions the exact response shape and error categories, and includes cost/performance trade-offs. The combination of schema, annotations, and description leaves no major gaps.

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

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

The description does not add parameter-level meaning; it only refers to a 'question' implicitly. Input schema coverage is 100%, with each of the 6 parameters documented as aliases for 'question' and the question description already stating the accepted aliases. Per baseline for high schema coverage, the description need not repeat this.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains its routing and extraction process. It explicitly distinguishes itself from sibling ask_pipeworx by noting the grounded extraction and refusal behavior. This gives the agent a specific verb+resource and differentiates it from similar tools.

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

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

The description states exact conditions for use: 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains (financial verdicts, legal claims, medical lookups). It also provides an explicit alternative: 'prefer ask_pipeworx for casual lookups,' and notes the extra LLM call cost. This is exemplary when/when-not guidance.

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

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

The description extensively details behavioral traits beyond the annotations. It explains the fan-out process, response shapes, resolver contract (confidence levels, alternatives, suggestions), parent event extraction, news fallback, safety mechanisms (low-confidence short-circuit, closed market handling), wide spread warnings, and resolution-rule risk. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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 long (multiple paragraphs) and contains extensive detail, which can be overwhelming. However, it is well-organized with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that improve scannability. The first sentence effectively states the core purpose, but the overall length exceeds what is typically concise.

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

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

Given the tool's complexity (3 parameters, no output schema, numerous behavioral considerations), the description is highly complete. It covers input options, output structure, edge cases (low confidence, closed markets, wide spreads), fan-out examples, and even resolution-rule risk. No missing essential information.

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 covers all three parameters with descriptions, and the tool description adds significant context: for 'market', it explains acceptable formats (slug, URL, question text) and includes examples; for 'depth', it defines 'quick' vs 'thorough'; for 'include_raw', it clarifies when to use true vs false and the impact on response size. This goes beyond the schema's simple descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb ('research'), the resource ('Polymarket bet'), and the method ('pull Pipeworx data'). The description also provides example use cases and differentiates from sibling tools by highlighting its comprehensive fan-out and evidence packet return.

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

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

The description explicitly says when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear usage scenarios but does not explicitly state when not to use it or identify alternative tools for different contexts. However, given the sibling tools list, the guidance is sufficient for typical 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 show readOnly, openWorld, idempotent, and non-destructive. The description adds useful context: handles off-calendar fiscal years correctly, sorts results by primary metric, returns citation URIs. 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 well-structured and front-loaded with examples and preference statement. Every sentence adds value, though it 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?

Covers key aspects: entity types, data sources, sorting, return format (paired data + citation URIs). Lacks mention of error handling or missing data, but otherwise complete for a tool with no output schema.

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

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

Schema coverage is 100%. The description adds meaning beyond the schema: explains what data is pulled for each type, gives examples and constraints for values (tickers/CIKs, drug names, min/max).

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 2-5 companies or drugs side-by-side, lists example queries, and specifies the data pulled for each type. It distinguishes itself from sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives examples of when to use. However, it does not explicitly mention when not to use it or alternatives like entity_profile for single entities.

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

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

The description discloses extensive behavior beyond the annotations: account/plan prerequisites, decomposition into facets, parallel routing, the exact contents of the findings packet (verbatim evidence, confidence, source, fetched_at, citations), explicit gaps[] never invented, depth-specific behaviors (gap recovery, contradictions[], hop field), and expected latency. This goes far beyond what readOnlyHint/openWorldHint/idempotentHint convey.

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

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

The description is long but information-dense, with every sentence contributing unique value. It is logically structured: prerequisites and alternatives first, then core functionality, use cases, depth details, and performance expectations. Despite its length, it is partitioned clearly and front-loads the most operationally critical facts (account requirement, use ask_pipeworx instead when appropriate).

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

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

There is no output schema, so the description carries the full burden of explaining the return value. It thoroughly describes the findings packet, gaps[], contradictions[], hop field, citation_uri, excerpting of large records, and timing. It also addresses edge cases like sign-in state and breaking news. The description is complete for the tool's complexity and rich parameterization.

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

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

Although schema_description_coverage is 100%, the description adds crucial semantic depth to both parameters. It elaborates the depth values ('standard' re-angles unanswered gaps; 'thorough' chases leads and requires paid), and it explains that the question parameter accepts broad/multi-part questions because decomposition is the point. This enriches the parameter semantics significantly.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It explicitly distinguishes from siblings by stating 'this is NOT open-web search' and contrasts with ask_pipeworx. Clear examples of use cases ('compare X and Y's regulatory + financial exposure') anchor the purpose.

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

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

Explicit when-to-use vs alternatives: 'Best for broad/multi-part questions over structured data'; 'For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'; also tells users to use ask_pipeworx if not signed in. This directly addresses tool selection relative to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing that results include full input schemas and are ready to call directly, without contradicting annotations.

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

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

The description is a single paragraph but packs purpose, usage, and output details efficiently. It front-loads the key verb and resource, with 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 explains what is returned (names, descriptions, full schemas) and when to use. It lacks details on error handling but is sufficient for a discovery tool.

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

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

Schema coverage is 100%, and the description clarifies that q, task, search, description are aliases for query, adding semantic meaning beyond the schema. Also explains the limit parameter.

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

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

The description clearly states 'Find tools by describing the data or task' and lists specific domains. It distinguishes itself from siblings by emphasizing discovery and calling first to see options, making the purpose highly specific and differentiated.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST...' It provides clear context and implies when not to use (when you already know the tool), but lacks explicit exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds operational details: multi-source fan-out, soft-fail for patents, fallback news sources, and specific returned fields. 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 front-loaded with example queries and contains multiple informative sentences. While somewhat lengthy, every sentence adds value and is well-organized.

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

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

Despite no output schema, the description explains what data is returned (cik, filings, fundamentals, etc.) and notes limitations (patent API sunset, name unsupported). It is sufficiently complete for a complex multi-source tool.

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

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

Schema coverage is 100% and each parameter's description is already clear. The description adds contextual examples ('AAPL', '0000320193') and reinforces format requirements, providing marginal extra value over 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 provides a 'full cross-source profile of a US public company in ONE parallel call' and lists multiple example queries. It distinguishes from sibling tools by explicitly preferring this over chaining individual lookups.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns that names are not supported, directing to use resolve_entity instead.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and pairing, but no new behavioral traits beyond annotation. 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 tool purpose. Every sentence adds value: purpose, usage guidance, and sibling references.

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 1 parameter, no output schema, and clear annotations, the description covers purpose, usage context, and relations to siblings completely.

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 parameter 'key' described as 'Memory key to delete'. Description repeats the same information, adding no extra semantic value beyond schema.

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

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

Clearly states 'Delete a previously stored memory by key' – specific verb+resource. Distinguishes from siblings by mentioning '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 says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also advises pairing with related tools.

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

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

Annotations already declare readOnly and idempotent hints. The description adds behavioral context (fetches page, extracts title/description/links, emits markdown) beyond annotations, without contradiction. Missing details about rate limits or error handling, but acceptable.

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

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

The description is compact: two sentences plus a bullet list of use cases. Every sentence is informative and clearly structured, front-loading the core action and output format.

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

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

Given the tool's simplicity (2 params, 100% schema coverage, no output schema) and rich annotations, the description fully covers what the agent needs: what it does, output format, and appropriate use cases. 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 coverage is 100% and documents both parameters. The description only mentions 'maximum number of link entries' which is already in the schema, adding no extra 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 uses a specific verb ('generate') and resource ('llms.txt file'), clearly indicating the tool's purpose. It explains the output (standard markdown) and distinguishes it from sibling tools like 'ai_visibility_check' or 'deep_research' by focusing on a niche task.

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

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

Explicit use cases are provided (client sites, own projects, competitor auditing), but no guidance on when not to use or alternatives. The sibling list shows no direct alternative, so the context is sufficient.

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

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

Annotations already indicate the tool is safe (readOnlyHint, idempotentHint, destructiveHint false). The description adds value by specifying the scope (caller's subscriptions) and return fields, which go beyond annotation information.

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 with no redundancy. The first sentence states purpose and return fields; the second provides usage guidance. 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 tool's simplicity (one optional parameter, no output schema), the description fully covers purpose, behavior, and usage. It is complete for effective 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% with a clear description for the only parameter. The tool description does not add new meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), and explicitly lists return fields. It clearly distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit use cases: reviewing subscriptions before adding more, and finding an ID to cancel. While it implies when to use, it does not explicitly state when not to use it, though context makes it clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it uses Google Maps API and requires an API key, which is relevant for usage. 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 informative but slightly lengthy. It front-loads key phrases and then adds mode details and preference guidance. Could be more concise, but no wasted sentences.

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

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

Given the presence of an output schema and comprehensive annotations, the description covers purpose, usage guidelines, and key requirements. It might lack details on limitations like waypoints or traffic, but it is sufficient for a straightforward directions tool.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds minimal new parameter-specific detail beyond listing modes (which are already in the schema). Baseline of 3 is appropriate.

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

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

The description clearly states 'Google Maps directions from A to B' and provides synonyms like 'transit/public-transport directions'. It specifies the output as turn-by-turn directions, lists modes, and distinguishes from sibling tools like maps_distance_matrix by recommending it specifically for public-transit routing.

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 prefer this tool over Mapbox/OpenRouteService for public-transit routing, providing usage context. It also notes the requirement for a Google Maps API key, but does not explicitly state when not to use it for other modes or 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, openWorldHint, idempotentHint, and destructiveHint, so the description is not required to repeat those. It adds value by specifying the output is distance and duration matrix, and listing supported modes. 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 somewhat verbose with multiple quotes and slashes. It could be more concise by removing redundant phrasing like 'drive-time grid via Google Maps' and 'transit times between addresses' which restate the same idea.

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 presence of an output schema (not shown but indicated), the description does not need to detail return values. It covers purpose, parameters, usage context, and modes adequately for a matrix tool.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description reiterates the pipe-separated format and provides examples, but adds little new meaning beyond what the schema already provides.

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

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

The description clearly states it computes a travel time matrix between N origins and M destinations, with multiple travel modes. It distinguishes itself from siblings like maps_directions by explicitly being a matrix tool for multiple points.

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

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

The description provides explicit use cases: 'Use for delivery routing, multi-stop optimization, transit-heavy planning.' It does not explicitly state when not to use, but the context clearly differentiates it from single-pair direction tools like maps_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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context: it uses the Google Maps Elevation API, supports batch queries via pipe-separated locations, and returns elevation in meters. This adds meaningful behavioral information beyond what annotations provide, though no details on API limits or error handling.

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, each serving a purpose: first sentence states the core function and data type, second explains the input format. It is front-loaded with key terms and contains no fluff. Ideal conciseness for an agent tool.

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

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

Given the complexity (2 parameters, simple return value), annotations (safe read), and presence of output schema, the description covers the essential: purpose, input format, and data source. No missing information for an agent to correctly invoke the tool.

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

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

The input schema fully describes both parameters (100% coverage), but the description adds value by explaining the format: 'Pipe-separated "lat,lng" pairs' and mentioning batch queries. This helps the agent understand the exact syntax required for the 'locations' parameter, going beyond the schema's generic 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 elevation in meters for lat/lng pairs via Google Maps Elevation API, using terms like 'elevation at [coords]' and 'altitude / height above sea level'. It distinguishes itself from sibling tools like maps_directions, maps_geocode, etc., by specifying the unique API and data type.

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

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

The description implies usage for elevation queries (e.g., 'elevation in meters for one or more lat/lng pairs') but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. The context from sibling names suggests differentiation, but the description itself lacks direct usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about premium-quality geocoding and highest accuracy for US addresses, which goes beyond the annotations. It does not mention rate limits or error conditions, but the core behavioral traits are well-covered.

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

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

The description is three sentences, front-loading the core action and usage guidance. Every sentence adds value with 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 presence of an output schema and the simple two-parameter nature of the tool, the description fully covers purpose, usage context, and behavioral traits. No additional details are necessary.

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 adequate descriptions for both parameters. The description adds little extra meaning beyond the schema, simply restating that the address is geocoded and an API key is needed. No parameter constraints or formats are elaborated further.

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 an address to lat/lng and formatted address via Google Maps, using action verbs like 'geocode' and 'convert'. It distinguishes from sibling maps tools by specifying the conversion from address to coordinates.

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

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

The description explicitly says 'Use when Mapbox/MapTiler/OpenStreetMap miss the address' and notes that a Google Maps API key is required, guiding the agent on when this tool is appropriate versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: returns full details (hours, phone, reviews, etc.) and relies on a prior search step, aiding agent understanding 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?

Two sentences with front-loaded example queries. Every word adds value, no 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?

Given the presence of an output schema, the description adequately covers the tool's inputs and outputs. It lists key return fields (address, phone, hours, etc.) and links to the required precursor tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces that place_id comes from `maps_place_search` but adds no new semantic detail 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 starts with natural language queries like 'Hours / phone / reviews of [business]' and clearly states it provides full details for a Google Place: address, phone, hours, website, ratings, user reviews. It also distinguishes from sibling tool `maps_place_search` by specifying it requires a place ID from that search.

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

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

Explicit guidance to 'Use after search to drill into one specific business' and requires a place ID from `maps_place_search`. While it doesn't mention when not to use, 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by noting it returns 'names, addresses, Google ratings, distances' and requires a 'Google Maps API key'. No behavioral contradictions exist.

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 (4 lines), front-loaded with example query patterns, and every sentence adds value. No unnecessary words or repetition.

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

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

With an output schema present, the description is not required to detail return values. It covers purpose, usage guidance, data quality, and authentication. It is sufficiently complete for a search tool with good annotation coverage.

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 100% coverage with descriptions and examples. The description does not add further parameter-level details beyond the schema, so it meets the baseline of 3.

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

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

The description uses clear verbs like 'find' and specifies the resource as 'nearby businesses and points of interest via Google Maps Places'. It provides concrete examples ('Find restaurants / hotels / coffee shops') and distinguishes itself from sibling tools like 'maps_place_details' by explicitly offering search rather than details.

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

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

It advises when to use this tool over alternatives ('Use over Yelp/OSM when you want Google's POI coverage and ratings'). It does not explicitly state when not to use it (e.g., for place details), but the examples and context imply the appropriate scope.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds the prerequisite of a Google Maps API key and a quality note about US accuracy, adding value 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?

The description is two sentences, front-loaded with the action, and every sentence is essential. 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 tool's simplicity (3 params, output schema exists), the description provides purpose, usage context, and a prerequisite. It lacks sibling differentiation but is otherwise complete. An output schema covers return values, so no need for more.

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 (lat, lng, _apiKey). The description does not add significant new meaning; it merely restates the purpose. 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 'reverse geocode' and the resource 'coordinates' with output 'address'. It uses a dual description that is specific and differentiates from forward geocoding sibling (maps_geocode) implicitly.

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

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

The description explicitly says 'Use when you need Google's street-address parsing (most accurate for US)', providing a clear context. However, it does not explicitly say when not to use it or compare to alternatives like maps_geocode.

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

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

Annotations provide no behavioral hints (all false). The description adds meaningful context: filing without an account returns a claim_token, passing that token back retrieves status, rate-limited to 5 per day, free, and doesn't count against quota. It does not mention all side effects (e.g., whether a ticket is created) but covers the key behaviors expectable.

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

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

The description is a single dense paragraph, but every sentence carries necessary information. It is front-loaded with the core purpose and then covers exclusions, token flow, rate limits, and signal impact. Slightly long but no redundant content.

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

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

Given the tool's complexity, no output schema, and no helpful annotations, the description thoroughly covers when to use, how to use, the claim_token return flow, rate limits, and what to avoid. An agent can decide and invoke correctly without additional documentation.

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

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

Schema coverage is 100% with each parameter already described. The description adds value by explaining claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), the 2000-char message limit, and the advice to describe issues in terms of Pipeworx tools/packs, which maps to the context object.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs and identifies the resource (Pipeworx team) and the action (feedback). This is the only feedback tool among siblings, so it inherently distinguishes itself.

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

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

Excellent usage guidance. The description explicitly says when to use it (bug, feature/data_gap, praise) and provides a critical exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file elsewhere for other vendors. It also advises against pasting end-user prompts, which is a clear when-not-to-use instruction.

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

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

Annotations already mark the tool as readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: data is derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This goes well beyond annotations and fully informs the agent.

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

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

The description is a single, well-organized paragraph of four sentences. It front-loads the core function, then lists use cases, and ends with technical details (derivation, privacy, caching). 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 trend tool with one optional parameter and no output schema, the description covers everything: what is returned, usage windows, use cases, data source, privacy, and caching behavior. The annotations and schema are rich, and the description fills any remaining gaps.

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

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

Schema coverage is 100% with a description for the 'window' parameter. The description's mention of windows ('24h, 7d, or 30d') reinforces the schema but does not add new information beyond what the schema already provides. Thus baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns 'the top tools, top packs, and total call volume over a recent window', providing a specific verb and resource. The three listed use cases further clarify its purpose, and it is easily distinguishable from sibling tools like 'discover_tools' or 'ask_pipeworx' due to its focus on trending metrics.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning use cases), giving clear context for when to use this tool. However, it does not explicitly exclude scenarios or compare with siblings like 'discover_tools', which could overlap.

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, idempotentHint, and non-destructive. The description adds significant behavioral context: fill check against live CLOB depth, placeholder filtering, semantic anchor for cross-event pairs, and partition filter details. 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 verbose but well-structured: main purpose first, then parameter explanations in order, followed by post-processing details. Every sentence adds value, though slight trimming could improve conciseness.

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

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

The description covers input, process, output structure (opportunities[], partition_check fields), edge cases (placeholder filtering, similarity check, fill check), and references related tool for custom sizing. No output schema but response is fully described.

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

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

Both parameters have 100% schema description coverage. The description adds substantial meaning beyond the schema, explaining event slug format, topic seed question, and the behavioral differences between modes.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes the three modes (no args, event, topic) and explicitly differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each parameter: no args for trending scan, event for specific market, topic for cross-event scan. It also tells when not to trade (if realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description goes far beyond by detailing the three segments, model families, edge calculation, knob effects, response structure, diagnostics, and caching behavior. This provides comprehensive behavioral context that annotations alone do not cover.

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

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

The description is comprehensive but overly verbose, as a single dense paragraph. It is front-loaded with the main purpose, but its length and lack of section breaks make it harder to parse efficiently. It could be more concise without losing critical details.

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 (9 parameters, no output schema), the description is remarkably complete. It explains the response structure (by_segment, fed_candidates, diagnostics), the edge calculation, model details, and knob effects, compensating well for the lack of output schema with nested object descriptions.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds valuable context beyond schema descriptions, such as explaining how min_partition_leg_kelly applies to per-leg Kelly and that min_kelly never filters partition arbs. This gives additional meaning for tool invocation.

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 top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using the specific verb 'Scan'. It distinguishes itself from sibling tools by focusing on discovering opportunities without paging hundreds of markets and detailing three unique model families.

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 the tool is built for 'what should I bet on today' and provides guidance on when to use it. It explains the knobs for filtering tradeable edges (min_liquidity, max_spread_pp, etc.) but does not explicitly state when not to use it or contrast with alternative tools beyond implication.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by detailing the snapshot mechanism, time-series tracking, decay computation, and limitations (TTL, cache-miss behavior). This provides rich 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?

The description is well-structured: purpose, args, response format, limits. Each sentence earns its place, front-loading the core purpose. It is appropriately sized for the complexity of the tool.

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

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

Given the tool has 2 optional parameters, no output schema, and full annotations, the description fully covers the behavior, response structure (tracked, expired, snapshot_dates), and constraints (TTL, decay derivation). No gaps remain.

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

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

Both parameters (days, window) are fully described in the input schema (100% coverage). The description adds context about defaults, clamps, and the 'snapshot family' meaning of window, providing additional value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes from the sibling 'polymarket_edges' by focusing on historical persistence rather than 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 implies usage through its purpose—use when you need historical edge persistence and decay metrics. It provides clear context but does not explicitly list when to use this tool vs alternatives or state exclusions.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details like live order-book checking, required parameters (market or event), default and clamp behavior, and return fields including a verdict. No contradictions.

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

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

The description is long but every sentence is necessary for the tool's complexity (two modes, multiple return fields, usage warnings). It is front-loaded with the core purpose and structured logically. No waste.

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

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

For a tool with 4 parameters, no output schema, and complex dual-mode behavior, the description is remarkably complete. It enumerates return fields, explains risk of partial fills, and covers default and clamp behavior. Adequate for agent invocation.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds context on parameter interaction (exclusivity of market/event, side default for basket, size_usd dual meaning) but does not significantly extend beyond 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 tool "check realizable-vs-theoretical edge against live CLOB order-book depth", specifying verb and resource. It distinguishes two modes (single-market and basket) and lists return values, differentiating it from sibling polymarket tools.

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

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

The description explicitly advises use before acting on polymarket_arbitrage signals or trades above $500. It also warns against partial basket fills leading to directional risk. While clear on when to use, it lacks explicit when-not-to-use guidance for small trades or 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?

Discloses extensive behavioral context beyond annotations: modes, compatibility warnings, temporal alignment, skipped pair counters. Explains that when matched_pairs=0 with skipped_cross_type>0 no arb exists, and that temporal misalignment makes spreads meaningless. 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?

Detailed but well-structured with clear sections and front-loaded purpose. Every sentence adds useful information, though slightly verbose. Still effective and easy to parse for an AI agent.

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 provides comprehensive context about response fields (compatibility_warning, temporal_alignment, skipped counters). Covers edge cases and limitations thoroughly. Complete for a complex tool with only 3 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 three parameters with descriptions (100% coverage). The description adds value by explaining the two modes, listing available topic shortcuts, and describing how explicit parameters override the topic. Could include more detail on parameter formats, but 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?

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from sibling tools like polymarket_arbitrage by specifying cross-venue comparison with two modes (shortcuts and explicit pairing).

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

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

Provides explicit when-to-use guidance including two modes, explains compatibility warnings and temporal alignment conditions, and warns that real spreads are rarer than the shortcut list suggests. Implicitly tells when not to trust results (e.g., when compatibility_warning fires).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping (anonymous IP, BYO key hash, account ID) and the behavior when key is omitted (list all keys), which is beyond annotations.

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

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

Two sentences, front-loaded with core action, no redundant words. Efficient and clear.

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

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

Simple tool with one optional parameter and rich annotations; description covers retrieval, listing, scoping, and pairing with siblings. No output schema needed.

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

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

Schema coverage is 100% with the key parameter described. Description explains the effect of omitting key (list all keys), adding meaning beyond the schema's 'omit to list all keys'.

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

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

The description clearly states the tool retrieves a saved value or lists all keys when omitted, specific verb 'Retrieve' and resource 'memory key'. It distinguishes itself from sibling tools 'remember' and 'forget' by explaining the pairing.

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

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

Explicit guidance on when to use: to look up previously stored context without re-deriving. Mentions pairing with 'remember' and 'forget', and 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?

Annotations already provide readOnly, idempotent, openWorld hints. Description adds valuable behavioral details: explains mark_read behavior (affects next call), mentions payload fields (source, citation_uri, raw event), and that the feed is persisted. 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 two sentences, with the first front-loading the core purpose. The second sentence is long but packs essential details. Could be slightly more concise, but no wasted words.

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

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

For a tool with 5 params, 100% schema coverage, and no output schema, the description covers behavior, filtering, read-state management, and alternative access. Missing explicit pagination limit info but acceptable given schema covers limit param.

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

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

Schema coverage is 100%, so baseline 3. Description adds concrete examples like 'e.g. 'sec_8k'' for type, 'ISO timestamp' for since, and clarifies mark_read effect. This goes beyond schema descriptions.

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

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

Description starts with clear verb+resource: 'Pull fired events from your subscription feed.' It specifically names the resource (subscription feed) and action (pull). No sibling tool serves the same purpose, so it's well distinguished.

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

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

States that polling works fine and mentions an alternative REST endpoint for scripts/dashboards, giving clear context. However, doesn't explicitly state when not to use or contrast with siblings, but since no sibling competes, this is sufficient.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: fan-out to multiple sources, GDELT→GNews fallback, and USPTO deprecation, all 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, efficient paragraph that front-loads usage examples and packs all essential information without unnecessary 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?

Despite lacking an output schema, the description explains the return format (grouped changes, total count, URIs) and covers edge cases like soft-fail for USPTO, making it fully informative for tool invocation.

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

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

Schema coverage is 100% but the description adds practical context: 'since' accepts ISO or relative shorthand with examples, 'value' can be ticker or CIK, and 'type' restricted to 'company'. This enhances parameter understanding.

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

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

The description clearly states the tool's purpose: providing a change feed for a company over a time window, aggregating multiple sources. It distinguishes from sibling 'entity_profile' by specifying when to use that alternative.

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

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

The description provides explicit usage examples and a direct contrast with 'entity_profile' for static profile queries. It also notes current limitations (USPTO soft-fail), giving clear when-to-use guidance.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. Description adds useful context: persistent vs. 24-hour retention based on authentication. 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, each with distinct purpose: purpose, usage, technical detail, pairing. No wasted words. Front-loaded with key action.

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

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

For a simple two-parameter tool with full schema coverage, the description covers all essential aspects: purpose, when to use, behavior (persistence), and integration with siblings. 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 covers 100% of parameters with descriptions. Description adds example key patterns (e.g., 'subject_property') and clarifies value as any text, adding meaning beyond schema.

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

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

Clearly states the tool saves data for reuse across conversations/sessions, with specific examples like 'resolved ticker' and 'user preference'. 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 when to use ('when you discover something worth carrying forward') and suggests pairing with recall/forget. Does not state explicit exclusions 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 and non-destructive behavior. The description adds substantial context beyond annotations: it mentions cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, and that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted. This informs the agent about underlying behavior and edge cases.

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-loaded with concrete user queries and a clear directive. Each sentence adds value, though it is somewhat long. Given the tool's complexity (two types, multiple data sources), the length is justified, but it could be slightly tighter without losing essential details.

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

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

No output schema exists, so the description carries the full burden of explaining return values. It thoroughly covers what each supported type returns (company: CIK, ticker, company name, LEI, FIGI; drug: RxCUI, ingredient, brand), including source attribution and unresolved handling. It also addresses edge cases like source unavailability, making it complete for an agent to select and use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning by explaining how 'value' is interpreted for each type (e.g., for company: ticker, CIK, or company name; for drug: brand or generic name) and what outputs are expected (CIK, LEI, FIGI, RxCUI). This goes beyond the raw schema by providing contextual semantics and output implications.

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 resolves a user-spoken name to canonical/official identifiers, with a clear verb ('resolve') and resource ('entity'). It distinguishes itself from siblings by listing specific use cases ('What's the ticker for...', 'find the CIK for...') and supported types, making its purpose unambiguous.

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains it replaces 2-3 manual lookups and describes the supported entity types, giving clear context on when to invoke this tool versus alternatives like entity_profile or compare_entities.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds detail on probing mechanism and output fields (score, confidence, signal density). No contradiction, but doesn't discuss rate limits or auth beyond schema. Adequate given annotations.

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

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

Two sentences: first states core function, second provides use case and output. Front-loaded, no filler. Every sentence adds value.

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

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

Explains probing, ranking, output fields. No output schema, so description compensates by listing score, confidence, signal density. Covers key aspects needed for agent to use tool correctly. Minor gap: no mention of error handling or timeout limits.

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: first entity treated as 'subject', range 2-8 entities, context disambiguates names, optional API key purpose. Enhances schema without redundancy.

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 uses specific verb+resource: 'scan competitor AI presence'. Clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying it probes AI visibility and ranks results.

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 case: competitive AI-marketing audits. Provides example question and implies when to use (comparing multiple entities). Lacks explicit exclusions or alternative sibling references, 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, openWorldHint, idempotentHint, destructiveHint. Description adds important behavioral detail: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts.

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

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

Description is detailed but efficient, front-loading the core purpose. While a bit long, every sentence adds value. Could be slightly more structured 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?

No output schema, so description comprehensively explains return values (summary block with fields, advisory details, links, alternative versions) and error handling. Complete for a complex read-only tool.

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

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

Schema coverage is 100%, but description adds context: scoped packages accepted, version defaults to latest. Provides extra meaning beyond schema.

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

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

Clearly states it's a composite check for adding an npm package, fans out across deps.dev and bundlephobia. Distinguishes from siblings by explicitly limiting to NPM ecosystem in v1.

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 agent asks about safety, popularity, size, or cost of adding a package. Also clarifies when NOT to use (other ecosystems) and directs to deps.dev:version directly.

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, idempotentHint, etc.), the description adds specific behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. This fully discloses operational behavior.

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

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

The description is a single, well-structured paragraph with no wasted words. Each sentence contributes essential information, and the key points (purpose, usage, behavior) are front-loaded.

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

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

Despite no output schema, the description adequately explains return values (passages, offsets, scores). All 3 parameters are covered in schema and description. The tool's behavior is fully described, 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 coverage is 100% with descriptions. The description adds value by explaining the intended use of 'text' (fetched record), providing query examples, and stating default and max for limit. While schema is already good, the description enhances it with practical 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 clearly states the tool performs semantic search inside a fetched record, specifying input (text and query) and output (top-N passages with offsets and scores). It distinguishes from siblings like ask_pipeworx_grounded by noting they pair together.

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 the record is too large for the prompt, and how it pairs with ask_pipeworx_grounded for grounding. Provides clear context on when it is beneficial, effectively guiding agent decision-making.

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=false and idempotentHint=true. Description confirms write operation ('Create') and returns new id. Discloses key behaviors: SMS cap (10/day), phone verification requirement, webhook auto-disable after 10 failures, and HMAC signing. No contradiction with annotations; adds significant behavioral context 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?

Description is moderately long but well-structured: main action first, then types in grouped bullet style, then delivery channels. Every sentence adds unique information. Slightly verbose due to necessary examples, but no wasteful 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?

Given complexity (3 params, nested objects, multiple subtypes, no output schema), description covers core creation, return value (id), constraints, and channel-specific behaviors. Could mention error scenarios (e.g., invalid phone or duplicate) but sufficient for agent to call 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 3 parameters. Description adds immense value by explaining the nested object structures (params and delivery) with concrete examples for each type, validation rules (E.164, email pattern, HTTPS-only), and constraints (phone verification, webhook signing). Exceeds baseline by providing actionable guidance for each parameter.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream.' with specific verb (create) and resource (subscription). Distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and providing detailed type examples.

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

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

Explicitly requires Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. Provides guidance on when to use each subscription type and delivery channel. Mentions alternative pull via recent_alerts or GET endpoint. Lacks explicit when-not-to-use but contextually clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds meaningful context about being an onboarding entry point and what it returns, no contradictions.

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

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

Description is somewhat long but well-structured: starts with common queries, then explanation, then usage. Could be slightly more concise 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?

Given the complexity (many siblings, meta-tools), description adequately explains what the tool does, when to use it, and what it returns. No output schema but explanation suffices.

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 a description for topic. Description adds examples of topics ('finance', 'pharma') and explains omitting topic for full spread, adding value beyond schema.

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

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

Description clearly states it's an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. Distinguishes from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly says 'Use this FIRST' and describes when to call with no arguments vs topic. Lacks explicit when-not-to-use but provides clear 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?

The description adds behavioral details beyond annotations: the row is deactivated not deleted, and historical events stay available via 'recent_alerts'. This complements the annotations (destructiveHint=false, idempotentHint=true) without contradiction.

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

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

Three concise sentences, each adding value. The first sentence states the purpose, the second adds access control, the third explains the effect. No unnecessary words or repetition.

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

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

The description is complete for a tool with no output schema: it explains the behavior, side effects, and access control. It could mention any side effects like stopping notifications, but overall it's sufficient.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The description adds context that the id is 'returned by subscribe', which helps the agent understand the parameter's origin 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 action ('Cancel a subscription by id') and specifies the resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description explains when to use the tool: to cancel a subscription. It mentions ownership enforcement but does not explicitly state when not to use it or provide alternatives, though the context is sufficient.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the two processing paths, the meaning of each verdict type, and critically distinguishes could_not_verify (verification didn't happen, carries verification_error) from unsupported (no source coverage). This is essential behavioral context that the annotations do not provide, and the description aligns with the annotations.

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

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

The description is long but every sentence carries useful information: trigger phrases, purpose, routing logic, verdict list, error semantics, and an efficiency note. It is well-structured with a front-loaded purpose and examples, and while it could be condensed, the complexity of the tool justifies 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?

With no output schema, the description must explain return values, and it does: verdict, evidence value with citation, reasoning, and error structure. It also covers both execution paths and tolerance behavior. Given the tool's complexity, this is a complete and self-sufficient description.

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

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

The input schema already provides 100% coverage of both parameters with detailed descriptions and examples. The description adds some context about the claim processing paths but does not significantly enhance parameter-level semantics beyond what the schema already offers, so the baseline score of 3 is appropriate.

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

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

The description opens with concrete trigger phrases like "fact check" and "verify the claim that…", then states the tool does natural-language claim verification against authoritative sources. It clearly distinguishes itself from general Q&A tools by focusing on adjudicating a claim with verdicts, and even differentiates a financial fast path from a general grounded pipeline.

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

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

The description gives explicit usage context: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains how claims are routed (SEC EDGAR for company-financial claims, grounded pipeline otherwise), which helps the agent decide when to invoke this tool. It does not name alternative tools explicitly, but the scope is clear enough to distinguish from siblings.

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