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 mark this as readOnly, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context: it routes and fills arguments on the agent's behalf, returns structured answers with citation URIs, and makes 'one fast call' on every tier. This goes beyond the annotations without contradicting them.

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

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

The description is long but front-loaded with the most important directive and organized into use-when, examples, default status, and escalation paths. There is some redundancy between the 'Use whenever' list and the example questions, but every section serves a distinct routing purpose.

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

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

For a broad, open-ended question-answering tool with no output schema, this description is complete: it covers scope, examples, alternatives, return format, citation URIs, tier availability, and speed. An agent has enough context to select and invoke the tool correctly in most factual-question scenarios.

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%: all six parameters are aliases for the required 'question' string, and the schema clearly describes natural-language input. The description contributes examples and query-phrase patterns but doesn't add new parameter-level semantics, so the baseline score of 3 is appropriate.

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

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

The description opens with a strong directive ('PREFER OVER WEB SEARCH') and states the core function: routes a natural-language question to the appropriate tool among 5,743 sources and returns a structured answer with stable pipeworx:// citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by 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 gives explicit when-to-use guidance: 'Use whenever the user asks "what is", "look up", "find"...' and lists concrete example questions. It also names the conditions for escalating to ask_pipeworx_grounded and deep_research, plus how ask_pipeworx handles breaking-news queries.

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

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

Annotations cover safety (readOnly, idempotent, not destructive), so the description's burden is reduced. It adds meaningful behavioral context beyond annotations: candidate routing improvements are enabled live during tests, no candidate is currently active, results are compared against the stable router to decide merges, and the tool is fully functional rather than a stub. It does not detail potential variability in outputs or error behavior, but the experimental nature is clearly communicated.

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

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

The description is a compact, information-dense block that front-loads the core identity ('Beta version of ask_pipeworx: identical universal router') before moving to experimental status, current state, and usage instructions. Every sentence earns its place; there is no padding or redundancy.

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

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

For a router that delegates to 5,743 tools, the description provides essential context: identical arguments, identical response shape, current parity with the stable router, and the purpose of running experimental candidates. The absence of an output schema is mitigated by pointing to ask_pipeworx's response shape. It does not detail error handling or rate limits, but the key operational context is sufficiently covered for an agent to call and interpret the tool correctly.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no parameter-level semantics beyond the schema, only stating 'same arguments' generically. Since the input schema already fully describes the parameters and their aliases, the baseline of 3 applies; no extra value is lost but none is added.

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 identifies the tool as a beta version of ask_pipeworx and characterizes it as a 'universal router' with the same 5,743 tools, arguments, and response shape. This gives a clear functional identity and distinguishes it from the stable sibling by emphasizing its experimental 'edge' status. However, it relies on the reader already knowing what ask_pipeworx does, and the core action is only implied through the reference to a router rather than stated directly.

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

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

The description explicitly instructs when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing'. It names the alternative (ask_pipeworx), explains the comparison and merge process, and clarifies that it is a full working router with no fallback. This leaves no ambiguity about when to prefer this beta over the stable sibling.

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

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

Annotations already declare readOnly/openWorld/idempotent/not destructive, and the description adds significant behavioral context beyond that: it discloses the exact success return shape, the five explicit refusal reasons, that only the tool result is used, and the extra LLM call cost. No contradictions with annotations.

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

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

The description is dense but every sentence earns its place: core value, routing behavior, return contract, refusal contract, use cases, and cost tradeoff. It is front-loaded with the key differentiator and avoids filler.

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

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

With no output schema, the description fully compensates by detailing the success and refusal return shapes. It also covers the alternative, cost implication, and appropriate contexts, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents the question parameter and all aliases. The description adds little beyond the schema, only reinforcing that the question is natural language; 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 states a precise purpose: a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers only from the fetched tool result. It clearly differentiates itself from the sibling ask_pipeworx and ask_pipeworx_beta by emphasizing grounded, evidence-backed answers.

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

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

It explicitly says when to use it: whenever an answer will be quoted, cited, or acted on, and facts must not be invented, with examples such as financial verdicts and legal claims. It also names the alternative ask_pipeworx and tells the agent to prefer it for casual lookups, providing clear when-to-use and when-not-to-use guidance.

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

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

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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, and the description adds substantial context: account requirements, paid plan for 'thorough', latency expectations, gaps[] for unanswered facets, 'never invented' evidence, semantic excerpting, and resolvable citation_uri. There is no contradiction between the description and 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 operational value: account requirements, alternatives, output packet structure, gaps behavior, latency, citation fetchability, and excerpting strategy. It is front-loaded with the most critical selection constraint (account required / use ask_pipeworx) and avoids fluff.

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

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

For a tool with no output schema, the description thoroughly covers return shape (findings packet with evidence, confidence, source, fetched_at, citation), failure behavior (gaps[], contradictions[]), latency expectations, and depth-specific behavior. An agent has enough context to decide when to call it and to interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds little beyond the schema for either parameter: the depth semantics are already fully detailed in the enum descriptions, and the 'question' guidance ('Broad/multi-part is fine — decomposition is the point') is essentially repeated verbatim in the schema. The description does not provide meaningful extra parameter-level meaning.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources.' It explicitly differentiates from siblings by saying 'this is NOT open-web search' and by contrasting with ask_pipeworx for single lookups. An agent can clearly understand what deep_research does and how it differs from nearby 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 gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It also names alternatives and conditions: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead.' This leaves little room for mis-selection.

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

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

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, and the description adds substantial non-obvious details: the specific sources fanned out, USPTO sunset soft-fail, empty sections meaning real absence of data, resolved:false behavior for private companies, and fallback behavior. No contradiction with annotations.

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

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

The description is long and dense, but nearly every sentence adds operational value and key instructions are front-loaded with examples. It could be improved with bullets or shorter paragraphs, but the density is justified by the tool's complexity.

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

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

With no output schema, the description takes on the burden of explaining return sections: cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and the meaning of sources_used/sources_failed. It also covers edge cases like empty FDA sections and private company resolution, making the call contract fully transparent.

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 still adds meaningful semantics: `type` values are interchangeable, `value` can be a ticker, zero-padded CIK, or company name, name resolution happens via SEC EDGAR, and the resolved_from/resolved_to fields are explained. This goes well beyond the schema.

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

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

The description states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call,' with concrete example phrasings. It also distinguishes the tool from chained single-source lookups by emphasizing the holistic, fan-out behavior.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies acceptable input forms and what happens for private companies, making the invocation conditions 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 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?

The description goes far beyond the readOnly/idempotent annotations by detailing the tool's full safety behavior: compatibility_warning and compatibility_codes[] can both be non-empty, code semantics for event_subject_mismatch, temporal_mismatch, and temporal_alignment_unknown, and the rule that unknown legs are never paired. It also discloses that spreads are gross not net tradeable (fees_note). This is exceptional transparency for a read-only tool.

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 appropriately structured with labeled sections (RESPONSE, SAFETY FIELDS, codes list) and front-loaded information. It is dense with safety-critical details, and while there is mild repetition around temporal_alignment_unknown, every sentence carries operational meaning. It earns its length given the tool's complexity and lack of an output schema.

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

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

With no output schema, the description fully specifies what the response contains: 'each venue's leg-by-leg prices (raw probability 0-1) plus matched spread[].top_spreads_pp', plus flags, skip counters, and fees_note. It also explains null semantics for temporal_alignment. An agent has everything needed to invoke the tool and interpret results.

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

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

Schema coverage is already 100%, and the description adds substantial meaning beyond the schema: it explains the topic enum values, the override relationship between topic and the explicit parameters, and how the same matcher runs in both modes. This gives an agent a clear mental model of parameter interactions.

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

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

The opening sentence states a precise verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This establishes the tool's core function and distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which target different concepts. The two-mode description further clarifies scope without ambiguity.

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

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

The description explicitly explains when to use each mode: 'TWO MODES: (1) topic — 10 pre-mapped macro shortcuts... (2) explicit kalshi_event_ticker + polymarket_event_slug for custom pairings.' It also provides cautionary guidance ('most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'). However, it does not explicitly name alternative sibling tools or state when to prefer them, so the exclusion dimension is missing.

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, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context beyond them: it cascades through multiple lookup endpoints, degrades gracefully when external sources are down, labels identifier provenance, explicitly reports unresolved identifiers, and returns figi_candidates rather than asserting a single match. This deeply informs the agent about 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 exceptionally dense and contains valuable, non-obvious details, but it is largely one sprawling paragraph with heavy parentheticals and embedded clauses. It would be more concise and scannable with bulleted type-specific breakdowns; the detail is useful, but the structure makes it harder for an agent to quickly extract the core contract.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does so well: it names returned identifiers (CIK, ticker, LEI, FIGI, RxCUI), states how sources are labelled, describes the unresolved field, and explains the figi_candidates response for ambiguity. For a two-parameter tool with complex multi-source behavior, nothing essential is missing.

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

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

Schema coverage is 100%, but the description significantly extends meaning: it explains that value can also be an ISIN for company lookups, warns against passing full noun phrases for bonds, clarifies that trailing security-class words break the FIGI match, and distinguishes accepted inputs per type. This goes well beyond the schema's minimal 'ticker, CIK, or name' definition.

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 names the exact action — resolving a user-spoken NAME to canonical identifiers — and enumerates the concrete question forms that trigger it, plus supported types (company, drug). It clearly differentiates this tool from siblings by positioning it as the required input provider for other tools, and explains edge cases like non-equity instruments and ambiguous matches.

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 FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. It explains ambiguity handling and notes fallback behavior when LEI/FIGI enrichment is unavailable. However, it does not name alternative sibling tools (e.g., entity_profile) to explicitly state when not to use this tool.

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

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

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.