postcodes

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds that the tool probes external LLMs (Workers AI and optionally Anthropic) and that the user pays Anthropic directly for those calls, which is a key behavioral trait not covered by 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 four sentences, each earning its place: main action, default model and key requirement, return format, use cases. It is front-loaded with the core purpose and uses efficient language without 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 has 4 parameters (1 required) and no output schema, the description provides sufficient context: what models are available, how to configure them, the return format, and typical use cases. It also hints at idempotency via annotations. No gaps remain for an AI agent to understand invocation.

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

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

Schema coverage is 100% with good parameter descriptions. The tool description adds value beyond the schema by explaining the default model, the purpose of _apiKey, and the return format (per-model score, confidence, signals, raw_response combined). This fully compensates for the lack of an output 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 probes LLMs for brand awareness and returns a visibility score. It specifies the default model and that Anthropic requires an API key. However, it does not differentiate from the sibling tool 'scan_competitor_ai_presence', which may have overlapping functionality, so sibling differentiation is missing.

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

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

The description lists explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to bring your own API key for Anthropic. However, it does not specify when not to use this tool or mention 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 explains that Pipeworx 'picks the right tool, fills the arguments, and returns the result' which provides useful context about the tool's orchestration behavior. However, it doesn't disclose important behavioral aspects like rate limits, authentication requirements, error handling, or what happens when no suitable data source is found.

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 functionality in the first sentence, followed by supporting details about how it works, and concludes with concrete examples. Every sentence earns its place by adding distinct value, with zero redundant information. The structure moves from general purpose to specific implementation to illustrative examples.

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 100% schema coverage but no output schema, the description provides excellent context about what the tool does and how to use it. The examples effectively illustrate the tool's capabilities. The main gap is the lack of information about return values or output format, which would be helpful since there's no output schema provided.

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 documents the single 'question' parameter. The description adds meaningful context by specifying that questions should be 'in plain English' and 'natural language', and provides three concrete examples that illustrate the expected format and scope of questions. This goes beyond what the schema provides about parameter semantics.

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

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

The description clearly states the tool's purpose with specific verbs ('ask a question', 'get an answer') and resources ('best available data source'), distinguishing it from sibling tools like lookup_postcode or discover_tools. It explicitly explains that Pipeworx handles tool selection and argument filling, which is unique functionality not implied by the tool name alone.

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 ('No need to browse tools or learn schemas — just describe what you need') and includes three concrete examples that illustrate appropriate use cases. It effectively communicates that this is the tool to use when you want natural language querying instead of manually selecting and configuring specific data 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?

The description discloses internal steps (resolves, classifies, fans out to packs) and return structure (evidence packet, comparison). Annotations already indicate read-only and non-destructive, and the description adds useful behavioral context beyond that.

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 purpose and contains essential information. It's slightly verbose but packs efficiency, market classification, and benefit into a few sentences.

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

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

Given no output schema, the description explains the return (evidence packet, model comparison) and the tool's role in the demo product. It sufficiently covers complexity, though more detail on output format 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 coverage is 100% and both parameters are well-described in the schema itself. The description slightly reinforces the input types but adds minimal new information 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 researches a Polymarket bet using Pipeworx data, with specific input types (slug, URL, question text). It distinguishes itself from siblings like ask_pipeworx by focusing on betting edge and market analysis.

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

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

The description explicitly lists use cases: 'should I bet on X?', 'what does the data say?', 'is there edge?'. While it doesn't explicitly state when not to use, the context is clear and relevant to the core demo product.

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 the full burden. It states the output includes paired data and URIs, and lists specific fields for each type, but omits potential side effects, error scenarios, or authentication requirements.

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 four sentences, front-loaded with the core purpose, and every sentence adds necessary information. No redundant or verbose phrasing.

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 or annotations, the description is fairly complete: it explains purpose, parameters, and return structure. Lacks details on error handling or limits, but these are not critical 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%, baseline 3. The description adds value by explaining the data returned for each entity type and the expected input format (tickers/CIKs vs drug names), exceeding the schema's basic 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, specifies two distinct entity types (company, drug) with unique data points for each, and distinguishes it from sibling tools like lookup_postcode or 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 explains when to use this tool (replacing 8-15 sequential calls) and provides context for entity types, but does not mention when not to use it or alternatives beyond the implied efficiency gain.

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 the tool's behavior: it's a search operation that returns relevant tools based on natural language queries, with implied read-only functionality (no destructive actions mentioned). However, it doesn't cover potential limitations like rate limits, authentication needs, or error conditions.

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 serve a clear purpose: the first explains what the tool does and returns, the second provides critical usage guidance. There's no wasted language and it's front-loaded with the core functionality.

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 functionality with natural language queries), no annotations, and no output schema, the description does well by explaining the purpose, usage context, and behavioral aspects. However, it doesn't describe the format of returned results or potential limitations, leaving some gaps for a tool discovery function.

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 mentions 'describing what you need' which aligns with the query parameter, but adds no additional semantic context beyond what's in the schema. This meets the baseline for high schema coverage.

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 ('search the Pipeworx tool catalog') and resource ('tool catalog'), and distinguishes it from siblings by explaining it's for discovering tools rather than working with postcodes like the sibling tools. It explicitly mentions what it returns ('most relevant tools with names and descriptions').

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 ('Call this FIRST when you have 500+ tools available and need to find the right ones for your task'), including a specific threshold (500+ tools) and context (finding tools for a task). It clearly distinguishes this from the sibling postcode tools by function.

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 tool aggregates multiple data sources in one call and returns citation URIs, implying read-only behavior. It does not explicitly state read-only or disclose error conditions, but the context is sufficient. 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 two sentences, front-loaded with the core purpose and details. Every sentence adds value, with no wasted words. It balances brevity and informativeness.

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

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

The description fully covers what the tool does for companies, what output to expect (pipeworx:// URIs), and what is excluded (federal contracts, handled by another tool). It also addresses input constraints (no names). No output schema exists, but the description adequately describes the return format.

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 giving examples for 'value' (ticker or CIK) and explaining names are not supported, referencing resolve_entity. It also clarifies the 'type' enum limitation to 'company'. This exceeds baseline.

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 it retrieves a full profile of an entity across multiple Pipeworx packs, listing specific data types (SEC filings, revenue, patents, news, LEI) and noting it returns pipeworx:// citation URIs. It clearly distinguishes itself by replacing 10–15 sequential agent 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?

The description provides clear when-to-use (for a full entity profile) and when-not-to-use (federal contracts, which should use usa_recipient_profile). It also advises using resolve_entity if only a name is available, giving practical guidance on prerequisites.

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 states this is a deletion operation, implying it's destructive, but doesn't clarify whether deletions are permanent, reversible, require specific permissions, or have side effects. This leaves significant gaps for a mutation 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 a single, clear sentence with zero wasted words. It's front-loaded with the core action and resource, making it highly efficient 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?

For a destructive operation with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after deletion (e.g., success confirmation, error responses), nor does it address behavioral aspects like idempotency or permissions, leaving the agent with incomplete operational 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?

The input schema has 100% description coverage, with the 'key' parameter fully documented in the schema itself. The description adds no additional semantic context beyond what the schema already provides, such as examples of valid keys or deletion constraints, meeting the baseline for high schema coverage.

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 resource ('a stored memory by key'), making the purpose unambiguous. However, it doesn't distinguish this tool from potential siblings like 'recall' or 'remember' beyond the deletion aspect, which prevents a perfect score.

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 like 'recall' (which likely retrieves memories) or 'remember' (which likely stores them). It lacks any context about prerequisites, error conditions, or typical use cases for deletion.

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 as safe. The description adds process details ('Fetches the page, extracts title/description/key links') and output format ('standard llms.txt markdown format'), which go beyond annotations without contradiction.

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

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

Three sentences: first defines purpose, second explains process, third gives use cases. Every sentence adds value with no redundancy, and the main action 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?

The description covers purpose, process, output format, and use cases. With no output schema, it describes the output as 'single text blob.' It does not address edge cases (e.g., unreachable URLs), but for a simple tool with strong annotations, it is nearly 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%, with both parameters well-described. The description does not add significant meaning beyond the schema (e.g., 'url' and 'max_links' are already explained). Baseline 3 is appropriate.

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

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

The description clearly states the tool's verb ('generate'), resource ('llms.txt file'), and purpose ('so AI crawlers can index the site cleanly'). It distinguishes itself from sibling tools (e.g., 'ai_visibility_check'), none of which perform this exact task.

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

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

The description lists explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It provides clear context but does not explicitly mention when not to use or alternatives, though no siblings directly compete.

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 mentions 'Get' which implies a read operation, but does not disclose traits like rate limits, authentication needs, error handling, or what happens with invalid inputs. The description is minimal and lacks essential behavioral context beyond the 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 a single, efficient sentence that is front-loaded with the core purpose ('Get full geographic and administrative details'). There is no wasted language, and it directly communicates the tool's function without unnecessary elaboration.

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 lack of annotations and output schema, the description is incomplete for a tool with behavioral implications. It does not explain what 'full geographic and administrative details' includes, potential response formats, or error cases. For a tool with no structured data beyond the input schema, more context is needed to guide 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 'postcode' parameter well-documented in the schema (including examples). The description does not add any additional meaning or details about parameters beyond what the schema provides, so it meets the baseline score of 3 for high schema coverage.

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 ('Get') and resource ('full geographic and administrative details for a UK postcode'), distinguishing it from siblings like 'nearest_postcodes' (which finds nearby postcodes) and 'validate_postcode' (which checks validity). It precisely communicates what the tool does without being vague or tautological.

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 retrieving detailed information about a specific UK postcode, but it does not explicitly state when to use this tool versus alternatives like 'nearest_postcodes' (for proximity searches) or 'validate_postcode' (for validation). No exclusions or clear context for choosing this tool over siblings are provided.

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 'finds' nearest postcodes, implying a read-only operation, but doesn't cover aspects like rate limits, error handling, or output format. This leaves significant gaps in understanding how the tool behaves.

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, clear sentence that directly states the tool's function without any unnecessary words. It is front-loaded and efficiently communicates the core purpose, making it highly concise and well-structured.

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

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

Given the tool's complexity (a geospatial query with no output schema) and lack of annotations, the description is incomplete. It doesn't explain what 'nearest' means (e.g., distance metrics, result limits) or the return format, which is critical for an agent to use the tool 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?

The input schema has 100% description coverage, with the parameter 'postcode' well-documented as a UK postcode with an example. The description adds no additional parameter details beyond what the schema provides, so it meets the baseline score of 3 for high schema coverage.

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 a specific verb ('Find') and resource ('nearest UK postcodes'), and it specifies the target ('to a given postcode'). However, it doesn't explicitly differentiate from sibling tools like 'lookup_postcode' or 'random_postcode', which likely have different functions.

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 sibling tools or contexts where this tool is preferred, such as for proximity searches versus validation or random selection, leaving the agent without usage 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?

With no annotations, the description discloses the rate limit of 5 messages per day and the privacy guideline about not including user prompts. However, it does not mention any acknowledgment or storage 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 concise, with a clear structure: purpose first, then use cases, then constraints. Every sentence adds necessary information without 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?

Given the moderate complexity and no output schema, the description covers essential aspects: purpose, usage context, rate limit, and content rules. It is adequate for a feedback 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 the schema already explains each parameter. The description adds value by guiding the message content (be specific, no verbatim prompts) and implying context is optional.

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 sends feedback to the Pipeworx team and enumerates specific use cases (bug reports, feature requests, etc.), distinguishing it from data-querying siblings 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?

Describes when to use (for feedback types) and provides a clear constraint on message content (no user prompt verbatim). It also mentions rate limits, but does not explicitly compare to 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?

Annotations indicate readonly, idempotent, nondestructive. Description adds valuable details: derived from CF analytics-engine, no PII, caching behavior (5min-1h). 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?

Approximately 100 words, well-structured with bullet points. Front-loaded with key information. 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 simple tool (1 parameter, no output schema), description explains output, window semantics, caching, and data provenance. No gaps.

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

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

Schema covers parameter fully (enum with descriptions). Description adds meaning: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond schema.

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

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

Clearly states what the tool returns: top tools, top packs, and total call volume. Uses specific verb 'returns' and resource 'what other AI agents are calling on Pipeworx'. Distinct from siblings like 'discover_tools' or 'compare_entities'.

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

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

Lists three explicit use cases: discovering hot data sources, confirming canonical choice, and seeing alignment. Lacks explicit when-not-to-use or alternatives, but use cases provide clear guidance.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds value by detailing internal steps: walks child markets, extracts dates/thresholds, sorts, and reports pairs. 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 informative and well-structured, with a clear explanation of the concept followed by mechanics and output. It is slightly lengthy but every sentence adds value.

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

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

Given the tool's low complexity (1 param, no output schema), the description adequately covers purpose, input, mechanism, and output format. It does not mention openWorld implications but that is minor.

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 single parameter. The description further clarifies input format (slug or URL) and provides an example, adding meaning 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 finds arbitrage opportunities via monotonicity violations, with specific examples and explanation. It distinguishes from siblings by focusing on Polymarket event internal mispricings.

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

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

The description provides clear context on when to use (when an event has multiple by-date or by-threshold markets) but does not explicitly mention alternatives or when not to use.

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

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

The description details the internal logic: V1 covers crypto-price bets, uses lognormal model from FRED and live coinpaprika price, groups by asset, fetches price history once, computes model probability, and ranks by edge. Annotations already indicate read-only and non-destructive, with no contradiction.

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

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

The description is well-structured with a front-loaded purpose statement, followed by method and output. It is slightly verbose but every sentence contributes uniquely.

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

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

The description covers input, process, and output (returns top N with trade direction). It mentions limitations (V1, crypto-only) and explains the model. No output schema, but the description suffices for understanding returns.

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?

Though the input schema has 100% description coverage, the description adds significant context on how parameters like window and min_edge_pp are used in the process (e.g., volume filter, inclusion threshold). This goes beyond the schema's basic explanations.

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 high-volume Polymarket markets and returns those where Pipeworx data disagrees most with market price, using a specific model. It distinguishes itself from sibling tools like bet_research and polymarket_arbitrage by focusing on 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?

The description explicitly identifies the use case: 'what should I bet on today' and explains it saves browsing hundreds of markets. However, it does not provide explicit when-not-to-use guidance or compare to alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds value by detailing the two operating modes and the return structure (leg-by-leg prices and spread), which are beyond what annotations provide. No contradictions with annotations.

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

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

The description is well-structured, starting with the core purpose, then explaining the arbitrage rationale, followed by the two modes, and finally the return format. It is concise but slightly verbose in explaining the venue difference; still, every sentence adds value.

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

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

Given the three optional parameters and no output schema, the description adequately covers the input modes and output format (prices and spread). It does not specify exact data types or examples, but for a read-only analytical tool, the context 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?

While schema coverage is 100% (each parameter has a description), the description adds meaningful context: it explains that `topic` maps to pre-defined shortcuts and that explicit parameters override the topic-mapped side. This clarifies interaction between parameters 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit event identifiers) and explains the output (leg-by-leg prices and spread). This differentiates it from sibling tools like polymarket_arbitrage, which may focus on other arbitrage signals.

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 when an agent wants to compare prices across venues for matched events, but it does not explicitly state when to use this tool over alternatives like polymarket_arbitrage or compare_entities. No exclusion criteria or usage context beyond the two modes are provided.

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's behavior by indicating it returns 'full geographic and administrative details,' but lacks information on potential limitations such as rate limits, data freshness, or error handling. The description is adequate but could be more detailed for a tool with no annotation support.

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 output details without any unnecessary words. It is front-loaded with the core action and resource, making it highly concise and effective.

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 (0 parameters, no output schema, no annotations), the description is reasonably complete. It specifies what the tool does and the type of output expected. However, it could be more comprehensive by detailing the format of the 'geographic and administrative details' or any constraints, but for a low-complexity tool, it is largely sufficient.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description does not add parameter details beyond the schema, but this is acceptable as there are no parameters. A baseline of 4 is appropriate since the schema fully covers the absence of parameters.

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 ('Get a random valid UK postcode') and the resource ('with full geographic and administrative details'), distinguishing it from sibling tools like lookup_postcode, nearest_postcodes, and validate_postcode by emphasizing randomness rather than lookup, proximity, or validation.

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 context by specifying 'random valid UK postcode,' suggesting it's for generating arbitrary postcodes rather than querying specific ones. However, it does not explicitly state when to use this tool versus alternatives like lookup_postcode for known postcodes or validate_postcode for verification, leaving some guidance implicit.

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 key behavioral traits: it retrieves memories stored earlier in sessions, supports listing all memories, and handles both current and previous sessions. However, it lacks details on error handling, response format, or performance limits, leaving some gaps for a tool with no annotation support.

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 and concise, with two sentences that efficiently convey purpose and usage without redundancy. Every sentence adds value, making it easy to parse and understand quickly.

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 (1 parameter, no output schema, no annotations), the description is mostly complete: it covers purpose, usage, and parameter semantics. However, it lacks details on return values or error cases, which would be helpful since there's no output schema, leaving minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter. The description adds meaningful context: it explains that omitting the key lists all memories, while including it retrieves a specific memory by key, clarifying the parameter's role beyond the schema's basic description.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'), distinguishing it from siblings like 'remember' (store) and 'forget' (delete). It explicitly mentions retrieving context saved earlier in sessions, which clarifies its role in memory management.

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: use to retrieve context saved earlier, and specifies when to omit the key (to list all memories) versus include it (to retrieve a specific memory). It implicitly distinguishes from siblings by focusing on retrieval rather than storage or deletion, though it doesn't name alternatives 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?

With no annotations, the description fully reveals key behaviors: parallel fan-out to SEC EDGAR, GDELT, USPTO; accepted since formats (ISO date or relative); and return structure (structured changes + total_changes count + pipeworx:// URIs). This gives the agent a complete understanding of the tool's operation.

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 front-loaded with the core purpose. It conveys rich information in a few sentences without redundancy. Minor improvement could be splitting into bullet points for readability, but it's well-structured 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 the absence of an output schema, the description adequately explains return types (structured changes, count, URIs). It covers all parameters and usage context. Missing details like pagination or error handling are acceptable for a monitoring tool.

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

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

Schema coverage is 100%, but the description adds extra meaning beyond the schema: it explains the fan-out logic tied to type, provides examples for since ('7d', '30d', '3m', '1y'), and clarifies that value can be a ticker or CIK. This adds substantial value.

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

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

The description clearly states 'What's new about an entity since a given point in time,' specifying the verb (recent changes) and resource (entity). It distinguishes from siblings by implying change-monitoring workflows, which is distinct from entity profiling or 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?

The description explicitly states 'Use for "brief me on what happened with X" or change-monitoring workflows,' providing clear usage guidance. It does not explicitly exclude alternatives or mention when not to use, but the context is sufficient for effective tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it's a storage operation (implying mutation), specifies persistence differences based on authentication ('Authenticated users get persistent memory; anonymous sessions last 24 hours'), and hints at session scope. However, it doesn't cover error cases, limits on key/value size, or concurrency 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 appropriately sized and front-loaded: the first sentence states the core purpose, and subsequent sentences add valuable context without redundancy. Every sentence earns its place by explaining usage, authentication implications, and session duration—no wasted words.

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

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

Given the tool's moderate complexity (storage with authentication-dependent persistence), no annotations, and no output schema, the description is mostly complete. It covers purpose, usage, and key behavioral aspects like persistence rules. However, it lacks details on return values (e.g., success confirmation) and potential error conditions, leaving minor gaps.

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

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

The input schema has 100% description coverage, with clear descriptions for both 'key' and 'value' parameters. The description does not add any additional semantic meaning beyond what the schema provides (e.g., no examples of valid key patterns, no constraints on value content). Baseline score of 3 is appropriate since the 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 specific action ('Store a key-value pair') and resource ('in your session memory'), distinguishing it from sibling tools like 'recall' (which likely retrieves) and 'forget' (which likely deletes). It explicitly mentions what can be stored ('intermediate findings, user preferences, or context across tool calls'), making the purpose unambiguous.

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

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

The description provides clear context for when to use this tool ('to save intermediate findings, user preferences, or context across tool calls'), but does not explicitly state when not to use it or name alternatives. It implies usage for persistence across sessions but lacks explicit exclusions or comparisons with sibling tools like 'recall'.

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 what inputs are accepted (ticker, CIK, name) and what returns (ticker, CIK, name, URIs). It does not discuss side effects or permissions, but for a resolution tool the behavior is clear. No contradictions with annotations as none exist.

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

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

The description is two sentences, front-loaded with purpose and then providing version and type details. Every sentence is informative and there is no redundancy or extraneous 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?

Given the tool's simplicity (2 required params, no output schema), the description covers purpose, inputs, and outputs adequately. It mentions the output includes ticker, CIK, name, and resource URIs. It does not specify error handling or format details, but overall it is sufficient for an agent to decide to use it.

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

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

Schema coverage is 100% and both parameters include descriptions. The description adds significant value by explaining that 'value' can be ticker, CIK, or name, and gives examples. It also clarifies that 'type' is currently only 'company', 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 it resolves an entity to canonical IDs across Pipeworx data sources, specifying the resource (entity), action (resolve), and concrete examples (ticker, CIK, name). It distinguishes from siblings by claiming 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?

The description provides explicit usage context: it supports type 'company' and accepts ticker, CIK, or name. It mentions it can replace 2–3 lookup calls, implying efficiency. However, it does not explicitly state when not to use it or name specific 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: it probes each entity, ranks by score, and uses ai_visibility_check internally. This adds context beyond annotations.

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

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

The description is concise and front-loaded with the main action. It wastes no words and is 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?

Given 4 parameters and no output schema, the description fully explains the return value (ranked list with score, confidence, signal density per entity). It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning by explaining that the first entity is treated as the 'subject' and that '_apiKey' is passed to api.anthropic.com per probe.

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 compares AI visibility across multiple entities side-by-side, ranks them by score, and surfaces the most/least recognized. It distinguishes itself from sibling 'ai_visibility_check' by being a multi-entity 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?

The description provides a specific use case ('competitive AI-marketing audits') and an example question. It implies when to use but does not explicitly state when not to use or list alternatives, though it mentions it uses ai_visibility_check internally.

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 fully carries the burden of behavioral disclosure. It reveals that v1 only supports company-financial claims, uses specific data sources, and returns specific outputs. It also notes that it replaces 4-6 sequential agent calls, indicating efficiency. 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 three sentences with no waste. The first sentence states purpose and scope, the second explains supported domain/data sources, and the third lists outputs and efficiency benefit. Front-loaded and every sentence earns its place.

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

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

Given the tool has one parameter, no output schema, and no annotations, the description covers all essential context: purpose, domain, data sources, return values, and efficiency improvement. It is sufficient for an agent to select 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?

The input schema has 100% coverage describing the 'claim' parameter. The description adds value by providing concrete examples of acceptable claims, such as 'Apple's FY2024 revenue was $400 billion', which aids correct invocation 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: fact-checking natural-language claims against authoritative sources. It specifies the domain (company-financial claims for US public companies), data sources (SEC EDGAR + XBRL), and return values (verdict, structured form, citation, delta). This distinguishes it from sibling tools like entity_profile or resolve_entity.

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 the tool: for financial claims about public US companies. It gives examples and mentions it replaces sequential agent calls. However, it does not explicitly state when not to use it or mention alternatives, which would strengthen 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 are provided, so the description carries the full burden of behavioral disclosure. It states the tool checks validity but doesn't describe what 'valid' means (e.g., format, existence), potential error handling, rate limits, or response format. For a validation tool with zero annotation coverage, this is a significant gap in behavioral context.

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

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

The description is a single, clear sentence with no wasted words: 'Check whether a UK postcode is valid.' It is front-loaded and efficiently communicates the core purpose, making it easy for an agent to parse and understand quickly.

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 (1 parameter, 100% schema coverage) but lack of annotations and output schema, the description is incomplete. It doesn't explain what constitutes validity, potential return values, or error cases. For a validation tool, this leaves critical behavioral aspects undocumented, reducing its helpfulness to 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?

The input schema has 100% description coverage, with the parameter 'postcode' documented as 'UK postcode to validate (e.g., "SW1A 1AA").' The description adds no additional parameter semantics beyond this, as it doesn't elaborate on validation criteria or input constraints. Given the high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Check whether a UK postcode is valid.' It specifies the verb ('Check') and resource ('UK postcode'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'lookup_postcode' or 'nearest_postcodes,' which might also involve postcode validation as part of their functionality.

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 sibling tools or contexts where validation is preferred over lookup or other operations. This leaves the agent without explicit direction on tool selection, relying solely on the tool name and basic purpose.

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