Arcgis Mobile

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

Annotations already declare read-only and idempotent behavior. The description adds important behavioral context: the default model is free, Anthropic requires a BYO key paid directly to Anthropic, and the API key passes straight through. This enhances transparency 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 concise, with three sentences that front-load the main action and provide essential details without redundancy. 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?

Despite no output schema, the description explains the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers all parameters and their roles, and provides use cases. The tool is adequately described for an agent to use 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 baseline is 3. The description adds value beyond schema by explaining the default model, the role of _apiKey (only for Anthropic), and the disambiguation purpose of the context 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 the tool probes LLMs for knowledge about a business/brand/product/topic and produces visibility scores. It specifies the verb 'probe', the resource 'LLMs', and the output format (0-100 per model). The description differentiates from sibling tools like scan_competitor_ai_presence by focusing on this specific scoring mechanism.

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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it does not explicitly exclude alternatives, it provides clear context for when the tool is appropriate.

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

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

The description discloses that the tool routes to many tools, fills arguments automatically, returns structured answers with citations, and is a single fast call. This goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by explaining the routing and citation 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 somewhat long but well-structured with clear sections: preference statement, examples, usage guidance. It is front-loaded with the key directive to prefer over web search. Minor redundancy could be trimmed, but overall efficient.

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

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

Given the tool's complexity (many sources, multiple parameters), the description covers purpose, usage, behavior, and return format (structured answer with citations) despite lacking an output schema. It provides sufficient context for an AI agent to use 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% (all parameters described). The description adds value by explaining the 'question' parameter and its aliases, and noting that the tool fills arguments internally. This provides context beyond the schema definitions.

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

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

The description clearly states the tool routes questions to a vast set of verified sources (4,552 tools across 1,160 sources) and returns structured answers with citations. It lists specific domains (SEC filings, FDA drug data, etc.) and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specifies when to step up to alternative tools (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions, web search for breaking news). It also provides example 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 already provide readOnlyHint, etc. The description adds significant detail: costs one extra LLM call, returns structured response with evidence and refusal reasons, and explains refusal conditions. 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?

Description is detailed but front-loaded with key information. Every sentence adds value, though it is somewhat lengthy. It could be slightly more concise without losing clarity.

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

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

No output schema exists, but the description thoroughly explains the return structure, including refusal reasons. It also covers internal routing and cost, making it complete for a complex 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 all params documented as aliases for 'question.' The description does not add new parameter-level semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads.' It explains the routing, data extraction process, and distinguishes itself from the sibling 'ask_pipeworx' by noting the extra LLM call and appropriate use cases.

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

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

Explicitly provides when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. Also contrasts with sibling: 'prefer ask_pipeworx for casual lookups.'

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 provides extensive behavioral details beyond annotations: resolver contract, safety short-circuits, wide-spread handling, resolution-rule risk. It complements the annotations (readOnlyHint: true, idempotentHint: true) without contradiction, making agent behavior fully transparent.

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

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

The description is lengthy but well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY). It is front-loaded with core purpose. Though slightly verbose, the information density justifies the length for a complex tool.

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

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

Given the tool's complexity and lack of output schema, the description fully covers return values, edge cases, safety, resolution rules, and behavior for various scenarios. It leaves no critical gaps for an agent to understand tool usage.

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

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

The input schema already covers 100% of parameters. The description adds practical context: market parameter accepts slug/URL/question text, depth has quick/thorough options with defaults, include_raw explains when to use true/false. This enriches schemas without being redundant.

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 provides specific use cases ('should I bet on X', 'what does the data say about Y') and distinguishes from sibling tools like polymarket_edges by emphasizing comprehensive data gathering and analysis.

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

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

The description explicitly lists when to use the tool ('Use for...') and mentions blocking conditions (low-confidence matches, closed markets). It does not explicitly state when NOT to use it or provide direct alternatives, but the context implies differentiation from 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 indicate read-only, idempotent, open-world behavior. The description adds valuable behavioral context: correct handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 efficient and front-loaded with examples, but slightly lengthy. Every sentence adds value, though could be trimmed slightly without loss.

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 covers data sources, sorting, and output format (paired data + URIs). However, it could be more explicit about the exact structure of the returned data.

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 both parameters with descriptions, but the description adds real-world meaning: explains data sources per type (SEC EDGAR for companies, FAERS for drugs) and value formats (tickers/CIKs, drug names), plus bounds (2-5).

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 side-by-side comparisons of 2-5 entities (companies or drugs) in one call, with example queries. It distinguishes itself from sequential lookups and implicitly from single-entity tools like entity_profile.

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 when comparing entities' and provides natural language triggers, giving strong guidance on when 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 show readOnlyHint and idempotentHint, and the description adds extensive behavioral context: account requirements, latency (15-60s), return of gaps[], and that tool does not invent answers. 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 relatively long but front-loaded with critical information (account requirement). Every sentence serves a purpose, though some details could be slightly condensed.

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, parameter count is low (2), no output schema, but the description fully explains the return format (findings packet with evidence, confidence, source, citation, gaps) and expected latency. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds meaningful detail: explains the depth enum values (quick=3, standard=5, thorough=8 facets) and clarifies that broad questions are acceptable. No additional parameter info is needed.

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

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

The description clearly states the tool performs grounded multi-source research across 1160 structured data sources, decomposing questions into facets and routing to 4,552 tools in parallel. It distinguishes itself from siblings like ask_pipeworx and includes specific use-case 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 tells when to use (broad/multi-part questions over structured data) and when not to (breaking news, current topics; use ask_pipeworx). Also provides account requirements and alternative tool for unauthenticated users.

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 valuable context beyond these: it explains that the output includes 'names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' This enriches the agent's understanding of behavior and output. No contradictions with annotations.

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

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

The description is a single paragraph but is efficient and front-loaded with the core purpose. Each sentence adds value: purpose, domains, output format, and usage advice. While it could be slightly more structured (e.g., bullet points), it is not overly long and avoids 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?

Despite having no output schema, the description compensates by describing the output type (tools with names, descriptions, full schemas) and behavior (top-N, ready to call). It covers the limit parameter and the natural language query. However, it does not specify edge cases like no results or exact formatting, leaving minor 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 description coverage is 100%, so the baseline is 3. The description mentions the main parameter 'query' as a natural language description and hints at 'limit' by saying 'returns top-N,' but it does not add significant semantic detail beyond what the schema already provides. The aliases are also listed in the schema, so the description adds minimal extra value.

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 'Find tools by describing the data or task,' which is a specific verb+resource statement. It lists numerous example domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling tools by advising to 'Call this FIRST when you have many tools available.' This clearly communicates the tool's role as a tool discovery mechanism.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides a clear usage context and implies it should be used for exploration rather than when the agent already knows the exact tool. However, it does not explicitly state when not to use it or list alternative strategies for known tools, so it loses a point.

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

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

Discloses multi-source fan-out, specific return fields, fallbacks (GDELT→GNews, soft-fail for patents), and timing. Adds value beyond readOnly, idempotent, and openWorld hints.

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

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

Dense but well-structured with examples upfront. Could be more concise, but every sentence earns its place with specific 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 complexity and no output schema, description fully explains return fields from each source and limitations (patents). Enough for agent to use correctly.

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

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

Schema coverage is 100% with good descriptions. The description reiterates and expands slightly (e.g., zero-padded CIK example). Adds moderate 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?

The description clearly states the tool creates a full cross-source profile for US public companies in one call, contrasting with chaining other tools. Examples and output details solidify understanding.

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 for holistic company views, prefers over chained lookups, specifies allowed inputs (ticker or CIK) and to use resolve_entity for names.

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 confirms the destructive nature implied by the destructiveHint annotation, and adds context about use cases like clearing 'sensitive data' and 'the agent saved earlier'. This adds value beyond the annotations. No contradictions are present.

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

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

The description is concise (two sentences) and front-loaded with the action, followed by usage guidance. Every sentence serves a clear purpose 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?

For a simple tool with one parameter, the description provides all necessary context: what it does, when to use it, and its relationship to sibling tools. No output schema is needed for a delete operation.

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 the single parameter 'key' with a description 'Memory key to delete'. The tool description mentions 'by key' but does not add further semantic detail beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Delete' and resource 'memory by key', clearly stating the tool's function. It distinguishes itself from siblings 'remember' and 'recall' by implying storage and retrieval, making the purpose unambiguous.

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

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

The description explicitly lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', providing useful context. However, it does not explicitly state when not to use it, though the conditions are fairly comprehensive given the tool's simplicity.

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

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

The description discloses that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. This adds behavioral context beyond the annotations (readOnlyHint, idempotentHint, openWorldHint, non-destructive). 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 concise, about 4 sentences, each adding value. It front-loads the main action and purpose, then details the process and use cases. 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 (2 parameters, no output schema), the description adequately covers what it does and how to use it. It mentions the output format (single text blob) and the fact it crawls the page. It could note potential delays from fetching but is 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?

The input schema has 100% coverage with descriptions for both parameters (url and max_links). The description mentions 'page, title/description/key links' which relates but does not add significant new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool generates a production-ready llms.txt file for a given URL, specifying the resource (llms.txt file), action (generate), and purpose (for AI crawlers). It distinguishes itself from sibling tools by being the only one that specifically creates an llms.txt file.

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

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

The description lists three explicit use cases: getting a client's site indexed, drafting for own project, and auditing competitors. It provides context on when to use the tool. However, it does not explicitly state when not to use it or compare to alternatives like ai_visibility_check or scan_competitor_ai_presence.

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 destructiveHint false. The description reinforces this by stating 'Get' and adds behavioral details on what is returned (fields, geometry, count, capabilities), providing value 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?

Single sentence, front-loaded with key information, no wasted words. Every part 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?

The tool is simple (one parameter, read-only), and the description covers the main return values. No output schema exists, but the description specifies what is returned. Minor omission of potential error conditions, but overall complete given simplicity.

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% as the single parameter 'url' is described in the schema. The description mentions 'by url' but adds no additional meaning beyond the schema's description. Baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves an ArcGIS Feature/Map Service layer's schema, listing specific outputs (fields, geometry type, record count, capabilities). It uses a specific verb 'Get' and distinguishes from sibling tools like query_layer which likely queries data.

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

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

The description clearly indicates when to use this tool (to get a layer's schema) but does not explicitly mention when not to use it or compare with alternatives. The context is clear but lacks 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 provide readOnlyHint, idempotentHint, and destructiveHint. Description adds that it returns specific fields and defaults to active subscriptions, but does not disclose additional behavioral traits beyond what annotations convey.

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

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

Two sentences with no wasted words. Purpose and usage are front-loaded, providing essential information efficiently.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description adequately covers purpose, usage, and returned fields. A brief mention of possible pagination or limits could enhance completeness, but it is not 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 coverage is 100% and the description does not elaborate on the parameter. Baseline score of 3 is appropriate since the schema already documents the only 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 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe/unsubscribe and mentions the returned fields.

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

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

Explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear usage context. Could be improved by mentioning when not to use it, but it's 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?

Adds significant context beyond annotations: rate limit (5 per day), free (no quota cost), and that feedback affects roadmap. Annotations only indicate non-read-only and non-destructive, so description fills gaps perfectly.

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

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

Four sentences front-load the purpose, followed by concise usage rules and constraints. No redundant or irrelevant information.

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

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

Given the tool's simplicity (3 params, no output schema), the description covers all necessary aspects: purpose, when to use each type, rate limits, cost, and maximum message length. An agent can confidently invoke this tool.

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

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

Schema coverage is 100%, but description enriches each parameter with practical usage hints (e.g., '1-2 sentences typical', 'be specific'). The type enum is explained in plain language, and context parameter's purpose is clarified.

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 'tell' and specific resource 'Pipeworx team', along with concrete examples (broken, missing, praise). It distinguishes itself from sibling tools which are mostly research/visibility 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?

Provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). Lacks explicit when-not-to-use, but the use cases are well defined.

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

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

Description adds context beyond annotations: explains self-aggregating from CF analytics-engine, no PII, caching details (5min-1h). Annotations already declare safe read-only, idempotent, non-destructive; description enriches with operational details.

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

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

Concise, well-structured with bullet points. No redundant sentences. Every sentence adds value.

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

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

Given simple tool with one param and no output schema, description covers purpose, usage, behavior, parameter, and caching. Complete for agent decision-making.

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?

Only one parameter with enum and schema description. Description adds nuance about shorter vs longer windows (hot vs steady-state). With 100% schema coverage, baseline is 3 but the added semantic tip 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?

Description clearly states the tool returns top tools, top packs, and total call volume over a window. The verb 'returns' and resource 'trending data' are specific. It distinguishes from siblings like search tools by focusing on aggregation.

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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical tool, and aligning use case. No exclusions or when-not-to-use, but the context is clear.

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

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

Description provides comprehensive behavioral details beyond annotations: explains three operational modes, partition checks, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against live CLOB depth, and when trades are not advisable. Annotations already indicate read-only, open-world, idempotent, non-destructive, and description aligns with these.

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 appropriately sized for a complex multi-mode tool. It begins with a one-line purpose, then systematically explains each mode and its nuances. Every sentence provides essential information, and there is no redundancy. The structure is logical: modes, then semantic anchor, partition filter, response, fill check, and reference to sibling 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 no output schema, the description covers the response structure (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, etc.) and explains the fill check process. It also references a sibling tool for further functionality. All critical aspects of the tool are addressed, making it self-sufficient for an AI agent to invoke correctly.

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

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

Despite 100% schema description coverage, the description adds substantial meaning: for event parameter, explains it takes a Polymarket event slug like 'fed-decision-may-2026' and walks child markets; for topic, explains cross-event scanning and provides examples like 'Strait of Hormuz traffic returns to normal'. It clarifies the behavioral impact of each parameter beyond the schema's brief 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and explains the specific arbitrage detection techniques. This differentiates it from sibling tools like polymarket_fill_risk, which is mentioned for custom sizing.

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 each parameter: 'Call with NO args for a trending_scan... pass event for... pass topic for...' Includes recommendations ('event recommended for a specific market') and provides examples of valid inputs. Also references sibling tool for alternative use case: 'For custom sizing use polymarket_fill_risk.'

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 discloses behaviors beyond annotations: caching at KV level keyed on all knobs, model family details with formulas, edge calculation net of slippage, Kelly fraction caps, diagnostics for empty segments. Annotations already indicate read-only, open-world, idempotent, non-destructive; description adds operational depth without contradiction.

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

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

The description is long but well-structured: front-loaded with purpose, then segment explanations, then knob details, then response structure. Each sentence carries informational weight. Could be slightly more terse, but the technical depth 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?

Given 9 parameters, no output schema, and complex behavior, the description is remarkably complete. It explains response structure including diagnostics, caching behavior, Fed handling, and edge calculation. An agent has sufficient information to invoke this tool correctly 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 100%; description adds marginal value by explaining parameter interactions (e.g., min_partition_leg_kelly versus min_kelly) and providing real-world context (Polymarket zero fees but slippage from bid/ask). Baseline 3, elevated to 4 due to additional semantic 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly mentions the intended use case 'what should I bet on today' and distinguishes from siblings by detailing unique methodology and segments.

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

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

The description provides clear guidance on when to use (discovering opportunities without paging hundreds of markets) and includes knob descriptions for filtering. It mentions Fed bets handled separately. However, it doesn't explicitly contrast with sibling tools like polymarket_edge_tracker or polymarket_arbitrage, leaving some ambiguity.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds valuable behavioral details: that decay numbers come from daily closes (not intraday), history depth is bounded by 60-day TTL, and snapshots only written on cache-miss. No contradictions with annotations.

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

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

The description is front-loaded with the purpose, but it is somewhat long and includes detailed response structure that could be more concise. Every sentence adds value, but overall length reduces 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?

Given no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations (60-day TTL, snapshot gaps). Parameters are fully covered. This provides a complete picture for 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?

Input schema covers both parameters with descriptions and defaults. The description reiterates these (days default 14 max 30, window default 1wk) but adds minimal new meaning beyond the schema. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay over time using daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description provides a clear usage scenario (distinguishing fresh vs. old edges) and implies when to use it. However, it does not explicitly state when not to use it or list alternatives, though the context is strong enough for an AI agent to infer appropriate 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 declare read-only, idempotent, and non-destructive behavior. The description goes beyond by detailing internal logic: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict (clean|degraded|cannot_fill).' It also warns about forced directional risk in basket mode. 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 lengthy but every sentence adds value given the tool's complexity. It is well-structured: starts with purpose, then modes, inputs, outputs, and usage guidance. While it could be slightly more concise (e.g., merging some details), the density of information is appropriate for a high-stakes 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?

Despite the lack of an output schema, the description comprehensively lists return fields for both modes (e.g., top_of_book, slippage_pp, capture_ratio, thin_legs, forced_directional_risk). It also explains the meaning of outputs like verdict and profit_usd. The context of when to use (pre-trade check) is fully covered. No gaps for this complexity level.

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

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

All four parameters are fully described in the schema (100% coverage). The description adds significant meaning beyond the schema: explains size_usd interpretation per mode (max spend vs target proceeds, settlement notional), side auto-default logic for basket mode, and provides default values and constraints (clamp 10–1,000,000). This enriches the parameter semantics.

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

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

The description explicitly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and provides specific use cases (before acting on polymarket_arbitrage or polymarket_edges). This differentiates it from sibling tools and gives a precise understanding of what the tool does.

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

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

The description includes explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable on thin books, partial fills create directional risk). This provides clear when-to-use and when-not-to-use context.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description goes far beyond by detailing safety fields (compatibility_warning, temporal_alignment, skipped_* counters) and explaining when spreads are or aren't meaningful. It reveals that the two venues can price the same outcome 2-25pp apart due to participant pool differences, and warns that aligned:false makes spreads meaningless. 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 well-structured: it starts with the core purpose, then explains modes, response format, and safety fields. Every sentence adds value, though the length is slightly high due to detailed safety explanations. The information is front-loaded and logically ordered, making it efficient for an AI agent to parse.

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

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

No output schema is provided, so the description must cover return structure. It does so by outlining the response fields: leg-by-leg prices, matched spread, compatibility_warning, temporal_alignment, and skipped_* counters. However, it could be more precise about the structure of matched_spread (e.g., array of objects). Given the tool's complexity, the description is fairly complete for an agent to understand expected output.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing the exact 10 pre-mapped topic values, explaining the overriding mechanism between topic and explicit parameters, and providing example values. This extra context helps the agent form correct parameter values beyond what the schema alone provides.

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

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

The description clearly states the tool's purpose: computing cross-venue spreads between Polymarket and Kalshi for the same resolving question. It uses specific verbs ('compare', 'detect') and resources ('cross-venue spread'), and distinguishes itself from sibling tools through its unique cross-platform functionality. The two operating modes (topic shortcuts and explicit pairings) are explicitly described.

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

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

The description provides explicit when-to-use guidance: for finding spreads when the same outcome is priced on both venues. It details two modes (topic shortcuts for pre-mapped events, explicit IDs for custom pairs) and includes a caution that pre-mapped topics often return compatibility_warning. It does not directly contrast with sibling tools like polymarket_arbitrage, but the context is clear enough for an AI agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that it returns attribute rows and geometry, providing context on output shape 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 with no wasted words. The first sentence states the purpose and lists parameters; the second gives a practical tip. Front-loaded and efficient.

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

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

For a tool with 6 parameters and no output schema, the description covers return type, parameter patterns, and connects to the sibling search_datasets. It is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds value by explaining how to use parameters (SQL-like where, comma-separated out_fields, order_by format) and gives a concrete usage example, significantly enhancing 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 it queries an ArcGIS Feature/Map Service layer, specifying the verb 'Query' and the resource. It mentions returning attribute rows and geometry, distinguishing it from siblings like search_datasets and layer_info.

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

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

The description says to use the URL from search_datasets, implying a prerequisite. It provides parameter examples and a concrete usage tip ('use where="1=1" + out_fields="*" to sample'). It does not explicitly mention when not to use, but the usage 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?

Description adds context beyond annotations: scoping to identifier, listing behavior when key omitted. Annotations already indicate readOnlyHint=true and idempotentHint=true, so description complements rather than repeats.

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

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

Three sentences, no wasted words. Front-loaded with main purpose, then use case, then linking to siblings. Efficient and structured.

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

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

Given simplicity (1 optional param, no output schema, clear annotations), description covers retrieval, listing, scoping, and pairing with sibling tools. 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% with a description for key. Description adds value by explaining that omitting key lists all keys, which is not in schema. Also clarifies the purpose of the key 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 uses specific verb 'retrieve' and identifies resource as saved values via remember. Clearly distinguishes from sibling tools like remember and forget by stating 'Pair with remember to save, forget to delete.' This makes purpose unambiguous.

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

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

Provides explicit context: 'Use to look up context the agent stored earlier.' Mentions alternative tools for saving and deleting. Does not explicitly state when not to use it, but the scope 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 declare readOnlyHint=true, indicating no state modification, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' implying a side effect of updating read status. This is a direct contradiction, severely undermining trust. The description also does not clarify the open-world or idempotent nature beyond what annotations already provide.

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

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

The description is a single paragraph with front-loaded purpose. Every sentence adds value, though the mention of an alternative HTTP endpoint could be considered extraneous but is still useful. It is efficient but not maximally 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?

With no output schema, the description explains return fields (source, citation_uri, raw event payload) adequately. It covers parameter behavior and polling suitability. However, the contradiction with annotations regarding mark_read side effects creates a gap in completeness, as the described behavior conflicts with the annotated read-only guarantee.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema by explaining parameter usage (e.g., 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)') and the effect of mark_read. This adds moderate value above the 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 begins with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It distinguishes itself from sibling tools like 'list_subscriptions' by focusing on events rather than subscriptions. The return fields are specified, making the tool's purpose unambiguous.

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

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

The description mentions 'Polls work fine' and notes an alternative access method (GET registry.pipeworx.io/alerts.json), suggesting when to use the tool versus an HTTP endpoint. However, it does not explicitly contrast with other sibling tools like 'subscribe' or 'query_layer', nor does it state when not to use this tool. The context is clear but lacks 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?

Disclosures beyond annotations: fans out to multiple sources, GDELT preferred over GNews with fallback on rate limit/5xx, USPTO soft-fails until reactivated, and 'since' format details. These are behavioral traits not captured by the annotations alone.

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

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

The description is information-dense but front-loaded with examples and purpose. It could be slightly more structured, but every sentence adds value. Not overly verbose given the complexity.

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

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

With no output schema, the description compensates by summarizing the return structure (grouped changes, total count, citation URIs). Covers purpose, sources, fallback, parameter formats, and sibling differentiation. Complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining 'since' format with examples and giving typical values (e.g., '30d'). Also clarifies 'value' accepts ticker or CIK. Moderate added nuance.

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

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

The description clearly states the tool provides a change feed for a company in a specific time window, using multiple sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling 'entity_profile' by specifying when to use each. Example queries at the start reinforce the purpose.

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

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

Explicit guidance on when to use this tool versus the sibling 'entity_profile' ('Use entity_profile instead when you want the static profile... regardless of window'). Also implies usage context via example queries and parameter explanation.

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 idempotent (idempotentHint=true) and non-destructive (destructiveHint=false). The description adds critical context: scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions.

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 purpose, second covers usage and details. Zero wasted words, front-loaded with the core 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 2-parameter tool with no output schema and well-documented annotations, the description covers persistence, scoping, and lifecycle—fully adequate.

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

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

Schema coverage is 100% with descriptions for both parameters, so the description adds minimal extra meaning beyond reinforcing examples. 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 ('save') and resource ('data'), enumerates clear use cases (resolved ticker, target address, etc.), and distinguishes from sibling tools 'recall' and 'forget' by naming them.

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

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

The description explicitly states when to use ('when you discover something worth carrying forward') and pairs with recall/forget, but does not provide explicit 'do not use when' conditions.

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, open-world, non-destructive behavior. The description adds that 'each call cascades through several lookup endpoints internally,' providing insight into performance and internal complexity. It also describes the output format, 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?

The description is front-loaded with example queries, followed by a clear usage directive, then structured type details. Every sentence adds value; no redundancy. It is compact yet comprehensive for the tool's complexity.

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

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

Given no output schema, the description fully explains what is returned for each type (ticker, CIK, name, citation for company; RxCUI, ingredient, brand, citation for drug). It also mentions internal cascading and that it replaces multiple manual lookups. This covers all necessary context for an agent.

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

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

Schema description coverage is 100% (both parameters described). The description adds significant value: examples for each type, clarification of auto-disambiguation, and details about output including citation URIs. This extra context compensates well above 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 clearly states the tool resolves names to canonical identifiers with specific examples ('ticker for...', 'find the CIK for...'). It distinguishes itself by noting it replaces 2-3 manual lookups, implying efficiency. The supported types are explicitly listed, making it easy to understand.

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 guides when to use: 'Use FIRST whenever you have a name but need an ID.' It details what each type returns (e.g., company returns ticker, CIK, company name, citation URI) and that other tools require these IDs as input. It implicitly tells when not to use—when already have the ID.

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 transparently states that the tool probes each entity with ai_visibility_check, ranks them by score, and returns a ranked list with score, confidence, and signal density. This adds behavioral context beyond the annotations (readOnlyHint, idempotentHint) which already declare it safe and idempotent. 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 only four sentences, front-loaded with the main purpose, and each sentence adds essential information: purpose, mechanism, use case, and return format. 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 moderate complexity (4 params, no output schema), the description is mostly complete. It explains the return format and the internal call to ai_visibility_check. However, it does not mention the entity count range (2-8) which is in the schema, but that is a minor gap. With good annotations and schema coverage, a 4 is appropriate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by stating that the first entity is treated as the 'subject' for narrative, which is not in the schema. 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 compares AI visibility across multiple entities side-by-side. It uses a specific verb ('compare'), a concrete resource ('AI visibility'), and distinguishes itself from siblings by focusing on AI presence rather than generic comparison, as seen in siblings like compare_entities.

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

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

The description explicitly provides a use case ('competitive AI-marketing audits') and a concrete question ('does Claude know about us as well as our competitors?'). It implies that for single entity checks, one would use ai_visibility_check, thus giving clear guidance on when to use this tool vs 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by detailing that it fans out to two services, returns specific fields, degrades gracefully with sources_failed, and notes that bundlephobia's first measurement can take 5-30s. 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 well-structured with a clear front-load of the composite nature, followed by usage guidance, return details, ecosystem scope, and performance caveat. Every sentence adds value without redundancy, making it appropriately sized for the tool's complexity.

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

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

The description fully covers what the tool does, when to use it, what it returns, and its limitations. Given the absence of an output schema, the detailed list of return fields compensates well. The partial failure and performance notes enhance completeness.

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

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

Schema coverage is 100% with both parameters described. The description adds context about acceptable scoped package names and default version behavior, but these are already implied by the schema descriptions. The baseline of 3 is appropriate as no significant additional semantics are provided.

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 is a composite check for npm packages, aggregating data from deps.dev and bundlephobia. It distinguishes itself from sibling tools by specifying its unique function of evaluating package safety, popularity, and size, which is not covered by other sibling tools like search_within or scan_competitor_ai_presence.

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

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

The description explicitly advises use when agents ask 'is X safe / popular / small' or 'what does adding lodash cost me'. It also specifies limitations: NPM ecosystem only in v1, and PyPI/Maven/Cargo/Go fall under deps.dev:version directly, guiding when not to use this tool. Partial failure behavior is also documented.

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 (readOnlyHint, idempotentHint, etc.) already indicate a safe, read-only operation. The description adds context by specifying the output structure (name, summary, record_count, url) and the intended workflow, 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?

Two sentences efficiently convey purpose, return fields, and usage guidance. No wasted words; information is front-loaded and well-structured.

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

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

For a simple search tool with three parameters and no output schema, the description is complete. It specifies all returned information and guides the agent on how to use the output, leaving 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 all three parameters with descriptions (100% coverage). The description adds value by providing examples ('parcels'), default values (limit 20), and clarifying the optional nature of org_id, going 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 it searches City of Mobile GIS open geospatial datasets by keyword, listing examples (parcels, zoning, etc.) and specifying return fields (name, summary, record_count, owner/org, Feature Service url). It distinguishes from sibling tools like query_layer and layer_info.

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

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

The description explicitly tells the agent to pass the returned url to query_layer/layer_info, providing a clear next step. While it doesn't explicitly contrast with alternatives, the context is sufficient for correct 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, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag. This is rich detail beyond annotations with 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 the core action. It is slightly wordy but every sentence adds value. Could tighten minor phrasing but overall efficient.

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

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

Despite no output schema, the description explains return format (passages with character offsets and similarity scores). It covers input constraints (200K char cap), search mechanics (500-char windows), and usage pairing. Complete for a retrieval tool with high annotation richness.

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

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

Schema coverage is 100% so the schema describes all 3 parameters. The description adds meaning by explaining usage of 'text' and 'query' with examples, and implies the 'limit' effect via 'top-N passages'. It adds value beyond the schema without repeating it.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article, tool result). It distinguishes from siblings like ask_pipeworx, compare_entities, deep_research, etc., by focusing on searching within pre-fetched text rather than fetching or comparing external data.

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

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

The description explicitly says to use when the record is too large for the prompt, and suggests pairing with ask_pipeworx_grounded for grounding. It provides context but does not explicitly list when not to use or alternatives beyond the sibling mention.

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 mutation (readOnlyHint=false), idempotency, and non-destructive behavior. The description adds rich behavioral context: returns subscription id, requires OAuth, supported types with examples, delivery channel details (always-on feed, email, SMS with caps, webhook with signing secret). No contradictions with annotations.

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

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

The description is front-loaded with the main action and return value, then provides detailed yet valuable information. Every sentence serves a purpose. Could be slightly tighter, but overall well-structured.

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

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

Given the tool's complexity (3 parameters, 2 required, no output schema, multiple subscription types and delivery channels), the description covers all necessary aspects: prerequisites, type-specific parameters, delivery options, and return value. It is fully adequate for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond schema: for 'type' it gives examples and semantics, for 'params' it provides type-specific structures, for 'delivery' it explains constraints (phone verification, SMS cap, webhook auto-disable). This greatly aids correct parameter usage.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (create) and resource (subscription), and distinguishes from sibling tools like list_subscriptions 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 clear context on when to use (creating a monitoring subscription) and prerequisites (requires Pipeworx OAuth account). It details delivery channels and limitations. However, it lacks explicit 'do not use if' statements, which would make it perfect.

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 that it returns example questions and can be focused by topic, but the safety profile is well-covered by annotations, so the description adds moderate 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 with a clear purpose, examples, and usage instructions. However, it is somewhat verbose with multiple example queries; could be slightly more concise while retaining all critical information.

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

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

Despite no output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and how the topic parameter modifies output. All critical information for selecting and invoking the tool is present.

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

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

Schema has 100% coverage with one optional parameter. The description provides detailed semantics: explains the effect of omitting vs providing `topic`, lists example values (e.g., 'finance', 'pharma'), and relates it to output categories, going well beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions for Pipeworx, serving as an onboarding entry point. It distinguishes itself from siblings like ask_pipeworx and discover_tools by specifying that it teaches what Pipeworx can do and how to call meta-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 states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning meta-tools, providing clear when-to-use and alternative guidance.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds crucial behavioral details: ownership enforcement and deactivation (not deletion). This context helps the agent understand safety and side effects beyond the schema.

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

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

Two sentences, each earning its place: first states core action, second adds ownership and behavior details. No fluff, front-loaded 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 simple one-parameter tool with no output schema, the description covers purpose, ownership, behavior (deactivation vs deletion), and links to 'recent_alerts' for history. Annotations cover idempotency and non-destructiveness. Context is complete.

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

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

Schema coverage is 100% for one parameter 'id', which is already described as 'Subscription id (uuid) returned by subscribe.' The description adds 'by id' but does not add significant new meaning beyond the schema's own description. 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?

Tool name 'unsubscribe' and title 'Unsubscribe from Alerts' pair with description 'Cancel a subscription by id.' The verb 'Cancel' and resource 'subscription id' are specific. It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Description states ownership enforcement ('you can only cancel your own subscriptions') and that the row is deactivated, not deleted, keeping historical events available via 'recent_alerts'. This provides clear context for when to use the tool, though it does not explicitly list alternatives or when not to use.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals the tool's reliance on SEC EDGAR + XBRL, its v1 limitations, and the structured return format (verdict, actual value, citation, delta). This adds meaningful context for safe usage.

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 detailed but well-organized, starting with illustrative queries followed by scope, mechanism, and output. Every sentence contributes, 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 fully explains the tool's purpose, usage, supported claims, return values, and efficiency gains, despite lacking an output schema. It provides sufficient detail for an agent to decide when and how to invoke it.

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 the single 'claim' parameter with a description. The tool description enhances this with examples and clarifies the expected natural-language format and domain, adding 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 function: fact-checking natural-language claims using authoritative sources. It includes specific query patterns and distinguishes itself by focusing on company-financial claims for public US companies, setting it apart from sibling tools like deep_research or compare_entities.

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

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

The description explicitly advises use when the agent needs to verify factual correctness of a user's statement. It defines the supported domain (company-financial claims) and notes efficiency gains over sequential calls. However, it does not list alternative tools for unsupported claim types.

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