nominatim

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

Annotations already indicate readOnly, openWorld, and idempotent hints, so the description adds value by detailing default model, API key requirements, and return structure (per-model results). No contradictions.

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

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

Two sentences, front-loaded with main action, efficient and without wasted words. 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) and covers all parameters. Sufficient for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, and the description enriches each parameter with examples (e.g., 'Pipeworx' for entity, 'sk-ant-...' for API key) and clarifies the role of 'context' for disambiguation.

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 an entity and scores visibility, with specific verb and resource. It differentiates from siblings like 'compare_entities' and 'scan_competitor_ai_presence' by focusing on probing LLMs directly.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional API key. It does not explicitly state when not to use, but the context is sufficient.

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

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

With no annotations provided, the description carries full burden. It discloses key behavioral traits: the tool automatically selects data sources and fills arguments, handles natural language questions, and returns results. It doesn't mention rate limits, authentication needs, or error conditions, but provides substantial operational context beyond basic purpose.

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 perfectly front-loaded with the core purpose in the first sentence. Every subsequent sentence adds value: explaining the mechanism, contrasting with alternatives, and providing concrete examples. Zero wasted words or 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 single-parameter tool with no annotations and no output schema, the description provides excellent context about how the tool works, when to use it, and what to expect. The examples effectively illustrate both input format and potential output types. It could mention response format or error handling, but 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 description coverage is 100%, so the schema already documents the single 'question' parameter. The description adds meaningful context by emphasizing 'plain English' and 'natural language' input, and provides concrete examples that illustrate the expected parameter format and scope beyond what the schema 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: 'Ask a question in plain English and get an answer from the best available data source.' It specifies the verb ('ask'), resource ('answer'), and mechanism ('Pipeworx picks the right tool, fills the arguments'). It distinguishes from siblings by emphasizing natural language input rather than structured queries.

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 this tool: 'No need to browse tools or learn schemas — just describe what you need.' It provides clear alternatives by implication (use other tools when you want to browse or use structured schemas). The examples further illustrate appropriate use cases.

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 explains internal steps (resolve, classify, fan-out, return comparison) which adds value beyond annotations; annotations already indicate read-only and open-world, but description fills in behavioral 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?

Description is concise yet comprehensive, front-loading the core purpose and usage, with every sentence adding 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?

Description covers purpose, usage, parameter details, internal behavior, and return content, making it complete for a tool with no output schema.

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

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

Description provides examples and context for the market parameter beyond schema, and explains depth default, 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 uses a specific verb-resource combination ('Research a Polymarket bet') and explains it pulls Pipeworx data, distinguishing it from general tools like ask_pipeworx.

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

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

The description provides explicit use cases ('should I bet on X?', 'what does the data say...') and implies context for use, though it does not explicitly mention when to use alternatives like ask_pipeworx for general questions.

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?

No annotations are provided, so the description must fully disclose behavioral traits. It mentions data sources (SEC EDGAR for companies, FDA for drugs) and return format (paired data + URIs), but lacks details on side effects, authorization needs, rate limits, or consistency guarantees. This is adequate but not comprehensive.

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 extremely concise—two sentences—and front-loads the core purpose. Every sentence provides essential information without any fluff. Highly 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 no output schema, the description adequately explains return type and data fields. It covers the primary use case and efficiency benefit. Minor omissions like error handling or response limits do not significantly reduce completeness for a comparison 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. The description adds value by explaining the actual data fields returned for each type (e.g., revenue, net income) and how to specify values (tickers/CIKs vs. drug names). This goes beyond the schema's generic 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 compares 2–5 entities side by side, specifying two data types (company and drug) and the exact data fields retrieved. It distinguishes itself from siblings by noting it replaces 8–15 sequential calls, making its purpose unique.

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

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

The description explicitly explains when to use the tool (for side-by-side comparison of companies or drugs) and quantifies the efficiency gain (replaces multiple calls). However, it does not explicitly state when not to use it or suggest alternatives, though the sibling list makes the tool's niche 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns 'the most relevant tools with names and descriptions' and mentions a default/max limit (implied from schema), but doesn't cover other behavioral aspects like error handling, authentication needs, rate limits, or whether it's read-only. The description adds some context but leaves gaps for a search tool.

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

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

The description is concise and well-structured in two sentences. The first sentence states the purpose, and the second provides usage guidelines. Every sentence earns its place with no wasted words, and key information is 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?

Given the tool's moderate complexity (search function with 2 parameters), no annotations, and no output schema, the description is reasonably complete. It covers purpose, usage context, and return content, but lacks details on output format (e.g., structure of returned tools) and error cases. For a search tool without annotations or output schema, it does well but could be more comprehensive.

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 schema already fully documents both parameters (query and limit). The description adds marginal value by emphasizing the natural language aspect of the query ('by describing what you need') and the catalog context, but doesn't provide additional syntax or format details beyond what the schema specifies. Baseline 3 is appropriate when schema does the heavy lifting.

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: 'Search the Pipeworx tool catalog by describing what you need.' It specifies the verb ('Search'), resource ('Pipeworx tool catalog'), and method ('by describing what you need'), distinguishing it from sibling tools like lookup, reverse_geocode, and search_address which appear to be more specific data lookup tools rather than a catalog search.

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

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

The description provides explicit usage guidance: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This gives clear context on when to use it (large tool catalogs, initial discovery) and implies alternatives (other tools for specific tasks once identified), though it doesn't name specific 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?

No annotations provided, so description carries full burden. It discloses that results contain URIs and that the call replaces 10–15 sequential calls. Could explicitly state read-only nature, but overall 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?

Two sentences front-load purpose and then detail the company profile contents. No redundant phrases, efficient structure.

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 what the tool does, what it returns (URIs), and when not to use it. Missing explicit read-only declaration but otherwise complete for a profile 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. The description adds value by explaining type='company' is the only current option and that value accepts ticker or CIK, not names, with a suggestion to use resolve_entity for names.

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 returns a 'full profile' across multiple packs, specifying what's included for type=company (SEC filings, XBRL data, patents, news, LEI). It distinguishes from siblings like resolve_entity (name resolution) and compare_entities (comparison).

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 guidance: use for comprehensive profiles; not for names (use resolve_entity first) or federal contracts (use usa_recipient_profile directly). This helps the agent decide when to invoke.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool deletes a memory, implying a destructive mutation, but doesn't cover critical aspects like permissions needed, whether deletion is permanent or reversible, error handling for non-existent keys, or rate limits. For a destructive tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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

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

The description is a single, efficient sentence with zero waste—'Delete a stored memory by key.' It is front-loaded with the core action and resource, making it easy to parse quickly. Every word contributes directly to understanding the tool's purpose without redundancy or fluff.

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

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

Given the tool's destructive nature, lack of annotations, and no output schema, the description is insufficiently complete. It doesn't explain what happens post-deletion (e.g., confirmation, error messages), the scope of 'memory' in this context, or how it integrates with sibling tools. For a mutation tool with no structured safety or output information, more detail is needed to guide safe and effective use.

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

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

The input schema has 100% description coverage, with the 'key' parameter documented as 'Memory key to delete'. The description adds minimal value beyond this, only reinforcing the parameter's role. With one parameter and high schema coverage, the baseline is 3, but the description's concise alignment with the schema earns a slight boost for clarity, though it doesn't provide additional context like key format or examples.

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

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

The description clearly states the action ('Delete') and the resource ('a stored memory by key'), making the purpose immediately understandable. It distinguishes from siblings like 'remember' (create) and 'recall' (retrieve), though it doesn't explicitly contrast with them. The verb+resource combination is specific but could be more detailed about what 'memory' entails.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., that the memory must exist), exclusions, or comparisons to sibling tools like 'discover_tools' or 'lookup'. Usage is implied only by the action 'delete', leaving the agent to infer context without explicit direction.

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, idempotent, etc.) already indicate safe, non-destructive behavior. Description adds detailed behavioral steps: fetches page, extracts title/description/links, emits standard format. 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 concise sentences, front-loaded with purpose. Every sentence adds value: purpose, process, use cases. 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 no output schema, description sufficiently explains output format (standard llms.txt markdown, single text blob). Schema covers inputs fully. No gaps.

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

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

Schema has 100% coverage with clear param descriptions. Description adds no additional parameter information beyond what schema 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?

Description states specific verb 'generate', resource 'llms.txt file for any URL', and benefit for AI crawlers. Clearly distinct from sibling tools which are unrelated.

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?

Lists three explicit use cases (client site indexing, own project drafting, competitor auditing). Lacks explicit when-not-to-use or alternatives, but no direct sibling overlaps.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It explains the ID format and prefixes but doesn't mention important behavioral aspects like whether this is a read-only operation, what happens with invalid IDs, rate limits, authentication requirements, or what the return format looks like.

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 perfectly concise - a single sentence that efficiently communicates the tool's purpose, parameter format, and object type mapping. Every word earns its place with zero wasted text.

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 annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, how errors are handled, or important behavioral constraints. While the purpose is clear, the description lacks sufficient context for an agent to fully understand the tool's behavior.

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

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

The schema description coverage is 100%, so the schema already fully documents the single parameter. The description repeats the ID format and prefix information from the schema without adding significant additional semantic context beyond what's already in the structured data.

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 specific action ('Look up') and resource ('OpenStreetMap objects by their OSM IDs'), with explicit mention of the three object types (node, way, relation). It distinguishes from sibling tools by focusing on ID-based lookup rather than geocoding or address search.

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

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

The description provides clear context for when to use this tool (looking up objects by OSM IDs) but doesn't explicitly mention when not to use it or name alternatives. The sibling tools (reverse_geocode, search_address) serve different purposes, but the description doesn't contrast with them.

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?

No annotations are provided, so the description must cover behavioral traits. It discloses a rate limit of 5 messages per day and notes it is free, but does not describe if the tool is synchronous, returns a response, or any side effects.

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 four sentences covering purpose, usage, content guidelines, and rate limiting. It is front-loaded with the primary purpose and remains 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 feedback tool with 3 parameters and no output schema, the description covers purpose, content guidelines, and rate limiting. It could mention what happens after sending (e.g., no response) but 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% and includes detailed enum descriptions for 'type'. The description adds valuable guidance on what to include in 'message' (specific tool, error, missing data) and length limits 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 'Send feedback to the Pipeworx team' and lists specific use cases (bug reports, feature requests, missing data, praise). No sibling tool serves a similar purpose, so differentiation is clear.

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 content ('Describe what you tried... do not include the end-user's prompt verbatim') and mentions rate limiting. It does not explicitly state when not to use it, but the context is sufficient.

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

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

Annotations provide readOnlyHint, openWorldHint, etc. Description adds: source (CF analytics-engine), privacy (no PII), data content (pack, tool, count), and caching behavior (5min-1h). 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?

Paragraph is clear and front-loaded with purpose. Lists three use cases in a readable manner. Could be slightly more concise but 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?

Despite no output schema, description explains return content (top tools, top packs, call volume) and caching. Covers privacy and source. Sufficient for an agent to understand 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?

Only parameter 'window' is well-documented in schema with enum. Description adds extra context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances understanding beyond enum values.

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

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

Clearly states it returns top tools, top packs, and total call volume over time windows. Uses specific verb ('returns') and resource (top tools/packs). Distinct from siblings like 'discover_tools' which focuses on discovery, not trending.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment). Implicitly tells when not to use it (if not interested in trending). Could name alternatives but not required.

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

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

Description discloses key behaviors: walking child markets, searching across events, grouping, and checking monotonicity. Annotations already state readOnlyHint=true and destructiveHint=false, so no contradiction. Adds context beyond annotations about the tool's search and comparison logic.

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 concisely structured with clear separation of modes and examples. While slightly lengthy, each sentence earns its place by adding useful detail like the rationale for cross-event mode. Slightly less concise than ideal but well-organized.

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

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

Given no output schema, the description thoroughly covers the tool's purpose, modes, and edge cases. It explains the monotonicity checking and why cross-event mode is needed. All relevant aspects for an AI agent to select and invoke the tool correctly are addressed.

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

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

Input schema has 100% coverage with two optional parameters, each described. Description adds meaning by explaining how each parameter triggers a different mode (event vs topic) and the significance of topic mode for cross-event arbitrage, which goes beyond 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 uses specific verb 'find' and resource 'arbitrage opportunities on Polymarket', clearly distinguishing two modes (event and topic) and explaining the monotonicity checking logic. It differentiates from siblings like polymarket_edges by focusing on arbitrage through monotonicity violations.

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 two modes and when to use each: event mode for a single event slug, topic mode for cross-event searches. Provides rationale for topic mode catching cases that event mode misses, giving clear guidance on alternative 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 signal safe read-only behavior; description adds rich detail: scanning top markets, grouping by asset, single fetch of price history, model probability computation, ranking by |edge|, and output with direction. 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 well-structured with a clear, front-loaded purpose. It is concise with about four sentences, though could be slightly tighter.

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, but the description explains the return format (top N list with direction) and underlying model/data sources (FRED, coinpaprika). It is sufficient for an agent to understand the tool's capabilities and limitations.

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 does not add new semantic information beyond what the schema already 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 scans top Polymarket markets, finds discrepancies with Pipeworx data, and returns ranked edges with direction. It distinguishes itself from siblings like polymarket_arbitrage and bet_research by focusing on opportunity discovery.

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 built for the 'what should I bet on today' question and explains the method (V1 crypto-price bets). While it doesn't state when not to use or name alternatives, the usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive hint. The description adds valuable behavioral context: the spread is a real arb signal, and it details the two modes and return format. No contradiction with annotations.

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

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

The description is well-structured with two modes clearly separated. It is slightly lengthy but every sentence adds value. Front-loaded with the core purpose. Minor room for tightening, 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 (two modes, three optional params, no output schema), the description is fairly complete. It explains inputs, modes, and output format (prices and spread). However, lacking an output schema, a more detailed example or edge-case handling (e.g., mismatch) would improve completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant extra meaning: explains that 'topic' auto-maps to both venues, and that explicit tickers override the mapped side, plus describes the return structure (prices and spread).

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 cross-venue spread tool between Kalshi and Polymarket, with a specific verb ('cross-venue spread') and resource ('the same resolving question'). It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on cross-venue, not within-venue.

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

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

The description explains two usage modes: topic shortcuts for common events and explicit ticker/slug for custom pairings. It implies when each mode is appropriate (pre-mapped vs custom), but does not explicitly state when to avoid using this tool in favor of 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully describes key behaviors: the tool retrieves stored memories (implying read-only operation), works across sessions (persistence behavior), and has two modes (retrieve by key vs list all). However, it doesn't mention potential limitations like maximum memory size, retrieval time, or error conditions for invalid keys.

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 perfectly concise with two sentences that each earn their place. The first sentence explains the core functionality and parameter usage, while the second provides context about when to use the tool. There's zero wasted language, and the most important information (retrieval functionality) comes first.

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 memory retrieval tool with one optional parameter and no output schema, the description provides good coverage. It explains the tool's purpose, usage scenarios, and parameter behavior. However, without annotations or output schema, it could benefit from mentioning what format memories are returned in or any limitations on memory storage/retrieval. The description is complete enough for basic understanding but leaves some implementation details unspecified.

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% description coverage, providing a solid baseline. The description adds valuable semantic context beyond the schema: it explains that omitting the key parameter triggers listing of all stored memories, and clarifies that keys are used to retrieve 'context you saved earlier.' This connects the parameter to the tool's purpose in a way the schema alone doesn't.

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 with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'). It distinguishes from siblings like 'remember' (store) and 'forget' (delete) by focusing on retrieval operations. The phrase 'by key' adds specificity about the retrieval 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 provides explicit guidance on when to use this tool: 'to retrieve context you saved earlier in the session or in previous sessions.' It also specifies when to omit the key parameter ('omit key to list all keys') and distinguishes this from storage operations implied by sibling tools like 'remember'. The guidance covers both retrieval scenarios clearly.

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?

With no annotations, the description carries full burden. It explains the parallel fan-out (SEC EDGAR, GDELT, USPTO), return structure (structured changes + count + URIs), and acceptable since formats. It is transparent about behavior, though lacking explicit read-only or side-effect statements.

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 4 sentences, front-loaded with the core purpose, then explains fan-out, parameter details, return format, and use cases. Every sentence adds value with zero 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 no output schema, the description adequately explains return fields (structured changes, total_changes, URIs) and the fan-out behavior. It mentions the only supported type (company). It could improve by noting potential errors or limitations, but it is sufficiently complete for typical use.

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

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

Schema coverage is 100%, baseline 3. The description adds value by giving examples for 'since' (ISO date vs relative) and clarifying 'value' as ticker or CIK. It also notes the enum constraint for 'type' (only company).

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 'What's new about an entity since a given point in time' and explains the fan-out to multiple sources for company type. It provides concrete use cases like 'brief me on what happened with X' or change-monitoring, making the purpose specific and actionable.

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

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

The description explicitly says 'Use for "brief me on what happened with X" or change-monitoring workflows,' giving clear context for when to use. However, it does not mention when not to use or suggest alternatives among siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it's a storage operation (implied mutation), specifies persistence differences for authenticated vs. anonymous users, and mentions session duration (24 hours for anonymous). It does not cover rate limits, error conditions, or response format, but adds substantial context beyond basic purpose.

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 core purpose in the first sentence, followed by usage guidance and behavioral details. Each sentence adds value without redundancy, and it efficiently covers key aspects (purpose, usage, persistence) in a compact form. No wasted words or under-specification.

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 annotations and no output schema, the description does well by explaining persistence behavior and usage context. However, it does not detail what happens on success/failure, return values, or error handling, which are gaps for a mutation tool. It compensates partially with clear purpose and behavioral traits, but could be more complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('key' and 'value') with examples. The description does not add specific syntax or format details beyond what the schema provides (e.g., it mentions 'any text' but the schema says 'any text' too). Baseline 3 is appropriate as the schema handles parameter documentation adequately.

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 verb 'store' and the resource 'key-value pair in your session memory', making the purpose clear. It distinguishes from siblings like 'forget' (delete) and 'lookup/recall' (retrieve) by focusing on storage. The description provides specific examples of what to store ('intermediate findings, user preferences, or context across tool calls'), enhancing clarity.

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 when to use this tool ('to save intermediate findings, user preferences, or context across tool calls'), which helps guide usage. However, it does not explicitly mention when not to use it or name alternatives among siblings (e.g., 'forget' for deletion or 'lookup/recall' for retrieval), so it lacks full differentiation 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?

No annotations provided, so description carries full burden. It discloses return fields, version limitations (v1 only company), and the read-only nature (resolving, not modifying). Lacks explicit safety or rate limit info.

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 waste. Front-loaded with purpose, followed by specifics and benefit. Excellent 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, description explains return fields. Mentions version and scope. Does not cover error cases or edge cases, but adequate for a simple 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 has 100% coverage, but description adds example values and explains the purpose of parameters (e.g., 'accepts ticker, CIK, or company name'). 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?

Description clearly states the tool resolves an entity to canonical IDs, provides specific inputs (ticker, CIK, name) and outputs (ticker, CIK, name, URIs), and distinguishes from siblings by noting it replaces multiple lookup calls.

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 implies when to use (single call vs. 2-3 lookups) but does not explicitly state when not to use or list alternatives. Still 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?

No annotations are provided, so the description carries the full burden. It discloses the tool uses OpenStreetMap Nominatim, which adds useful context about the data source, but does not mention rate limits, authentication needs, or error handling. The description is accurate but lacks detailed behavioral traits.

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 sentence that efficiently conveys the tool's purpose and data source without any wasted words. It is appropriately sized and front-loaded with key 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 low complexity (2 simple parameters) and no output schema, the description is reasonably complete for a read-only operation. It specifies the data source (OpenStreetMap Nominatim), which adds context, but could benefit from mentioning potential limitations or output format to 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 description coverage is 100%, so the schema fully documents the two parameters. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints, but does not contradict it. Baseline 3 is appropriate as the schema handles parameter documentation.

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

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

The description clearly states the specific action ('reverse geocode') and resource ('latitude/longitude coordinate pair'), and distinguishes the tool's purpose from its siblings by specifying it converts coordinates to addresses, unlike 'lookup' or 'search_address' which likely perform different 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?

The description implies usage by stating the tool converts coordinates to addresses, but it does not explicitly guide when to use this tool versus alternatives like 'lookup' or 'search_address'. No exclusions or prerequisites are mentioned.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds detailed behavioral context: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradictions.

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

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

Description is two sentences, each packed with essential information: purpose, method, output, and use case. No filler or repetition.

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

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

No output schema exists, but description explicitly explains return format (ranked list with score, confidence, signal density per entity). It also mentions the internal dependency on ai_visibility_check. For a comparison tool, this 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?

Input schema has 100% coverage with descriptions for all 4 parameters. Description adds semantics beyond schema: specifies that first entity is treated as 'subject' for narrative and rest as competitors. This aids selection without being overly verbose.

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 per entity, and ranks results. It distinguishes from sibling ai_visibility_check (single entity) by explicitly mentioning multiple entities and ranking.

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 provides a clear use case example ('does Claude know about us as well as our competitors?') and context (competitive AI-marketing audits). It implies when to use (multi-entity comparison) but does not explicitly state when not to use or mention alternatives like compare_entities.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the service provider (OpenStreetMap Nominatim) and the return type (matching places with coordinates), it doesn't disclose important behavioral traits like rate limits, authentication requirements, potential costs, privacy considerations, or what happens with ambiguous queries. The description provides basic functionality but lacks operational 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 perfectly concise - a single sentence that efficiently communicates the tool's purpose, method, and output. Every word earns its place with no redundancy or unnecessary elaboration. The structure is front-loaded with the core functionality immediately clear.

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

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

Given no annotations and no output schema, the description provides adequate basic context for a geocoding tool but lacks completeness. It explains what the tool does and what it returns at a high level, but doesn't address important contextual elements like response format details, error conditions, or integration considerations with the OpenStreetMap service that would help an agent use it effectively.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (query and limit). The description adds no additional parameter semantics beyond what's in the schema - it mentions 'free-form address or place name' which is already covered in the query parameter description. Baseline score of 3 is appropriate when the schema does all the parameter documentation work.

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 specific action ('Forward geocode'), resource ('a free-form address or place name'), and technology used ('using OpenStreetMap Nominatim'). It distinguishes this tool from its sibling 'reverse_geocode' by specifying forward geocoding (address→coordinates) rather than reverse geocoding (coordinates→address).

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

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

The description implies usage for forward geocoding but doesn't explicitly state when to use this tool versus alternatives like 'lookup' (sibling tool). It provides context about what the tool does but lacks explicit guidance on when to choose this tool over other geocoding or lookup methods available on the server.

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?

No annotations are provided, so the description must fully disclose behavior. It describes the output (verdict, structured form, citation, delta) and mentions the tool's efficiency, but it does not address potential latency, rate limits, error conditions, or dependency on external data sources, which are important for a tool performing live lookups.

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

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

The description is three sentences, each earning its place: first sentence for purpose, second for scope, third for output. It is concise, front-loaded, and free of redundancy or fluff.

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

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

Despite lacking an output schema, the description thoroughly explains the return values (verdict, structured form, actual value with citation, percent delta). It covers the supported claim types and context. However, it could include more on error handling or what happens with unsupported claim types.

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 only one parameter (claim) that is fully described in the schema, the description adds value by specifying the types of supported claims and providing examples, plus detailing the output format. This goes beyond the basic parameter description, aiding correct 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 specifies that the tool fact-checks natural-language claims against authoritative sources, focusing on company-financial claims for public US companies via SEC EDGAR and XBRL. It distinguishes itself from siblings by noting it replaces 4-6 sequential agent calls, making the purpose highly specific and unique.

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

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

The description explicitly states the supported domain (company-financial claims) and types (revenue, net income, cash) but does not provide explicit when-not-to-use guidance or contrast with sibling tools like compare_entities or lookup. However, the clear scope and the mention of replacing sequential calls imply appropriate usage.

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