What3words

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe and idempotent. The description adds behavioral details: scoring range (0-100), per-model return fields (score, confidence, signals, raw_response), combined view, and default model. 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 three sentences, front-loaded with purpose, then provides key usage details. Every sentence adds information without redundancy or wordiness.

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 specifies the return format (per-model {score, confidence, signals, raw_response} + combined view). All four parameters are explained with clear context. The tool's purpose and behavior are fully described for a probing/auditing 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 description coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the default model behavior (Workers AI free) and the role of `_apiKey` (BYO key for Anthropic). Examples in entity description help disambiguate input.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses specific verbs ('probe', 'score'), identifies the resource (LLMs), and distinguishes from sibling tools like 'ask_pipeworx' and 'entity_profile' by focusing on multi-model visibility scoring.

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

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

The description provides explicit guidance on when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how to configure (default model vs Anthropic with API key). It does not explicitly mention when not to use or name alternatives, but the context signals and sibling list imply distinct 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?

Annotations already indicate idempotent, read-only, and open-world. Description adds behavioral context: routes to 3,436 tools, fills arguments, returns structured answer with stable pipeworx:// URIs. No contradictions.

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

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

Well-structured with a strong opening sentence. While slightly lengthy, each sentence serves a purpose: usage guidance, examples, and behavioral notes. Could trim slightly 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 no output schema, the description includes return format (structured answer with citations). Missing details on error handling or limitations, but sufficient for an agent to understand invocation and expected results.

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

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

Schema coverage is 100% with all 6 parameters being aliases for 'question.' Description adds no further parameter details beyond what schema provides. The examples in the schema already cover usage. So baseline 3.

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

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

The description clearly states the tool routes factual questions to authoritative sources (SEC, FDA, etc.) and returns structured answers with citations. It distinguishes from web search and provides specific examples, leaving no ambiguity about its purpose.

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

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

Provides explicit when-to-use guidance: factual questions about real-world entities/events/numbers, even if web search could answer. Includes rich examples. However, does not directly address when to prefer sibling tools like entity_profile or validate_claim.

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 safe reads; the description adds critical behavioral traits: hallucination-resistant, extracts only from tool result, returns structured refusals (e.g., not_in_source). 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?

Single paragraph, front-loaded with purpose, then details and usage guidance. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description thoroughly explains return fields (answer, evidence, confidence, source, fetched_at, refusal_reason) and refusal reasons. Covers routing and cost, making it self-contained for a complex tool.

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

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

Schema coverage is 100%, so baseline 3. The description mentions the tool fills arguments but adds no additional semantic meaning to the parameters 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 this is a hallucination-resistant answer mode for high-stakes reads, contrasts with ask_pipeworx, and details the extraction process and output format. It distinguishes itself from siblings by emphasizing truthfulness and explicit refusals.

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

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

Explicitly advises using this tool when answers will be quoted or acted on, and not to invent facts, while preferring ask_pipeworx for casual lookups. Also mentions the extra LLM call cost, providing clear decision criteria.

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=true, and destructiveHint=false, so description adds limited behavioral context. It does mention the focus point biasing, which is not in annotations. No contradictions 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?

Two sentences, no filler. Efficiently conveys purpose and key optional behavior. Front-loaded with 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?

Has output schema, so return values need not be described. Covers the main use case and optional focus. Could mention that it works for what3words addresses, but not necessary. Reasonably complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by clarifying that 'input' is partial/mistyped and that focus parameters bias proximity. This enhances understanding 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?

Clearly states it takes a partial/mistyped 3-word input and returns ranked suggestions. Mentions optional focus point for proximity biasing. Does not explicitly differentiate from sibling tools like 'words_to_coords', but purpose is distinct enough.

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 (partial/mistyped input) but does not mention when not to use or suggest alternatives among siblings. Lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds extensive behavioral context: resolver contract, parent event extraction, news fallback handling, safety notes on low-confidence matches and closed markets, and tradeability warnings. No contradictions.

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

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

The description is long but well-structured with clear sections and front-loaded purpose. While comprehensive, some details could be streamlined for an AI agent, but every sentence serves a purpose.

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

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

Despite lacking an output schema, the description thoroughly explains response shapes, edge cases (low confidence, closed markets, wide spreads), and safety mechanisms. It is complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds further value by explaining depth values ('quick = 2-3 sources'), providing market input examples, and detailing include_raw behavior with response size implications.

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 Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and provides usage examples ('should I bet on X'). It distinguishes from sibling tools like polymarket_arbitrage by focusing on evidence gathering.

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 cases ('Use for...') and gives examples of classifiers and fan-outs. However, it does not mention when NOT to use this tool or compare to alternatives, leaving some gap for exclusive guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds type-specific data sources (SEC EDGAR/XBRL for companies, FAERS/drug data), sorting behavior, and citation URIs. Missing details like rate limits or auth, but annotations cover safety profile adequately.

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 packed with useful information including query examples, type-specific details, and output format. Slightly long but well-structured with front-loaded examples. Could trim some redundancy but still 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?

Despite no output schema, description explains return format (paired data, citation URIs) and sorting behavior. Covers both entity types thoroughly, and provides precise data sources and constraints.

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

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

Schema coverage is 100%, but description goes beyond by giving concrete examples (tickers like AAPL, drug names like ozempic) and explaining the meaning of the type enum. Adds context on constraints like 2-5 items and ticker format.

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 performs side-by-side comparison of 2-5 companies or drugs with specific metrics for each type. It uses specific verbs like 'compare' and 'rank', and distinguishes from sibling tools like 'entity_profile' which handles single 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides concrete usage context (comparison queries) and states it replaces 8-15 sequential lookups.

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

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

Consistent with annotations (readOnly, idempotent, non-destructive). Adds that it converts to a 3-word address and language default. Could mention error handling but overall sufficient.

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

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

Two sentences with no wasted words. Front-loaded with primary action, then secondary detail. 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 output schema exists and annotations cover safety, the description adequately explains the core transformation and language option. No missing critical information.

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

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

Schema coverage is 100%, so description adds minimal value beyond what's in schema. It restates the default language, but parameter meanings are already well-documented.

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 converts lat/lon to a what3words address, specifying the resource (what3words) and action (convert). It distinguishes from sibling 'words_to_coords' by implication.

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 clear context: defaults to English, and how to use other languages via a 2-letter code. Does not explicitly mention when not to use or alternatives, but sibling tool names imply reverse operation.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false. Description adds behavioral details: returns schemas with curated examples, results are 'ready to call directly'. 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 well-structured sentences with a list. Purpose is front-loaded, every sentence adds value. 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?

With 6 parameters fully described in schema and description adding behavioral context, the description is complete for a discovery tool. It explains the return format (top-N tools with schemas) though it doesn't mention pagination beyond limit.

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

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

Schema coverage is 100%. Description adds meaning by explaining the query parameter as 'Natural language description' and lists aliases (task, q, description, search). It also clarifies the limit parameter's default and max.

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

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

Description explicitly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains and mentions returning top-N tools with schemas ready to call, clearly distinguishing it from sibling tools which are individual data tools.

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

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

Explicitly instructs: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance, though it doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral details: it fans out across multiple sources, returns specific fields, notes that patents may soft-fail after May 2025, and describes fallback mechanisms. 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 front-loaded with examples and emphasis, but is relatively long. However, every sentence provides necessary information—examples, data sources, output fields, limitations. It is effective but not maximally concise, hence a 4.

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 thoroughly explains all return values: CIK, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI. It covers data sources, fallbacks, and limitations. Context signals show complexity; description is complete.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra context: value must be ticker or zero-padded CIK, names not supported, and the type parameter is limited to 'company'. It also directs to resolve_entity for names, which goes beyond schema.

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

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

Description explicitly states it provides a 'full cross-source profile of a US public company in one parallel call' with examples of user queries like 'tell me about X' and 'brief me on Tesla'. It clearly distinguishes itself from chaining single-source lookups.

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

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

Description says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also specifies that names are not supported and instructs to use resolve_entity first, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context about why deletion might be needed (stale context, sensitive data). No contradictions. Some extra detail on irreversible nature could push to 5.

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 the action, no filler. Every sentence adds value and earns its place. Ideal 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?

For a simple delete-by-key tool, the description covers purpose, usage context, and relation to siblings. No output schema needed as return is straightforward. Complete for agent decision-making.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description does not add further semantics beyond what the schema provides, meeting baseline expectations.

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 deletes a memory by key, using the verb 'Delete' and resource 'previously stored memory'. It also distinguishes itself from siblings by mentioning 'Pair with remember and recall'.

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

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

The description explicitly lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also provides alternatives by referencing sibling tools, offering clear usage context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds behavioral context like fetching the page, extracting data, and emitting standard markdown, which informs the agent about potential latency and output format.

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?

Front-loaded with purpose, concise enough at four sentences. Could trim some redundant phrases but overall well-structured and efficient.

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

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

Given only two parameters and no output schema, the description fully explains input, process, and output (a text blob ready to drop). No missing information for agent to select and invoke.

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

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

Schema covers 100% of parameters with full descriptions. Description adds minimal extra context (e.g., 'or a specific landing page' for url) but does not enhance understanding beyond schema defaults.

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 generates an llms.txt file for any URL for AI crawlers. Distinguishes from siblings like scan_competitor_ai_presence and ai_visibility_check by focusing on file generation.

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 three specific use cases: indexing client site, drafting for own project, auditing competitor. However, does not explicitly mention when not to use or suggest alternative tools from sibling list.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context that the output includes code and name for 3-word output, which goes beyond annotations and clarifies the return structure.

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 conveys the purpose without any fluff. It is front-loaded and every word 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 no parameters and the presence of an output schema, the description is complete. It explains the purpose and output format, and annotations cover safety and behavior. No additional information is necessary.

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

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

There are no parameters (0 required, schema coverage 100%). With 0 parameters, the baseline is 4. The description does not need to add parameter info, and it correctly implies no inputs are needed.

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

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

The description clearly states the tool lists supported languages for 3-word output with code and name. The verb is implied, and the resource is explicit. It distinguishes from sibling tools as none serve a similar listing function.

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 explicit guidance on when to use this tool versus alternatives. It is implied that it should be used when languages need to be known for 3-word output, but no when-not-to-use or specific conditions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it returns only active subscriptions by default and lists the return fields, which is useful 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?

Two clear sentences with no unnecessary words, efficiently conveying purpose, return fields, and usage guidance.

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 list tool with good annotations and a single parameter, the description is complete enough. It explains what is returned and when to use it, though it could mention pagination or limits if applicable.

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

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

Schema coverage is 100% with the parameter 'include_inactive' described. The description adds meaning by mentioning 'active subscriptions' and implying the default behavior, providing slight additional 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 the tool lists the caller's active subscriptions, specifies the verb 'list' and resource 'subscriptions', and distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel', indicating when to use it and for what purpose.

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 are minimal (all false), but the description adds important behavioral context: the tool is rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. It also mentions that the team reads digests daily. This goes beyond what annotations provide. 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 concise and front-loaded: purpose first, then usage, then restrictions. Each sentence adds value. Minor nit: could be slightly shorter, but it's 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?

Complete for a feedback tool: explains the feedback lifecycle (digests, roadmap impact), rate limiting, quota implications, and content guidelines. No output schema needed; the description covers what the agent needs to know.

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

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

Schema coverage is 100% with all parameters having descriptions. The description adds additional context (e.g., meaning of each enum value, guidance on specificity) but the schema already covers the basics. 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 collects feedback for the Pipeworx team about bugs, missing features, or praise. It enumerates specific categories (bug, feature, data_gap, praise) and differentiates from sibling tools like 'ask_pipeworx' or 'discover_tools' which serve different purposes.

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

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

Explicitly states when to use: for bug reports, feature requests, data gaps, or praise. Provides concrete instructions like 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' Also mentions rate limits and that it's free with no quota cost.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. Description adds value by explaining data source (CF analytics-engine), no PII, and 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?

Two concise sentences plus bullet list. Front-loaded with main functionality. No redundant or unnecessary words.

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

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

For a simple tool with 1 optional param and no output schema, the description fully covers purpose, parameters, return values, use cases, and behavioral traits. Annotations handle safety.

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 enum description. Description adds interpretive context: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema.

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

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

The description states verb+resource: 'Returns the top tools, top packs, and total call volume over a recent window'. This clearly distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' which serve different purposes.

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 lists three use cases (discovering hot data, confirming canonical tool, aligning use case). Does not explicitly state when not to use, but context makes it clear this is for aggregate trends.

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 algorithms used (monotonicity checks, partition-sum checks), semantic anchoring (Jaccard similarity threshold), partition filtering (placeholder fraction), and the structure of the response. This goes far beyond the annotations which only indicate readonly, openWorld, and idempotent 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 dense but every sentence serves a purpose. It is front-loaded with the requirement, then explains modes, algorithms, filters, and response format. There is no redundancy or unnecessary detail.

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 fully explains the response structure: opportunities array with gap_pp, suggested_trade, reasoning, and the partition_check object in event mode. It also covers edge cases like placeholder filtering and low similarity skipping, making the tool's behavior fully understandable.

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 describes both parameters, and the description adds significant context: event mode walks child markets and checks date-axis/threshold-axis ordering, topic mode searches related events and flattens markets. It also notes that full Polymarket URLs are accepted for the event parameter, adding value beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic), each with specific use cases, and the purpose is unique among sibling tools like polymarket_edges and polymarket_kalshi_spread.

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 that one of event or topic is required, and failing to provide both will cause the call to fail. It provides clear guidance on when to use each mode: event for a specific market, topic for cross-event scanning, and even explains the advantage of topic mode with examples of patterns it catches.

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

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

The description goes far beyond annotations by detailing the behavioral traits of the tool: it explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), the caching behavior ('Cached 1h at the KV level'), and the output structure with diagnostics. It does not contradict any annotations; readOnlyHint, idempotentHint, and destructiveHint are all consistent with the described 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 verbose and includes many details that are important but could be more concise. It is structured with numbered sections and bullet points, which helps readability, but the length may be overwhelming. Front-loading the main purpose is good, but some redundancy exists (e.g., repeating edge_pp_net). A tighter description would improve conciseness.

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

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

Despite the lack of an output schema, the description thoroughly explains the return structure (by_segment, fed_candidates, diagnostics), parameter behavior, and underlying models. It covers all aspects a caller needs to understand what the tool does, how to configure it, and interpret results. This is a very complete description for a complex tool.

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

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

The input schema already has 100% coverage with descriptions for all 9 parameters. The tool description adds value by providing contextual usage tips (e.g., 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade' for slippage_pp, and 'min_kelly skips opportunities that are too small to bet sensibly'). This extra context elevates understanding beyond the schema alone.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb and resource, and distinguishes itself by being a discovery tool for betting opportunities without paging through markets. The title and description align well with the tool's function.

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

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

The description provides a clear use case: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It also gives tuning knobs and explains when to use filters like min_liquidity and max_spread_pp. However, it does not explicitly mention when not to use this tool or compare it with sibling tools like polymarket_arbitrage, so some guidance is missing.

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

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

The description discloses behavioral traits well beyond the annotations, including compatibility_warning cases, temporal alignment checks, and skipped cross-type/subtype counters. It highlights that real spreads are rare and explains the meaning of various response fields, adding significant transparency.

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 main purpose, then detailing two modes, response fields, and safety warnings. While it is somewhat verbose, every sentence adds meaningful information, and the organization aids readability.

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

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

Given the tool's complexity (three optional parameters, no output schema, and rich annotations), the description is highly complete. It explains the response structure, safety fields, temporal alignment, and limitations, covering all aspects an agent needs to correctly invoke and interpret the tool.

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

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

Although the schema covers 100% of parameters, the description adds value by explaining the relationship between topic and explicit parameters, providing examples, and clarifying the override behavior. This aids in correct parameter selection beyond what the schema alone offers.

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 the cross-venue spread between Kalshi and Polymarket for the same resolving question, specifying two modes and the response format. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue 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 explains when to use each mode (topic shortcuts vs explicit pairings) and warns that most pre-mapped topics return a compatibility warning, implying that not all pairings yield tradeable spreads. It lacks explicit when-not-to-use guidance or direct alternatives but provides sufficient context for proper 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 declare readOnlyHint, idempotentHint, destructiveHint. The description adds scoping information (anonymous IP, BYO key hash, account ID), which is not covered by annotations. No contradictions.

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

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

Three sentences: first defines core function, second provides usage example, third explains scoping. Front-loaded, no wasted words.

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

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

Given the simple tool (one optional param, no output schema), the description covers purpose, usage, scope, and sibling relationships. Complete and sufficient.

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

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

Schema coverage is 100%, so the description does not need to add parameter details. However, it clarifies that omitting the key parameter lists all keys, which adds meaningful usage semantics 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 defines the tool's purpose: retrieve a saved value or list all keys. It uses a specific verb-resource pair and distinguishes itself from siblings (remember, forget) by explicitly naming them.

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

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

The description explains when to use the tool (look up stored context) and when to use alternatives (save via remember, delete via forget). It provides clear context and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds significant behavioral context: it returns the most recent alerts with specific fields, mentions the side effect of mark_read (flagging events as read), and states that polls work fine. This goes well beyond the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, and each sentence adds meaningful detail without redundancy. It is efficiently structured for quick comprehension.

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 (5 optional params, no output schema) and rich annotations, the description covers the return value fields, filtering, mark_read behavior, and even an alternative access method. It is complete enough for an agent to use the tool effectively, though an explicit return format description would push it to 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining 'type' with an example ('sec_8k'), clarifying 'since' as ISO timestamp, and describing the effect of 'mark_read'. However, it does not cover all parameters (e.g., limit, unread_only) as thoroughly as the schema, so it only marginally improves parameter understanding.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly specifying the verb (pull) and resource (subscription feed events). It details the fields returned (source, citation_uri, raw payload) and mentions filtering by type and since, making the tool's purpose very clear and distinct from siblings like 'recent_changes'.

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

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

The description provides usage context (filtering, mark_read to acknowledge, polling works) and even suggests an alternative access method (GET registry.pipeworx.io). However, it does not explicitly state when to use this tool versus others or when not to use it, so the guidance is implied but not exhaustive.

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, open-world, and idempotent behavior. The description adds valuable context: it fans out to multiple APIs (SEC EDGAR, GDELT→GNews fallback, USPTO), describes fallback logic, and notes that the patents source may soft-fail. It does not contradict 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 detailed and front-loaded with example queries. While every sentence adds value, it could be slightly more concise. However, the structure is effective and easy to scan.

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

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

Given no output schema, the description fully explains the return format (structured changes grouped by source, total_changes count, citation URIs). It covers all relevant sources and their behaviors, making the tool's capabilities clear.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds further meaning: explains the 'since' parameter accepts both ISO dates and relative shorthand (e.g., '30d'), recommends typical monitoring values, and clarifies that 'type' only supports 'company' and 'value' can be ticker or CIK.

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

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

The description clearly states the tool's purpose: providing a change feed for a company (e.g., 'What's new with X') by aggregating data from multiple sources in one parallel call. It distinguishes itself from the sibling tool 'entity_profile' by specifying that this tool is for changes over a time window, while entity_profile provides a static profile.

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

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

The description provides explicit example queries (e.g., 'latest on Y', 'updates on Acme') and directly tells when to use the alternative tool ('Use entity_profile instead when you want the static profile'). This gives clear guidance on 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?

Annotations provide readOnlyHint, idempotentHint, etc. Description adds context beyond: persistence duration (24 hours for anonymous, persistent for authenticated) and scoping by identifier. 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?

Description is concise, front-loaded with purpose, and every sentence adds value. No extraneous 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 two simple parameters and no output schema needed, the description covers purpose, usage, and persistence. Lacks explicit mention of conflict behavior but sufficient for the tool's simplicity.

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

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

Schema coverage is 100%, with both 'key' and 'value' well-described. Description does not add parameter-specific details beyond schema, 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 defines the tool as saving data for later reuse, with specific examples like tickers, addresses, and preferences. It distinguishes itself from sibling tools 'recall' and 'forget' by explaining pairing.

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

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

Explicitly states when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget, and notes scoping and persistence differences for authenticated vs. anonymous sessions.

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 reveals that the tool internally cascades through multiple lookup endpoints and returns citation URIs, adding context beyond the annotations (readOnly, idempotent, openWorld). It does not contradict annotations. However, it could mention error handling or disambiguation limits for completeness.

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 an intuitive example-led opening, then clear sections for each entity type. It is moderately concise; one could argue slight redundancy in repeating 'pipeworx://' URIs, but overall efficient for the detail provided.

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

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

Given no output schema, the description fully explains the return values for both company (ticker, CIK, company name, citation URI) and drug (RxCUI, ingredient, brand, citation). It also notes internal cascading, providing a complete picture of what the tool does and produces.

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 parameter descriptions that already include examples (e.g., 'AAPL', 'metformin'). The description reiterates these examples but adds no new semantic meaning for the parameters themselves. It does, however, explain how parameters relate to the output, which is useful but not strictly 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 resolves names to official identifiers, with specific examples ('ticker for...', 'find the CIK for...'), making the purpose unmistakable. It distinguishes itself from siblings like compare_entities and entity_profile by focusing on ID lookup rather than comparison or profiles.

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

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

The description explicitly advises to use this tool first when you have a name but need an ID, providing clear context. However, it does not explicitly state when not to use it or contrast with alternatives like entity_profile, leaving a minor gap in 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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 four sentences, front-loaded with the purpose, and each sentence adds value. 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?

Despite no output schema, the description explicitly lists return fields (score, confidence, signal density). Parameter descriptions are complete, and the tool's complexity is well 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?

Schema coverage is 100%, baseline 3. The description adds value by explaining semantics: 'First entry treated as the subject for narrative; rest are competitors.' and clarifies models and _apiKey usage beyond schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general 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 it is 'useful for competitive AI-marketing audits' and provides a direct example question. It does not explicitly mention when not to use or provide alternative tool names, but the context is clear.

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

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

Annotations already declare safe hints (readOnlyHint, idempotentHint, destructiveHint=false). Description adds extra behavioral context: bundlephobia first measurement may take 5-30s, sources_failed lists timeouts, graceful degradation.

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 informative but somewhat lengthy with multiple clauses. Front-loaded with purpose, but could be more succinct. 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 no output schema, description sufficiently explains return structure (summary block, advisory detail, links, alternative versions). Includes edge cases and provides a complete picture for a composite tool.

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

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

Schema coverage is 100% with detailed parameter descriptions. Tool description does not add further parameter information beyond what schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia. It distinguishes itself from sibling tools (no other dependency scanner present).

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

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

Explicitly states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and notes limitations (NPM ecosystem only in v1, partial failures).

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

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

Discloses internal embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and a 200K char cap with truncation flagging. Annotations already indicate idempotent/read-only; description adds complementary technical 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?

Four sentences, each adding value. Critical detail is front-loaded (semantic search inside record) with examples and constraints in later sentences. 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?

Despite no output schema, description explains return format and behavior. Covers use case, limitations (char cap), and integration with sibling tool. Sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about output format (passages with offsets and similarity scores) and hints at query style, but doesn't substantially enrich parameter meaning beyond schema descriptions.

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

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

Clearly states the tool performs semantic search inside a fetched record, with examples like SEC 10-K and articles. Distinguishes from sibling tools by focusing on intra-record search rather than external lookups or comparisons.

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

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

Explicitly tells when to use: when the record is too large for the prompt. Also pairs with ask_pipeworx_grounded, providing a clear workflow. No exclusion but 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?

The description discloses behavioral details beyond annotations: OAuth requirement, type-specific filters, delivery channel options with limits (SMS 10/day), webhook auto-disable, and phone verification. Annotations provide idempotentHint=true, but description says 'Creates' which may imply non-idempotent; however, no explicit contradiction. Adds significant 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 front-loaded with the core purpose, then prerequisites, then types, then delivery options. Every sentence adds value. No fluff. Well-structured and efficiently communicates all 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 complexity (3 params, nested objects, no output schema), the description covers return value ('Returns the new subscription id'), types, delivery, and limits. Could be more explicit about the full response structure, but overall complete for a creation 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%. Description adds meaning beyond schema by explaining the semantics of each type (e.g., sec_8k items codes, polymarket_edge topic, fred_series series_id) and delivery fields (email pattern, SMS verification, webhook HMAC signing). This enriches parameter understanding.

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

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

The description clearly states the verb 'Create' and the resource 'a proactive monitoring subscription to a live-data event stream'. It lists specific subscription types and delivery channels, distinguishing it from sibling tools like 'list_subscriptions', 'unsubscribe', and 'recent_alerts'.

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

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

The description mentions the prerequisite of a Pipeworx OAuth account and explains that anonymous/BYO cannot persist subscriptions. It implies when to use this tool versus siblings (e.g., 'recent_alerts' for pulling feed), but does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds context that it returns category-bucketed example questions with tool+argument shapes from a live catalog, which is consistent and adds value beyond annotations.

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

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

The description is front-loaded with common user queries, packed with useful details (categories, tool+argument shapes), and every sentence serves a purpose without unnecessary words.

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

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

For an onboarding/discovery tool with no output schema, the description fully explains what is returned (category-bucketed example questions with tool+argument shape) and when to use it, making it self-contained.

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

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

Schema coverage is 100% with a clear description for the single parameter 'topic', but the description adds practical usage patterns and examples (no args vs. topic values) that enhance understanding beyond the schema.

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

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

The description clearly states the tool is an onboarding entry point that returns categorized example questions, and explicitly distinguishes from sibling tools like ask_pipeworx by advising to 'Use this FIRST when you do not yet know what Pipeworx can do'.

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

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

It gives explicit when-to-use guidance ('when you do not yet know what Pipeworx can do', 'to learn how to call the meta-tools'), usage patterns (no args for full spread, topic to focus), and provides specific topic examples.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds key behavioral traits: ownership enforcement, deactivation (not deletion), and historical events remaining. This enriches understanding 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?

Two concise sentences. First sentence states action and constraint. Second sentence explains the consequence. Every word is purposeful, no redundancy.

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

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

For a tool with one parameter, no output schema, and annotations covering idempotency and non-destructiveness, the description fully covers: the operation, constraints, effect, and link to historical data via 'recent_alerts'. Complete for selection and safe 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?

The only parameter 'id' is described in the schema as 'uuid'. The description adds context that the id comes from 'subscribe' and clarifies ownership enforcement. This adds value beyond the schema by tying the parameter to its source.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id'. It distinguishes from siblings like 'subscribe', 'list_subscriptions', and 'recent_alerts' by specifying ownership enforcement and deactivation behavior.

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

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

The description tells when to use: to cancel a subscription. Ownership enforcement provides a clear constraint. It does not explicitly state when not to use or mention alternatives, but the context of sibling tools and the ownership hint are sufficient for typical use.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by listing the verdict types, output format (structured form, actual value with citation, percent delta), and the fact that it replaces 4-6 sequential calls. Could mention limitations or error handling, but overall good.

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?

Long but each sentence earns its place. Front-loaded with trigger phrases, then explains scope, output, and efficiency gains. No redundant or irrelevant information.

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

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

Given no output schema, the description compensates by enumerating verdict types and output components. It also mentions the replacement of multiple calls. Could be slightly more complete on unsupported claim types or edge cases, but for a v1 tool it is well-rounded.

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

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

Only one parameter (claim) with full schema description coverage. The description adds context by specifying the type of claims supported (company-financial) and providing example inputs. This goes 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?

Clearly states the tool's purpose: natural-language claim verification specifically for company-financial claims. The description provides trigger phrases like 'fact check', 'verify the claim', etc., and distinguishes itself as a bundled replacement for multiple sequential calls. No sibling tool duplicates this function.

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

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

Explicitly advises use whenever the agent needs to check factual correctness of a user's claim. Also delimits scope to company-financial claims for public US companies via SEC EDGAR + XBRL. The description provides clear usage context without ambiguity.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds valuable detail about output format (lat/lon centre + 3m×3m bounding box) beyond annotations.

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

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

Single sentence, no wasted words, front-loaded with the key action and output details.

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

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

Given only one parameter, and output schema exists (implied by context signals), the description covers the essential conversion logic and output format completely.

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

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

Schema has one parameter with description 'Three-word address (dot-separated)'. Description adds an example ('filled.count.soap') and clarifies format, adding value beyond the schema's own description (100% 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?

Description clearly states the conversion from 3-word address to lat/lon centre and bounding box. It uses specific verb 'Convert' and distinguishes from sibling 'coords_to_words' by indicating the direction.

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?

No explicit instructions on when to use this tool versus alternatives. However, the context of sibling tools implies it's for converting words to coordinates, but no when-not-to-use guidance.

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