zippopotam

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

Beyond annotations (readOnly, idempotent), description adds cost implications (free default, BYO key for Anthropic), model selection details, and return structure (per-model score/confidence/signals/raw_response + combined view). No contradiction.

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

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

Three well-organized sentences: purpose, model details, return format. Front-loaded with key action and output. Every sentence adds value 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?

No output schema exists, but description fully explains return format. All parameters are described with examples. Provides sufficient detail for an AI agent to use the tool correctly.

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

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

Schema covers all parameters (100%). Description enhances with entity examples and clarifies _apiKey purpose and pass-through behavior. Slightly exceeds the baseline 3 by adding practical context.

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

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

Clearly states it probes LLMs to score visibility (0-100) per model. Verb and resource are specific. Distinguishes from sibling tools like scan_competitor_ai_presence by focusing on scoring and multiple models.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Notes default model and optional Anthropic probe with BYO key. Lacks explicit when-not-to-use or alternative tool mentions, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context about routing to the correct tool among thousands and returning stable citation URIs. No contradictions.

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

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

The description is front-loaded with the key instruction to prefer over web search. It is relatively long but each sentence adds unique value, covering purpose, alternatives, and examples. Minor redundancy could be trimmed.

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 (6 aliased parameters, no output schema), the description adequately covers its behavior and return format (structured answers with citations). It lacks explicit details on the return schema but compensates with examples and context.

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

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

The input schema has 100% description coverage, clearly documenting all aliases (question, q, text, etc.). The description does not add significant meaning beyond restating that it accepts natural language. The examples in the schema provide additional clarity.

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 routes questions to a large set of verified sources and returns structured answers with citations. It explicitly distinguishes itself from web search and specifies the types of queries it handles (SEC filings, FDA data, etc.), providing a specific verb ('ask') and resource ('Pipeworx') with unique capabilities.

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 instructs to prefer this tool over web search for authoritative structured data. It lists numerous domains and provides example queries. It also suggests that web search is an alternative but less preferred, giving clear when-to-use guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond annotations: it details the extraction process using only tool results, the explicit refusal reasons, and the cost of an extra LLM call. 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?

The description is well-structured, starting with the core purpose, then details, and ending with usage guidance. Every sentence is necessary and impactful, with no redundancy or fluff.

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

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

Despite lacking an output schema, the description explicitly lists the return fields (answer, evidence, confidence, source, etc.) and possible refusal reasons. For a complex tool that routes to other tools, this is sufficiently 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 descriptive aliases. The description reiterates the aliases but does not add new meaning beyond what the schema already provides. Baseline 3 is appropriate as the schema carries the semantic load.

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 is a 'hallucination-resistant answer mode' for high-stakes reads, distinguishing itself from ask_pipeworx by emphasizing grounded, non-hallucinatory answers. The description specifies verb and resource, and differentiates from its sibling tool effectively.

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: 'whenever an answer will be quoted, cited, or acted on' and when to avoid: 'prefer ask_pipeworx for casual lookups'. Also notes the extra cost relative to the sibling tool, providing clear alternative selection context.

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

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

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds substantial behavioral detail beyond annotations: it explains low-confidence resolution short-circuiting ('low-confidence resolutions short-circuit with status:low_confidence_match'), closed market handling ('return status:market_closed_or_inactive'), wide spread warnings ('tradeability:illiquid_wide_spread'), and resolution-rule risk parsing. 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 quite verbose (multiple paragraphs) with detailed sections on response shapes, resolver contract, parent event extractor, etc. It is well-structured with clear headings, but many details could be distilled. Front-loading of the main purpose is good, but the overall length may overwhelm some agents. A more concise version would score higher.

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 (multiple data sources, classifiers, response fields), the description is highly complete. It covers response shapes (market, analysis, evidence), resolver contract (confidence, alternatives, suggestions), parent event extraction, news fields with fallback handling, safety mechanisms, and resolution-rule risk. No output schema is provided, but the description compensates fully.

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

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

Schema description coverage is 100% (all three parameters described). The description adds significant meaning beyond the schema: for 'market', it explains acceptable input formats (slug, URL, question text) with examples; for 'depth', it clarifies the behavior of 'quick' vs 'thorough'; for 'include_raw', it explains the trade-off between response size and completeness. The description 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 tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), the resource (Polymarket bet), and the action (aggregating data in one call). The description also distinguishes it from sibling tools like polymarket_edges and polymarket_edge_tracker by highlighting its comprehensive, single-bet research nature.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of classifiers and fan-out scenarios. While it doesn't explicitly state when not to use it, the context is clear and distinguishes from sibling tools. Missing explicit exclusions or alternatives prevents a 5.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: handles off-calendar fiscal years, returns sorted results, and includes citation URIs. No contradiction with annotations.

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

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

Description is relatively long but front-loaded with example queries. Every sentence adds value, covering usage, data sources, and return format. Could be slightly trimmed, but still 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 2 parameters with 100% schema coverage and no output schema, description explains return format (paired data + citation URIs) and sorting behavior. Covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%. Description adds significant meaning: explains that type='company' pulls SEC 10-K data, type='drug' pulls FAERS/FDA/trial counts, and values should be tickers/CIKs or drug names. Goes beyond basic schema descriptions.

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

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

Description uses specific verb 'compare' and resource 'entities,' with examples like 'X vs Y' and 'head to head.' It distinguishes from siblings such as entity_profile by specifying side-by-side comparison of 2–5 entities in one parallel call.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides clear context for when to use, including example queries and differentiation between company and drug types with their data sources.

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 that the tool decomposes questions, routes to tools in parallel, returns structured findings with evidence and gaps, and mentions latency (15-60s). All beyond annotations which already indicate safe 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?

Description is long but every sentence adds value, from main purpose to details to usage guidelines. Front-loaded with key info. Slightly verbose but not wasteful.

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 complex orchestration tool without output schema, the description thoroughly explains the output structure (evidence, confidence, source, gaps, etc.), prerequisites, and expected latency. Highly 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%, but description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8 with paid requirement) and clarifies that questions can be broad/multi-part. Enhances understanding beyond schema.

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

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

The description clearly states the tool performs multi-source research in one call, decomposing questions and routing to many tools. It distinguishes itself from the sibling 'ask_pipeworx' by noting that one is for single lookups.

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

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

Explicitly says to use for broad or multi-part questions and to use ask_pipeworx for single lookups. Also mentions prerequisites: Pipeworx account and paid plan for 'thorough' depth.

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 safe, idempotent, read-only behavior. Description adds that results include full schemas with examples and are ready to call directly, aligning with and supplementing 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?

Three sentences front-load purpose and usage, followed by return format and a call-to-action. 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 clearly explains what is returned (top-N tools with names, descriptions, schemas, examples). Usage context is thorough given the tool's simplicity and annotation coverage.

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. Description mentions only the 'query' parameter and its aliases, but does not add new meaning beyond what the schema provides, meeting the 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 clearly states the tool finds tools by describing data or task, listing numerous domains. It distinguishes itself as a meta-tool for browsing available tools, not a direct data access tool.

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 'Call this FIRST when you have many tools available and want to see the option set.' Provides clear context for when to use, but does not name specific alternatives or mention 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 expands significantly on the annotations (readOnlyHint, idempotentHint, etc.) by detailing the internal fan-out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and specifying the exact data fields returned (e.g., recent filings with URIs, fundamentals sorted by period_end). It also discloses the soft-fail behavior for patents.

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 example queries up front, followed by the core purpose, then detailed output sections. While it is relatively long, it is efficient for the complexity of the tool and avoids unnecessary repetition. 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 complexity and lack of an output schema, the description provides a comprehensive overview of inputs, behavior, and outputs, including specific data fields and sources. It addresses limitations (patents soft-fail, name requirement) and prerequisites (use resolve_entity for names). Minor missing details like pagination are acceptable for a one-call profile tool.

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

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

The schema already provides descriptions for both parameters (type and value), with 100% coverage. The tool description adds practical usage guidance, such as examples ('AAPL' or '0000320193') and the caveat that 'value' does not support names. This enriches the schema without being redundant.

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

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

The description clearly identifies the tool's function: generating a holistic cross-source profile of a US public company. It provides multiple example queries and specifies the scope ('US public company'). It also distinguishes itself from sibling tools like resolve_entity and narrow lookup tools by advising preference over 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?

The description explicitly states when to use the tool (for holistic views) and when not to (if only a name is provided, use resolve_entity first). It also explains the input requirements (ticker or CIK) and notes limitations like the patents API soft-failing. This provides clear direction for an AI agent.

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 idempotentHint=true and destructiveHint=true. The description adds context on when to use but does not disclose behavior such as idempotency or error handling, which are covered by annotations. No contradiction.

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

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

Two sentences, front-loaded with the core action, no extraneous words. Every sentence adds value.

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

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

Given the tool has one parameter and no output schema, the description covers purpose, usage, and pairing adequately. It is complete for a simple deletion 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 a single parameter 'key' well-described. The description does not add extra meaning beyond the schema, meeting 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 clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes from siblings like 'remember' and 'recall' by explicitly pairing.

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

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

The description provides explicit usage scenarios ('when context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with 'remember' and 'recall'. It does not include when-not-to-use or alternatives, but the guidance is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so description adds context by specifying it fetches the page, extracts title/description/key links, and emits markdown. This 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?

Extremely concise: four sentences cover purpose, behavior, output format, and use cases. No fluff; all sentences earn their place, front-loaded with the most important 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 and simple parameters, the description is nearly complete. It explains output format and use cases. Could mention error handling or limitations (e.g., large pages), but overall sufficient for effective selection and 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 has 100% coverage with descriptions for both parameters. The description mentions that max_links has a default and max, which is redundant with the schema. No additional semantic value beyond what's in 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 generates an llms.txt file for any URL, names specific AI crawlers, and gives concrete use cases that differentiate it from sibling tools like 'scan_competitor_ai_presence'.

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

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

It provides explicit use cases: indexing a client's site, drafting for own project, auditing competitors. It doesn't explicitly state when not to use, but the context is clear and contrasts well with 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 and idempotentHint, so the description adds value by specifying the exact fields returned and the default behavior (active only). This additional context goes beyond the safety profile provided 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 two sentences with no unnecessary words. It front-loads the purpose and return fields in the first sentence, then provides usage guidance in the second. Every sentence is informative and 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 simple tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage guidance. It is mostly complete, though it could mention potential limits or ordering for full 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% (the only parameter is fully described in the schema). The description repeats the same information ('include cancelled subscriptions in response (default false)') without adding new meaning, so baseline score of 3 applies.

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 lists the caller's active subscriptions and specifies the returned fields. The verb 'list' and resource 'subscriptions' are specific, and the context of sibling tools 'subscribe' and 'unsubscribe' further distinguishes this as a read operation.

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 recommends using this to review subscriptions before adding more or to find an ID to cancel, providing clear usage context. It does not include explicit exclusions or alternative tools, but the purpose is well-defined.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description's addition of 'Get all postal codes' is consistent but adds no behavioral details beyond the annotations. There is no mention of rate limits, pagination, or other traits.

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

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose without any wasted words or redundancy. It earns its place by being clear and concise.

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

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

Given the simplicity of the tool, the presence of a full output schema, comprehensive input schema, and informative annotations, the description is complete enough. It adequately covers what the tool does, leaving no critical gaps for an AI 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% coverage with descriptions for all three parameters. The description's mention of 'city', 'country', and 'state/province' adds no new semantics beyond the schema. The schema already provides examples and formatting hints.

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 'Get' and the resource 'all postal codes for a city'. It specifies the required context (country, state/province), making the purpose clear. However, it does not explicitly distinguish this tool from the sibling 'lookup_zipcode', which likely performs a reverse lookup.

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 does not mention use cases, exclusions, or when to prefer 'lookup_city' over 'lookup_zipcode' or other sibling tools. The context is purely descriptive.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing safety and idempotency. The description adds valuable behavioral details: free, sub-second response, no authentication required. This goes beyond annotations to give the agent confidence in using the tool without side effects.

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

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

Three sentences with no wasted words. First sentence defines the core action and output. Second sentence gives usage guidance. Third sentence provides workflow context and key attributes (free, fast, no auth). Information is 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's simplicity (2 required params, output schema exists), the description is complete. It covers geographic scope (60+ countries), performance (sub-second), cost (free), and security (no auth). The output schema documents return fields, so the description's listing of city/state/lat-lon is sufficient without needing full detail.

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 descriptions for both parameters (ISO country code and ZIP/postal code). The description adds marginal value by mentioning '60+ countries' but this is already implicit from the country parameter. Baseline 3 is appropriate per guidelines 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 tool resolves a ZIP/postal code to city, state/province, and latitude/longitude for 60+ countries. It uses a specific verb 'resolve' and identifiable resource 'ZIP/postal code'. While it doesn't explicitly distinguish from sibling 'lookup_city', the examples 'where is ZIP X' and 'what city is postal code Y in' clarify its targeted use case, making it highly distinct from a generic web search.

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

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

The description explicitly states 'PREFER OVER WEB SEARCH' for specific queries, providing clear when-to-use guidance. It also recommends using this tool as the first step in geo-aware workflows and chaining with other tools like weather or attom. This offers excellent usage context and exclusionary logic.

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?

While annotations are minimal, the description adds rich behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads digests daily with roadmap impact. 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 well-structured: first sentence states purpose, then usage guidelines, then constraints. Every sentence adds value; no wasted words. It's front-loaded with the core action.

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

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

For a simple feedback tool, the description is complete: it covers what to submit, when, how to write it, constraints, and what happens after. No output schema is needed for this tool.

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

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

Schema coverage is 100%, but the description adds meaning to the enum type by explaining each value and provides guidance on the message field (be specific, 1-2 sentences). The context field is explained as optional structured context.

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

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

The description clearly states the tool is for sending feedback (bug, feature, data_gap, praise) to the Pipeworx team, with specific verbs and resource. It distinguishes from sibling tools by being a feedback channel, not a query or data retrieval tool.

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 specifies exactly when to use (wrong data, missing tool, something worked) and what not to do (avoid pasting end-user prompts). It also provides constraints like rate limits (5 per day) and quota information (free, no count).

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, non-destructive. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and aggregate nature. 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?

Well-structured with an overview sentence, bulleted use cases, and additional info. Every sentence adds value, though slightly verbose in bullet explanations.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, use cases, parameter semantics, data source, privacy, and caching. Fully 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% with a description for the 'window' parameter. The tool description adds extra meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

The description clearly states it returns top tools, packs, and call volume over a window, using specific verbs and resources. It distinguishes from sibling tools like 'discover_tools' by focusing on trending usage.

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

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

Explicit usage scenarios are provided via three bullet points (discovering hot data, confirming canonical choice, aligning use case). No explicit exclusions or alternative recommendations, but 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 indicate safe, read-only behavior. The description adds rich behavioral details beyond annotations: the algorithm, Jaccard similarity threshold, partition filter logic, fill check behavior, and the fact that calling with no args fails. No contradictions with annotations.

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

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

The description is lengthy but well-structured, front-loading the critical requirement and then providing detailed algorithm information. Each sentence adds value for a complex tool; minor improvements in conciseness are possible but not detrimental.

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 complex tool with no output schema, the description comprehensively explains the response structure (opportunities, partition check, fill check), usage constraints (Jaccard similarity, placeholder filter), and references sibling tools. The parameter schema is fully covered, making the description 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 clear descriptions for both parameters. The tool description goes further by explaining event is for single-event mode with concrete examples, and topic for cross-event mode with context, adding semantic 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 on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between event and topic modes, and references the sibling tool polymarket_fill_risk for custom sizing, providing excellent differentiation.

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 opens with the explicit requirement that one of event or topic must be provided, warns against calling with no args, recommends event mode for specific markets, and explains when to use each mode. It also includes a fill check warning about when not to trade and references a sibling tool, offering comprehensive usage guidance.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, confirming safe read-only behavior. The description adds substantial behavioral context: cache duration (1h KV), segmentation of opportunities (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), details on edge calculation (edge_pp_net after slippage, Kelly fractions capped at 0.25), and special handling for Fed bets and filtered opportunities. No contradiction with annotations.

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

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

The description is well-structured with clear sections and logical flow. However, it is very long and dense with technical details, many of which could be simplified or removed without losing core meaning. It is adequate but not concise; every sentence does not earn 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?

Despite lacking an output schema, the description fully explains the response structure: by_segment with three segments, fed_candidates/fed_note, and _diagnostics. It also details edge components (edge_pp_net, kelly_fraction), time-value warnings, and filter effects. Given the tool's complexity (9 parameters, multiple models), the description is comprehensive enough for an agent to use effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema for several parameters, such as slippage_pp (zero fees but bid/ask typical 20-50bp), min_liquidity (set to 5000 to drop thin-book), and category_filter (combine values with commas). This extra guidance makes the parameters more actionable.

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 the tool does: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb and resource, and distinguishes from simply paging through markets. However, it does not explicitly differentiate from sibling tool 'polymarket_arbitrage', so it loses a point for lack of sibling differentiation.

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

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

The description provides a clear usage scenario: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains tradeable-edge knobs and when to apply filters like min_liquidity and max_spread_pp. However, it does not explicitly state when NOT to use this tool or compare it to alternatives like polymarket_arbitrage.

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, non-destructive. The description greatly exceeds annotations by detailing response structure (tracked, expired, snapshot_dates), limits (60-day TTL), and data characteristics (daily closes, no intraday).

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, providing a thorough explanation of response fields and limitations. While well-structured, it could be more concise to improve scannability.

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 all return fields (tracked, expired, snapshot_dates) and edge cases (gaps, TTL). It is complete for a data analysis tool with optional parameters.

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 adequate descriptions. The description restates defaults and max/min but adds no new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: to analyze edge persistence and decay from daily snapshots. It distinguishes from siblings by focusing on time-series behavior and explicitly contrasts fresh vs. aged edges.

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 when to use (when edge persistence matters) but does not explicitly state when not to use it or compare with alternative tools like polymarket_edges or bet_research.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, pure query. The description adds rich behavioral context: it walks the order-book ladder, computes VWAP fill price, slippage, and verdicts (clean/degraded/cannot_fill). It also details basket-mode risks like forced directional risk and thin_legs, which 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 structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and is front-loaded with the core purpose. However, it is somewhat lengthy; a few sentences could be tightened without losing essential 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 having no output schema, the description thoroughly explains all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers edge cases (thin books, partial fills, forced directional risk). It also references sibling tools for context, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the side default logic per mode, how market/event accept slugs or URLs, and the dual interpretation of size_usd (max spend vs target proceeds for single-market; settlement notional for basket). It also mentions default values and clamp range (10–1,000,000).

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 checks realizable vs theoretical edge against order-book depth. It explicitly distinguishes between single-market and basket modes, and references sibling tools (polymarket_arbitrage, polymarket_edges) to clarify its specific role.

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

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

The description explicitly provides when to use this tool: before any polymarket_arbitrage signal or polymarket_edges trade above ~$500. It also warns against partial fills leading to unhedged directional positions, which is a crucial usage guideline.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses two modes, safety fields, compatibility_warning scenarios, temporal alignment, and skipped cross-type/subtype counters. It fully informs the agent of behavioral traits and edge cases.

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?

Every sentence earns its place. The description is well-structured with clear sections: core purpose, modes, response format, safety fields. It is front-loaded with the main function and uses concise, informative language.

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

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

Given the complexity of cross-venue spread, the description covers all necessary aspects: modes, response contents, compatibility warnings, temporal alignment, skipped matches. Despite no output schema, the description provides sufficient context for an agent to understand usage and limitations.

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

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

Schema coverage is 100%, but the description adds value by explaining the two modes (topic vs explicit), providing examples of topics, and clarifying that explicit parameters override topic. This goes beyond the schema property 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb 'spread' and resource identification. It distinguishes itself from siblings like polymarket_arbitrage 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 spreads are meaningful (equivalent bet shapes, temporal alignment) and when to skip (compatibility_warning conditions). It implicitly guides usage but does not explicitly compare to alternative tools like polymarket_arbitrage or search_within.

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

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

Annotations declare read-only and idempotent; description adds context about pairing with remember/forget and scoping per identifier, complementing 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?

Compact 3-4 sentences, front-loaded with core action, each sentence adds value 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?

For a simple one-parameter read tool, description covers purpose, usage, scoping, and sibling relationships; no output schema needed.

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 repeats the schema's note about omitting key to list keys, adding no new parameter meaning.

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

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

Clearly states retrieval of saved values or listing keys, with explicit reference to sibling tools remember and forget, distinguishing its role.

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 on when to use (look up previously stored data) and scoping, but lacks explicit exclusions or direct 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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: mark_read:true flags events as read so subsequent calls only show newer ones, explaining state-changing behavior beyond the annotations.

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

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

The description is a single paragraph that front-loads the purpose and adds detail without verbosity. Every sentence contributes useful information, though it could be slightly more concise by combining some clauses.

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

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

With no output schema, the description compensates by listing returned fields and explaining filter behavior. It covers pagination hints (limit, since) and the mark_read mechanism. A minor gap: no mention of error handling or limits beyond max events, but overall completeness is good.

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%, but the description adds meaningful context: it explains the mark_read parameter's effect ('so the next call only shows newer ones'), gives an example for type filter ('sec_8k'), and describes the return fields (source, citation_uri, raw payload).

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 a clear verb+resource combination: 'Pull fired events from your subscription feed.' It specifies the tool's output (alerts with source, citation_uri, payload) and mentions filtering options, distinguishing it from siblings like list_subscriptions.

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

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

The description gives context for when to use this tool (pulling alerts from the feed) and an alternative: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' It implicitly advises against using this tool for bulk scripting, providing clear usage guidance.

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

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

Discloses fan-out to multiple sources with fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure with citations. Annotations already indicate safety; description adds behavioral detail beyond annotations.

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

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

Description is somewhat lengthy but front-loaded with examples and structured logically. Each sentence adds value, though could be slightly trimmed. Still well-organized.

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

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

Given the tool's complexity (multiple sources, fallback, parameter types), the description is fully adequate. Mentions return structure despite no output schema, covering all necessary context.

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

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

Schema already describes all three parameters with 100% coverage. Description adds value by providing example relative shorthands ('7d', '30d') and clarifying that 'type' only supports 'company', enhancing usability.

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 returns a change feed for a company within a time window. Provides verb 'fans out' and specifies data sources. Distinguishes from sibling entity_profile, making purpose unambiguous.

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

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

Explicitly lists example queries and provides a when-to-use versus alternative: 'Use entity_profile instead when you want the static profile'. Gives clear context for usage.

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

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

Annotations indicate this is a write operation (readOnlyHint false), idempotent, and not destructive. The description adds behavioral context: data is key-value scoped by identifier, with persistence differences for authenticated users (persistent) vs anonymous (24 hours). No contradiction with annotations. Minor gap: does not mention overwrite behavior if key exists.

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

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

Four sentences, front-loaded with the primary purpose. Every sentence adds value: purpose, usage guidance, scoping, persistence details, and pairing notes. No wasted words.

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

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

Given the tool's simplicity (2 required params, no output schema), the description covers purpose, usage, behavior, and pairing with recall/forget. It does not describe return values, but for a write tool this is acceptable. The description adequately completes the context provided by annotations and schema.

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

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

Schema coverage is 100% with clear descriptions of key and value. The description adds meaning by providing example key patterns (subject_property, target_ticker) and clarifying that value can be 'any text — findings, addresses, preferences, notes', which enhances the schema's 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 verb 'Save' and resource 'data' for reuse. It explicitly distinguishes from sibling tools recall and forget by mentioning pairing with them, making it clear when this tool is appropriate and differentiating from similar tools.

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

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

The description provides explicit context on when to use (discover something worth carrying forward) with examples (resolved ticker, target address, etc.). It does not explicitly state when not to use, but the context is clear enough for an agent to decide.

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

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

Discloses that each call cascades through several lookup endpoints internally and replaces 2-3 manual lookups, adding value beyond annotations which already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. 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?

Front-loaded with illustrative queries. Each sentence adds meaningful detail; no fluff. Could be slightly more concise, but structure 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?

Despite no output schema, description fully covers what each entity type returns, including citations. Explains internal cascading behavior. For a simple entity resolution tool, it provides all necessary context 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%, providing baseline of 3. Description adds rich context: for company returns ticker + CIK + company name + citation URI; for drug returns RxCUI + ingredient + brand + citation. Also specifies accepted input formats for value, enhancing schema descriptions.

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

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

Description clearly states the tool resolves user-spoken names to canonical identifiers, using example queries that immediately convey purpose. It differentiates from siblings like lookup_city by specifying supported entity types (company, drug) and that it returns official IDs required by other 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 says 'Use FIRST whenever you have a name but need an ID', giving clear when-to-use guidance. Context implies not to use when ID is already known, but does not list specific alternative tools or when-not scenarios.

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 cover safety (readOnly, idempotent, non-destructive). Description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, surfaces extremes. 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 efficient sentences: first explains process, second explains use case and output. 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?

Despite no output schema, description specifies return fields (score, confidence, signal density). All parameters are explained in schema and supplemented by description. Complete for the tool's complexity.

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

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

Schema descriptions cover all parameters (100% coverage). Description adds meaning beyond schema by explaining the role of entity order (first is subject) and default model behavior.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, and distinguishes from sibling 'ai_visibility_check' which probes 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?

Provides a concrete use case for competitive AI-marketing audits. However, it doesn't explicitly state when not to use or when to prefer the single-entity sibling.

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. The description adds significant detail: it is a composite check that fans out across two services, returns a summary block with specific fields, per-advisory detail, links, alternative versions, and mentions partial failure handling and a potential 5-30s delay for bundlephobia's first measurement. No contradiction with annotations.

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

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

The description is a single paragraph of moderate length, front-loaded with the main idea, then details, then caveats. It is clear and not overly verbose, though a bulleted list could improve structure for 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 as a composite check across two services, the description is comprehensive. It lists return summary fields, per-advisory detail, links, alternative versions, addresses failure modes and ecosystem limitations, and covers what an agent needs to invoke and interpret results despite the lack of an output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add much extra meaning beyond the schema, only reiterating that scoped packages are accepted and that version is optional. This adds minimal value 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?

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It specifies the verb 'scan', resource 'dependency', and the outcome (safety, popularity, size assessment), and it is distinct from sibling tools like 'entity_profile' or 'bet_research'.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing clear context. It also notes limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which tells when not to use it and suggests 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses critical behavioral details: the use of BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flagging, and that every passage includes character offsets for verification. No contradictions with annotations.

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

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

The description is a single paragraph but highly structured: first sentence states the core purpose, second explains when to use, third provides companion tool context, and fourth gives technical details. Every sentence serves a distinct purpose with no redundancy or filler.

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

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

Despite the absence of an output schema, the description fully explains what the tool returns (passages with offsets and scores), the chunking strategy, truncation policy, and integration with sibling tools. With only 3 parameters and no output schema, this description covers all essential aspects for correct usage.

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

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

Schema coverage is 100% with descriptions, but the description adds significant value: it explains that 'text' is the document to search (e.g., SEC 10-K), gives natural-language query examples, specifies the default limit (5) and valid range (1-20), and describes return attributes (offsets, similarity scores) that are not in 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 identifies the tool's action ('semantic search INSIDE a fetched record') and resource ('text you already pulled'). It distinguishes itself from the sibling tool 'ask_pipeworx_grounded' by explaining how they pair together, and provides concrete examples of use cases (SEC 10-K, article, long tool result).

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

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

The description explicitly states when to use this tool ('when the record is too big to cram into the prompt') and why it helps ('saves context, returns only the passages that matter'). It also provides an alternative companion tool ('Pairs with ask_pipeworx_grounded') and explains the decision process for using one over the other.

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 idempotentHint=true, but the description does not clarify behavior if the same subscription is created twice. It does disclose the SMS cap (10/day) and webhook auto-disable after 10 failures, adding 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 the main purpose and return value, then organizes details by requirements, types, and delivery channels. It is mostly concise, though somewhat lengthy due to comprehensive 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?

The description covers subscription types, parameter examples, delivery constraints, and the return value. It lacks error handling details (e.g., duplicate subscriptions) but is otherwise complete given the tool's complexity.

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

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

Schema coverage is 100%, and the description enriches parameters with concrete examples (e.g., items:["5.02"] for officer change) and delivery constraints (HMAC signing verification, phone verification requirement). This adds significant 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 creates a subscription to a live-data event stream and returns the new subscription id. It uses specific verbs and resources, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies the requirement for a Pipeworx OAuth account (anonymous/BYO not allowed) and provides examples for each subscription type. It gives context for delivery channels but does not explicitly differentiate from alternatives like recent_alerts.

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 the tool is read-only, idempotent, and not destructive. The description adds behavioral detail about the output format (category-bucketed examples with exact tool+argument shapes) and the source (live catalog of thousands of tools), which is useful 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 moderately long but well-structured, starting with common queries, then the purpose, then output details, then usage. It is front-loaded with useful information, though some redundancy (e.g., repeating topic options) could be trimmed.

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 schema (one optional param, no required) and rich annotations, the description thoroughly explains the output and usage context. It covers when to use, what it returns, and how to use it, leaving no gaps for an agent.

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

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

Schema coverage is 100% for the single optional parameter. The description adds context beyond the schema by listing the allowed topic values and explaining that omitting the parameter gives a cross-category spread. This adds practical meaning.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns categorized example questions with tool+argument shapes. It distinguishes from sibling tools like ask_pipeworx and discover_tools by explicitly positioning itself as the first tool to use when unsure of Pipeworx's capabilities.

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

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

The description provides explicit usage guidance: call with no arguments for full spread or pass a topic to focus. It also advises using this tool first when unsure. It lacks explicit when-not-to-use instructions, but the context is clear enough for an agent.

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

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

The description adds significant behavioral insights beyond annotations: ownership enforcement, deactivation rather than deletion, and preservation of historical events. Annotations indicate idempotentHint=true and destructiveHint=false, which align with the description. 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 extremely concise: two sentences that immediately state the action and then provide key behavioral nuances. No unnecessary words, fits the allowed space well.

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 simplicity of the tool (single parameter, no output schema), the description covers all essential aspects: action, ownership constraint, side effects, and connection to recent_alerts for historical data. Complete and 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?

The input schema has one required parameter 'id' with a concise description. The tool description does not add further parameter details beyond what the schema provides. With 100% schema coverage, 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 action 'Cancel a subscription by id', specifying the verb (cancel) and resource (subscription). It distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

The description provides important usage context: ownership enforcement (you can only cancel your own subscriptions) and the behavioral difference from deletion (deactivation, not deletion). It references recent_alerts for historical events, offering implicit guidance on alternatives. However, it does not explicitly state when not to use the tool or compare to other tools like forget.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant behavioral context: returns a verdict, structured form, actual value with pipeworx:// citation, and percent delta. It also discloses the data source (SEC EDGAR + XBRL) and version limitations, providing transparency 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 well-structured, starting with example queries, then usage guidance, then technical details. It is slightly verbose but every sentence adds value. Could be marginally shortened without losing clarity.

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

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

Given one required parameter and no output schema, the description fully covers the tool's behavior: input (natural-language claim), supported domain (company-financial), output format (verdicts, citations), and limitations (v1 scope). An agent can confidently invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing natural-language examples of the claim parameter, clarifying the expected format and scope. It does not repeat schema details but complements them with usage context.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It provides example query patterns and explicitly distinguishes itself from sibling tools by noting it replaces 4-6 sequential calls. The domain (company-financial claims for public US companies) is specified.

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 advises 'Use whenever the agent needs to check whether something a user said is factually correct.' It gives specific examples and domain scope. However, it does not explicitly state when not to use this tool or mention alternatives like 'deep_research' or 'compare_entities,' which could handle different claim types.

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