Geoboundaries

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true. Description adds cost/API key disclosure ('BYO key — you pay Anthropic directly'), model defaults, and that it's a probe (non-destructive). No contradiction.

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

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

Three sentences: main action first, then model options/fees, then use cases. Every sentence earns its place; no filler.

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

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

With no output schema, description compensates by stating return structure (per-model {score, confidence, signals, raw_response} + combined). Covers parameters, cost, use cases, and behavioral traits fully.

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 meaningful examples for 'entity' (brand names), lists acceptable 'models', explains '_apiKey' necessity, and disambiguation role of 'context'.

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 specific verbs ('probe', 'score') and resources ('LLMs', 'visibility') with clear output (0-100 per model). It distinguishes from sibling tools by focusing on LLM knowledge probing, not general entity research or betting.

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 lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains default vs. API key requirement for Anthropic. However, it does not explicitly state when not to use this tool or contrast with alternatives like '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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it routes questions across many tools, returns structured answers with stable citation URIs, and lists supported domains. 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 key instruction 'PREFER OVER WEB SEARCH', followed by domains, functionality, usage hints, and examples. Every sentence is informative and earns its place. No redundant information.

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

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

For a router tool with no output schema, the description adequately explains what the tool does, what it returns (structured answers with citations), and when to use it. It lacks details on error handling or rate limits but is sufficient given the tool's complexity.

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

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

Schema coverage is 100%; all parameters (including aliases) have descriptions. The description provides examples of valid questions but does not add technical detail beyond the schema. Baseline 3 is appropriate as the schema is self-sufficient.

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

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

The description specifies the tool as a router for factual questions about structured data, listing many domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes from web search. It clearly states the verb 'routes' and the resource '3,436 tools across 780 verified sources', making 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 says 'PREFER OVER WEB SEARCH' and gives concrete usage contexts: questions about current/historical data, with examples. It implies when to use (factual structured questions) but does not explicitly state when not to use or name alternatives, though the sibling list suggests alternatives like web search or other 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: resolution mechanism with confidence levels and alternatives, fan-out logic per category, response shapes with specific fields (e.g., edge_pp, kelly_fraction_half, market_move_warning), safety short-circuiting for low-confidence or closed markets, and fallback handling for news. No contradictions with annotations.

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

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

The description is long (500+ words) but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every sentence adds value given the tool's complexity. Some redundancy exists (e.g., multiple safety mentions), but overall it is efficiently organized for its depth.

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

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

Despite no output schema, the description comprehensively explains return fields and shapes for market, analysis, evidence, resolver contract, parent event, and news fields. It covers edge cases like low-confidence matches, closed markets, wide spreads, and fallback mechanisms. Given the tool's multiple data sources and complex fan-out, this description provides complete contextual guidance.

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 substantial meaning beyond the schema. For the 'market' parameter, it explains it accepts slugs, URLs, or question text and provides examples. For 'depth', it clarifies the difference between 'quick' and 'thorough'. For 'include_raw', it explains the trade-off between response size and detail. This fully compensates for any schema minimalism.

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 researches a Polymarket bet by pulling relevant Pipeworx data. It provides examples of valid inputs and explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This distinguishes bet_research from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on holistic 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 usage scenarios: 'Use for "should I bet on X"...' and warns about cases where the tool should not be trusted (low-confidence matches, closed markets). It includes detailed classifier lists, fan-out examples, and guidance on inspecting resolver fields like 'market_match_confidence' and 'suggestions'. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already set readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds specifics: for companies, it pulls latest 10-K data and handles off-calendar fiscal years; for drugs, it pulls FAERS, FDA approval counts, and trial counts. No contradictions.

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

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

Description is a single well-structured paragraph, front-loaded with key use cases. Every sentence adds necessary information with no redundancy.

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

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

Given the tool's complexity, the description fully covers both entity types, input format, data sources, sorting, and output format (paired data + URIs). No gaps.

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

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

Schema has 100% coverage but description adds significant value: explains that 'values' should be tickers/CIKs for companies and drug names for drugs, and details what each type retrieves.

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 performs side-by-side comparisons of 2–5 companies or drugs, with concrete example queries. It distinguishes itself from sibling tools like entity_profile by being a parallel comparison rather than single lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8–15 sequential lookups, providing clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that results include full input schemas with curated examples and are ready to call directly, providing useful behavioral context beyond annotations. No contradiction.

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

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

The description is fairly long but front-loaded with purpose and domains, making it clear. A slight trim of the domain list could improve conciseness, but it remains efficient overall.

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

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

Given no output schema, the description adequately explains what is returned (top-N relevant tools with names, descriptions, input schemas, examples). The annotations cover safety, and the description completes the context for a discovery tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining that query accepts multiple aliases (task, q, search, description) and providing examples, but the core parameter meaning is already captured by 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 finds tools by describing data or task, enumerates specific domains (e.g., SEC filings, FDA drugs, stocks), and explains that it returns top-N relevant tools with full schemas, distinguishing it from sibling tools which are concrete operations.

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 to call this tool FIRST when many tools are available and the agent wants to see options, not just one answer. This provides clear context for when and how to use it versus alternative 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?

Discloses soft-fail for patents, GDELT→GNews fallback, and limitation to 5 filings. Adds context beyond annotations (readOnlyHint, openWorldHint, idempotentHint) 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?

Packed with information but front-loaded with examples and clear flow. Slightly dense but every sentence earns its place; could be structured with bullet points for improved readability.

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

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

Covers input format, return fields, data sources, and fallbacks. Without output schema, it adequately describes return values. Lacks pagination details but is overall 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 covers 100% of parameters with descriptions. Description adds example values, constraints (no names), and references resolve_entity, providing extra semantic value beyond schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company in one parallel call, listing sources and return fields. It distinguishes from siblings like resolve_entity by specifying input requirements.

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 'ALWAYS PREFER over chaining single-pack lookups' for holistic views, and instructs to use resolve_entity first if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

The description adds context beyond annotations (e.g., clearing sensitive data, pairing with other tools). Annotations already indicate destructiveHint=true and idempotentHint=true, which align with the description. No contradiction.

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

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

The description is concise, with two sentences that front-load the purpose and usage. Every sentence adds value with no waste.

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

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

For a simple delete operation with one required parameter and no output schema, the description is complete. It covers purpose, usage context, and related tools.

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 a clear description for the 'key' parameter. The description's mention of 'by key' is redundant with the schema. No additional semantics 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 'Delete a previously stored memory by key', specifying the verb 'delete' and the resource 'memory by key'. It also distinguishes itself from sibling tools 'remember' and 'recall'.

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

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

Explicit usage guidelines are provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, implying alternatives. However, it does not explicitly state when not to use it.

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

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

The description adds value beyond annotations by detailing the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also discloses the output format. No contradictions with annotations (readOnly, idempotent, etc.).

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 plus a list. It is front-loaded with the main purpose and every sentence adds essential information. 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 simple tool (2 params, no output schema, but good annotations), the description covers purpose, process, output format, and use cases. It is fully adequate for an agent to understand and 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%, so the schema already documents both parameters thoroughly. The description repeats the schema descriptions verbatim ('default 25, max 50') without adding new meaning, 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 'Generate a production-ready llms.txt file for any URL', specifying the verb and resource. It distinguishes from siblings by listing specific use cases like 'auditing how an AI crawler would see a competitor', which differentiates it from other AI 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?

The description explicitly provides use cases ('Useful for: ...'), giving clear context on when to use it. However, it does not explicitly state when not to use it or mention alternatives, though the sibling context implies differentiation.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining what the return data includes (e.g., unit count, source) and the implications of the default product (CC-BY), without contradicting annotations.

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

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

The description is a single coherent paragraph that efficiently covers purpose, parameters, and defaults. It is well-structured and front-loaded, though could be slightly more streamlined.

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 the return values (metadata fields and download URLs) and parameter options, making it complete for the tool's intended use without unnecessary details.

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

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

With 100% schema coverage, the baseline is 3, but the description adds meaning by providing concrete examples (USA, FRA) for ISO3, defining ADM levels with real-world equivalents, and clarifying the default product and its license.

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 administrative boundary metadata for a country, listing specific outputs like unit count, year, source, license, and download URLs. It distinguishes itself from the sibling 'get_geometry' by focusing on metadata rather than geometry.

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 for parameter usage, including ISO3 country code examples, ADM level definitions, and product defaults. However, it lacks explicit guidance on when to use this tool versus alternatives like 'get_geometry'.

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 beyond annotations: warns about large payloads (several MB), explains the 4 MB limit, states it returns only simplified geometry, and clarifies the 'ALL' level exclusion. All annotations (readOnlyHint, etc.) are consistent and description adds valuable 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?

Single paragraph of four sentences, front-loaded with the core purpose, followed by warnings and usage guidance. No redundant or unnecessary 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?

Despite no output schema, the description sufficiently explains what is returned (simplified GeoJSON FeatureCollection), the limitations (large payloads, ~4 MB cap, not valid for ALL), and usage preference. Complete for the tool's complexity and context.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds minimal parameter-specific info beyond schema (e.g., mentions gbOpen default and CC-BY license, but schema already has enum descriptions). The payload warnings are about behavior, not parameter meaning.

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

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

The description clearly states the verb 'Fetch', the resource 'simplified GeoJSON FeatureCollection geometry', and the scope 'country/ADM level'. It distinguishes from sibling tool 'get_boundaries' by explicitly naming it and explaining when to prefer the alternative.

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

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

Explicit guidance: 'Prefer get_boundaries unless you explicitly need the coordinates.' Also states what not to use ('Not valid for adm="ALL"') and provides alternative for large payloads ('use get_boundaries and download the URL directly').

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

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

Annotations indicate write operation (readOnlyHint=false) with no destructiveness. The description adds rate-limit and quota-free details, which are beyond annotations. It does not contradict annotations, and the added constraints are accurate.

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 moderately long but each sentence serves a purpose. It front-loads the core action, then covers usage rules and constraints. It could be slightly more concise, but it remains efficient and scannable.

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

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

Given the tool has 3 parameters, nested objects, and no output schema, the description provides thorough context: feedback categories, optional context fields, rate limits, and behavioral guidance. It ensures the agent knows how to use the tool correctly.

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

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

Schema coverage is 100% and schema descriptions are clear. The tool description augments this by explaining the meaning of each enum option (e.g., bug vs wrong data, feature vs missing tool) and constraints on the message field (1-2 sentences, 2000 chars). This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature, data_gap, praise) and distinguishes from siblings (no other feedback tool exists).

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 specifies when to use each feedback type (bug for wrong data, feature for missing tools, etc.), advises against pasting end-user prompts, and discloses rate limits (5 per identifier per day) and quota exemption. This provides clear guidance on appropriate usage.

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 and idempotent behavior. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and that it's a self-aggregating signal. No contradiction with annotations.

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

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

Extremely concise: three sentences, with bullet-point use cases. Every sentence adds value and the overall structure is clean and front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description covers what it returns, derivation method, privacy, caching, and usage scenarios. No gaps identified.

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 enum and description for the only parameter. The description adds semantic value by explaining the difference between shorter and longer windows ('hot right now' vs 'steady-state demand'), which is not in the schema description.

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

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

The description clearly states that it returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from siblings like 'discover_tools' by focusing on aggregate usage trends rather than tool discovery or metadata.

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 choice, seeing alignment). While it doesn't explicitly state when not to use it or list alternatives, the context is clear and sufficient for appropriate usage.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds significant behavioral context: partition check expecting sum ≈1 with deviations >3pp triggering signals, semantic anchor with Jaccard similarity threshold, and partition filtering with placeholder fraction. This fully discloses the tool's behavior beyond the annotations.

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

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

The description is comprehensive but verbose. It front-loads the key requirement and then explains both modes with technical details. Some sentences are dense and could be split or shortened for readability. It is structured logically but lacks 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 the complexity of the tool and the absence of an output schema, the description covers all essential aspects: input requirements, mode selection, algorithmic behavior (monotonicity, partition checks), filtering criteria, and response structure. It could be slightly more systematic (e.g., bullet points for response fields), but it is largely 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%, so both parameters are described. The description adds substantial meaning: recommended usage for 'event' vs 'topic', example values, and details on how the parameters affect behavior (e.g., cross-event mode catches patterns missed by single-event). This significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (single-event and cross-event) with specific verb+resource and provides examples, making its purpose unambiguous.

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

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

The description explicitly requires one of 'event' or 'topic', explains when to use each mode, and notes that calling with no args fails. It provides concrete examples of valid inputs. However, it does not mention when not to use this tool compared to its siblings (e.g., polymarket_edges), so it lacks explicit exclusions.

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

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

The description adds extensive behavioral context beyond annotations: caching (1h KV), response structure (by_segment, diagnostics), and knob effects (e.g., min_kelly skipping small opportunities). It aligns with readOnlyHint and idempotentHint annotations.

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

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

The description is dense but well-structured with clear segments and front-loaded purpose. Every sentence adds value, though length could be slightly reduced for perfect 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 the complexity (9 params, 3 segments, diagnostics, caching), the description covers all key aspects: response structure, interpretation of edges, knob usage, and segment details. No output schema exists, so description compensates fully.

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%, and the description enriches parameter meaning (e.g., min_kelly skips too-small opportunities, min_edge_pp net of slippage, min_partition_leg_kelly for per-leg Kelly). It explains nuanced behavior beyond schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for daily betting discovery. It distinguishes from siblings like polymarket_arbitrage and bet_research by detailing unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT).

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 frames the tool as 'what should I bet on today' and notes it avoids paging hundreds of markets. However, it does not explicitly state when not to use it or provide alternatives among siblings (e.g., polymarket_arbitrage, bet_research).

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. The description adds extensive behavioral context: compatibility_warning conditions, temporal_alignment, skipped_cross_type, and that many pre-mapped topics return warnings. 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 well-structured with clear sections (modes, response, safety fields). Every sentence adds necessary information, though it could be slightly more concise without losing meaning.

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

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

Without an output schema, the description adequately explains the return structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment). Given the tool's complexity, it covers all necessary aspects for correct invocation and interpretation.

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

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

Schema already covers all three parameters with descriptions and examples (100% coverage). The description adds value by explaining the two modes (topic vs explicit), that explicit overrides topic, and listing the shortcuts. This enhances understanding 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 it calculates cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb+resource. It also distinguishes from siblings by being the only tool in the list that explicitly handles spreads across these two venues.

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 (to find spreads) and when not to use (when compatibility_warning fires, indicating non-equivalent bet shapes or unrelated events). It also sets expectations that pre-mapped topics may not be tradeable, providing clear usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. Description adds valuable behavioral context: scoping details (IP, key hash, account ID), behavior when omitting key (lists all), and that it complements remember/forget. No contradictions.

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

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

Three sentences, each earning its place: function, usage rationale, scoping and pairing. Front-loaded with action verb and outcome. No 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 read-only, idempotent tool with no output schema, the description fully covers functionality, scoping, and relationship to sibling tools. No gaps remain.

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

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

Schema covers the sole parameter 'key' with 100% description coverage. Description reiterates the omit-to-list behavior already in schema, adding no new semantic insight beyond schema.

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

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

Description clearly states verb 'retrieve' and resource 'memory', distinguishes from siblings 'remember' and 'forget'. It specifies both retrieving a single key and listing all keys, 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?

Explicitly states when to use: look up context stored earlier without re-deriving. Mentions scoping to user identifier and pairing with sister tools remember and forget. Provides clear context for usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: fans out to multiple sources, fallback logic, USPTO soft-fail, and output structure (changes grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is a single well-structured paragraph: starts with common queries, then details sources, since parameter, output, and alternative. Every sentence adds value, no fluff. Front-loaded and easy 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?

With no output schema, the description explains return format adequately. It covers all necessary aspects: what data sources are queried, how since works, what to expect in output, and when to use a different tool. Complete for an agent to make informed use.

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

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

Schema coverage is 100%, baseline 3. But description adds significant meaning: explains since accepts ISO and relative formats with examples, suggests '30d' or '1m' for monitoring, clarifies value can be ticker or CIK, and notes type only supports 'company'. This goes well 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 provides a change feed for a company from multiple sources (SEC, GDELT/GNews, USPTO) over a time window. It uses specific verbs like 'change feed' and 'fans out', and distinguishes from sibling tool entity_profile by specifying when to use the alternative.

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

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

It explicitly lists example queries ('what's new with X', 'latest on Y') to signal when to use, and directs to entity_profile for static profiles. It also explains source behavior (GDELT preferred, GNews fallback, USPTO soft-fail) and provides since parameter format guidance.

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

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

The description adds significant behavioral context beyond annotations: scoping by identifier, persistence differences (authenticated vs. anonymous), and a 24-hour retention limit. Annotations only indicate non-read-only, idempotent, non-destructive; the description enriches these with concrete 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?

The description is concise yet comprehensive, with each sentence serving a distinct purpose: purpose, usage condition, technical details, and pairing. It is front-loaded with the core action and efficiently includes all necessary 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 (no output schema, two string parameters), the description fully covers all aspects: what it does, when to use, behavioral nuances, and integration with siblings. No gaps remain for the agent to infer.

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 naming conventions for keys (e.g., 'subject_property') and clarifying that value can be any text. This provides useful guidance beyond the schema's generic descriptions, justifying a 4.

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

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

The description clearly states the tool's verb and resource: 'Save data the agent will need to reuse later.' It also specifies the mechanism ('key-value pair scoped by your identifier') and distinguishes from sibling tools like recall and forget by mentioning pairing.

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

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

The description explicitly says when to use: 'when you discover something worth carrying forward.' It also provides clear alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives the agent full guidance on when and how to use the 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?

Already supported by annotations (readOnly, idempotent, openWorld). Description adds that each call cascades through multiple internal endpoints, replacing 2-3 manual lookups. This provides extra behavioral detail beyond annotations.

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

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

Concise single paragraph, front-loaded with purpose and usage directive. Every sentence adds value. Structure is clear with introductory examples and type breakdown.

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?

Comprehensive coverage of both entity types, including return format, citation URIs, and internal cascading. No output schema, but description fully explains output. Suitable for a complex resolver 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 100% with clear enum and descriptions. Description adds extensive return details per type (e.g., 'returns ticker + 10-digit CIK + company_name...') that go beyond schema. Rich 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?

Description starts with example queries, clearly states it resolves names to canonical identifiers, and specifies supported types (company, drug) with return details. Distinguishes from siblings by focusing on identifier resolution.

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 FIRST whenever you have a name but need an ID.' Provides clear context for when to use. Lacks explicit exclusions or alternatives but the directive is strong.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) indicate safe, non-destructive behavior. Description adds that it probes each entity with ai_visibility_check and returns a ranked list with scores, confidence, and signal density, which is transparent about the process and output.

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 pack purpose, method, and output without excess. Front-loaded with action and result, though slight redundancy could be trimmed. Efficient overall.

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

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

Given 4 parameters, no output schema, but strong schema descriptions and annotations, the description adequately explains the return structure (ranked list, score, confidence, signal density). It covers the probing mechanism and use case, making it complete 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 coverage is 100% with descriptions. The description adds meaning beyond schema by noting the first entity is treated as 'subject' and context disambiguates common names, which enhances 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?

Description clearly states it compares AI visibility across multiple entities side-by-side using ai_visibility_check and ranks results. It specifies verb 'compare' and resource 'AI visibility', and distinguishes from siblings by focusing on competitive audits.

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 usefulness for competitive AI-marketing audits and provides an example question. It implies when to use (comparing multiple brands) but lacks explicit when-not or direct alternative naming, though siblings like ai_visibility_check serve as obvious alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, not destructive. Description adds that it fans out to external services (deps.dev, bundlephobia), partial failures degrade gracefully, and that bundlephobia's first measurement can take 5-30 seconds. No contradictions.

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

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

The description is long but every sentence adds value. It is well-structured: purpose, usage, details, limitations, 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 complexity (external services, partial failures, multiple data sources), the description is thorough. It explains the return structure (summary block, per-advisory detail, links, alternative versions) and limitations (NPM only, bundlephobia timing). Without an output schema, this compensates well.

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 that scoped packages are accepted and version defaults to latest, which is mildly helpful but does not significantly extend 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's a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from sibling tools by specifying the ecosystem (NPM only) and mentioning deps.dev:version as an alternative for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also notes when not to use (other ecosystems) and provides an alternative (deps.dev:version for PyPI/Maven/etc.).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns a structured verdict (confirmed, approximately_correct, refuted, inconclusive, unsupported), includes actual value with a pipeworx:// citation, and percent delta. It also explains that the tool uses SEC EDGAR + XBRL, providing transparency into the data source.

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 efficiently packs essential information: usage examples, domain, output format, and value proposition. It is front-loaded with clear action examples. However, it could be slightly more structured (e.g., bullet points for output verdicts) to improve scanability.

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 that there is no output schema, the description fully explains the return values (verdict, structured form, actual value, citation, percent delta). It also covers the domain, input format, and the tool's efficiency advantage. No additional information is needed for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with a description for the 'claim' parameter. The description enhances this by giving concrete examples of acceptable claim formats (e.g., 'Apple's FY2024 revenue was $400 billion') and by clarifying the natural-language nature. This adds meaningful context beyond the schema's brief description.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources, specifically focusing on company-financial claims. It provides clear examples of trigger phrases like 'Is it true that…' and 'fact check', and specifies the supported domain (public US company financials via SEC EDGAR). This distinctly differentiates it from sibling tools.

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

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

The description clearly indicates when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes that this tool replaces 4-6 sequential calls for efficiency. However, it does not explicitly state when not to use it or name specific alternatives, though the domain restriction (company-financial claims) is implied.

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