Geonet Nz

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

Annotations already provide read-only and idempotent hints. Description adds key behavioral details: default model, BYO key for Anthropic, and return structure (score, confidence, signals, raw_response). Notes cost implications for Anthropic calls.

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 and a list of return fields. Front-loaded with purpose, every sentence adds value. 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?

No output schema, so description covers return values adequately (per-model and combined). Provides usage patterns and parameter behavior. Could mention potential slowness or rate limits, but annotations cover safety.

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

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

Schema coverage is 100%, but description adds valuable context: clarifies default model behavior, that _apiKey is only needed for anthropic, and that context helps disambiguate. Enhances understanding beyond raw 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 probes LLMs for brand/product visibility and scores them 0-100. Differentiates from sibling tools like scan_competitor_ai_presence by focusing on visibility scoring rather than general 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?

Explicitly mentions use cases like AI-marketing audits and pre-launch brand checks. Could improve by contrasting with similar tools (e.g., scan_competitor_ai_presence) or stating 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?

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds valuable context: it is a fast default entry point, works on every tier, returns structured answers with stable citation URIs, and implies the base tool is not hallucination-resistant by recommending grounded for that need. No contradictions.

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

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

The description is long but front-loaded with the key directive 'PREFER OVER WEB SEARCH'. Every section adds value: purpose, context, alternatives, examples. It could be slightly trimmed, but the verbosity is justified by the tool's broad scope.

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

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

Given no output schema, the description explains the return format (structured answer with pipeworx:// citation URIs). It covers what the tool does, when to use it, how it differs from alternatives, and includes representative examples. This is complete for a complex routing 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 all six parameters fully described in the input schema. The description does not add parameter-level semantics beyond what the schema provides, so baseline 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 the tool routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers, distinguishing it from siblings like ask_pipeworx_grounded and deep_research. The verb 'routes' plus the resource scope is specific and 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 instructs to prefer this tool over web search for factual questions, includes trigger phrases and examples, and provides clear guidance on when to escalate to ask_pipeworx_grounded or deep_research. This is exemplary 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?

The description discloses the experimental nature, the current inactive state (retired 2026-07-26), that it falls back to nothing (i.e., it is a full working router), and that behavior is identical to stable unless a candidate is under test. This adds rich context beyond the annotations (readOnlyHint, idempotentHint) without contradicting them.

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 dense sentences pack in key information: beta status, functional equivalence, current state, usage guidance, and fallback behavior. It is slightly long but every sentence earns its place with no wasted words or redundancy.

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

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

Given the tool's experimental complexity, the description thoroughly explains current behavior, usage, and the experimental context. It references 'same response shape' but doesn't detail the response format; however, since there is no output schema and the input is a simple question, this is a minor gap rather than a critical omission.

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

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

The input schema already provides 100% coverage for all six parameters, including descriptions for question and its aliases, so the baseline of 3 applies. The description merely says 'same arguments' without adding syntactic or semantic detail beyond what the schema already states.

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 identifies as a beta version of ask_pipeworx, a universal router for questions, and distinguishes itself from the stable sibling by noting candidate routing improvements and the experimental edge. The verb+resource is specific and the scope is well-defined.

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 it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It does not list exclusions or alternative scenarios beyond that, but the context is clear enough for an agent to choose this tool over the stable variant.

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

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

Description discloses detailed behavioral traits beyond annotations: it returns a specific structure with evidence and refusal reasons, only uses tool result content, and incurs an extra LLM call. It does not contradict annotations, which already cover read-only and idempotent safety; the description adds rich context on failure modes and refusal behavior.

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

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

The description is dense but efficiently front-loaded with purpose, then behavior, return format, and usage. It is longer than minimal but every sentence carries necessary information, and the structure is logical.

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 fully explains return values for both success and refusal cases, including refusal reason enums. It also covers cost trade-offs and usage boundaries, 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% with all six parameters documented as aliases for 'question'. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode with a specific verb ('EXTRACTS the answer using ONLY what the tool result contains') and resource scope. It distinguishes itself from the sibling ask_pipeworx by explicitly stating the cost trade-off and recommending ask_pipeworx for casual 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?

Explicit usage guidance is provided: use for high-stakes reads where answers will be quoted, cited, or acted on, and specifically for financial, legal, medical, or public statements. It also states the alternative: prefer ask_pipeworx for casual lookups, which is clear when-not-to-use guidance.

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

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

The description goes far beyond annotations to disclose detailed behavior: fan-out to category-specific data packs, resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits for low confidence, closed markets, illiquid spreads, and resolution-rule risk. This provides full transparency without contradicting the readOnlyHint or idempotentHint annotations.

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

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

The description is lengthy but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence adds value, and the main purpose is front-loaded. However, it could be slightly shortened without losing essential context, earning a 4 rather than a 5.

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 (3 parameters, no output schema), the description is exceptionally complete. It covers all input variations, internal processing, response structure, edge cases (closed markets, low confidence, wide spreads), and even resolution-rule risks. The agent can fully understand what the tool does and what to expect without additional documentation.

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 coverage is 100%, and the description adds significant meaning beyond the schema: it explains the market parameter with examples (slug, URL, question text), clarifies the depth enum with 'quick' vs 'thorough' behavior, and describes the include_raw parameter's impact on response size and use cases. This fully equips the agent to set parameters correctly.

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), resource (Polymarket bet), and the mechanism (single call). It also provides concrete use cases ('should I bet on X') and examples, making it easily distinguishable from sibling tools like polymarket_edges or compare_entities.

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

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

The description explicitly tells when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides context on inputs (slug, URL, question text) and classifies bet types. However, it does not explicitly state when not to use it or compare directly with siblings, though the detailed behavior implies 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is dense with information but well-organized, using bullet points for clarity. It is slightly long but each sentence adds value, so it earns a high score.

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

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

Given no output schema, the description explains the return format (paired data + citation URIs) and covers both entity types comprehensively. It replaces the need for separate output schema documentation.

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

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

Schema coverage is 100%, and the description adds meaningful context: explains the enum values for type, and for values clarifies acceptable formats (tickers/CIKs for company, drug names) with examples. Goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single call. It provides specific trigger phrases ('X vs Y', 'which is bigger') and distinguishes from sequential single-pack lookups and sibling tools like entity_profile.

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

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

The description explicitly advises preferring this tool over sequential lookups, gives clear usage patterns (trigger phrases), and explains the differences between company and drug entity types. It tells the agent exactly when to use this tool.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false; the description not only aligns but adds substantial behavioral context beyond the annotations: it explains parallel facet decomposition, hop-based iteration with gap recovery, contradictions[] scanning, semantic excerpting of long records, latency expectations (15-60s, thorough up to ~90s), and the guarantee that citations are always resolvable and findings are never invented (explicit gaps[]). This goes far beyond what annotations provide, deeply informing the agent about what happens during execution.

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

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

The description is long, but every sentence earns its place given the tool's complexity. It is front-loaded with the most critical operational constraint (ACCOUNT REQUIRED) and the alternative tool, then moves through mechanics, use cases, and exclusions. While dense, it is well-structured with clear thematic flow; the only minor deduction is that the length could be overwhelming, though it is justified by the tool's sophistication.

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

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

Given no output schema, the description thoroughly covers return behavior: findings packet with verbatim evidence + confidence + source + fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri resolvability. It also mentions latency, account tiers, semantic excerpting, and explicitly handles failure modes (gaps for uncovered facets, never invented). For a research tool of this complexity, this is remarkably complete — the agent would be fully prepared to set expectations and interpret results.

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

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

Schema coverage is 100%, with both parameters (question, depth) already described in the schema. The description adds meaningful value by explaining the depth enum's real-world consequences (quick=3 facets, standard=5 with gap recovery + contradictions, thorough=8 paid with follow-up hop) and by noting that broad/multi-part natural-language questions are acceptable and encouraged. This enriches the parameter semantics beyond the schema's field-level 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 this tool performs 'grounded multi-source research' across Pipeworx's structured data sources, decomposing questions into facets routed to 5,529 tools. It uses a specific verb ('research'), names a concrete resource (1455 structured data sources vs open-web), and distinguishes it from siblings like ask_pipeworx for single lookups. The contrast with open-web search and explicit comparisons make its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly directs users away for breaking/current-news topics ('prefer ask_pipeworx — it routes to live news APIs'). It also names alternatives (ask_pipeworx for single lookup) and specifies account/paid-plan prerequisites. This is textbook 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 and idempotentHint=true. The description adds that the tool returns top-N relevant tools with full schemas and curated examples, ready to call directly, which is valuable behavioral context.

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

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

The description is a single paragraph that efficiently covers purpose, usage, and output without redundancy. It is front-loaded with the most critical information.

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

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

Given the complexity (6 parameters, no output schema), the description fully covers what the tool does, when to use it, what it returns, and how to construct queries. It leaves no critical gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal additional meaning beyond the schema's parameter descriptions, mainly reinforcing the query parameter's role.

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 'find' and resource 'tools', and explicitly lists the domains. It distinguishes from siblings by positioning itself as the tool discovery mechanism.

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

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

The description explicitly says 'Call this FIRST when you have many tools available', providing clear when-to-use and implied when-not-to guidelines.

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 idempotent behavior. The description adds value by detailing behavioral traits: fans out across multiple sources in parallel, soft-fails on patents USPTO API, and returns specific fields like recent_filings with pipeworx URIs. 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 moderately long but well-structured with examples, sections, and bullet-like lists. Every sentence adds useful information. Minor redundancy (e.g., repeating 'soft-fails') but overall efficient.

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

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

Given the tool's complexity (multiple sources, many outputs, no output schema), the description adequately covers what is returned, limitations (patents soft-fail, names unsupported), and provides fallback behavior. Users get a clear picture of the tool's capabilities and constraints.

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

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

Schema coverage is 100%, but the description adds extra meaning: explains value can be ticker or zero-padded CIK, explicitly excludes names (directing to resolve_entity), and notes type currently only supports 'company' with more types coming. This enriches the schema info.

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 returns a 'full cross-source profile of a US public company' and lists detailed data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). This specificity distinguishes it from siblings like compare_entities or resolve_entity.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. Also warns that names are not supported and advises using resolve_entity first. Provides query examples, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but does not significantly extend beyond annotations.

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

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

Two sentences, front-loaded, with no wasted words. Efficiently conveys purpose and usage.

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, no output schema, and clear annotations, the description covers all essential context and even references sibling tools for completeness.

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

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

Schema coverage is 100% and describes the single parameter 'key'. The description briefly mentions 'by key' but adds no new 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?

Clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: stale context, task done, clear sensitive data. However, it lacks explicit alternatives or when-not-to-use guidance beyond referencing sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral details: fetches page, extracts title/description/key links, emits standard markdown. No contradictions.

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

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

Three well-structured sentences front-loaded with purpose, followed by mechanism, then use cases. No fluff—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 full schema coverage, clear annotations, and two simple parameters, the description fully informs an agent about input, process, output, and use cases. No gaps.

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

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

Schema has 100% coverage for both parameters (url, max_links). Description does not add significant new meaning beyond schema descriptions, so baseline 3 is appropriate.

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

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

Clearly states it generates a llms.txt file for any URL, specifying the action (generate) and resource (llms.txt for a URL). It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation, not scanning.

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

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

Provides explicit use cases (client indexing, personal project, competitor audit) and describes output format and destination. Lacks explicit when-not-to-use or alternative tools, but the context is clear enough for most 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds value by noting 'Keyless' (no authentication required) and specifying the data fields returned. This goes beyond the annotations without contradicting them.

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 sentence that efficiently communicates purpose, input, and output. It includes the key note 'Keyless' as a fragment. While very concise, it could be slightly restructured for readability, but it 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 no output schema, the description thoroughly enumerates the returned fields (time, magnitude, depth, locality, felt intensity, location quality, coordinates). It also specifies the data source (GeoNet) and that it is keyless. For a simple single-item retrieval tool, this is fully complete.

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

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

Schema description coverage is 100%, and the description of the 'id' parameter in the schema is already clear. The tool description reinforces that the ID is a GeoNet publicID but does not add new syntactic details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves detailed information for a single New Zealand earthquake using its GeoNet publicID. It lists the specific fields returned (time, magnitude, depth, locality, felt intensity, location quality, coordinates) and mentions it is keyless. This distinguishes it from sibling tools like recent_quakes which would list multiple earthquakes.

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

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

The description implies usage when you have a specific earthquake ID and need its details. However, it does not explicitly state when to use this tool versus alternatives like recent_quakes or volcano_alerts. The guidance is clear but not explicit about exclusions.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds the return fields but does not disclose additional behavioral traits like rate limits or auth requirements. 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 concise with two sentences: the first states purpose and return fields, the second gives usage guidance. 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?

For a simple list tool with annotations and one optional parameter, the description covers purpose, return fields, and usage. It lacks explicit mention of pagination or response structure, but given no output schema and the tool's simplicity, the description is adequately 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?

The single parameter include_inactive is fully described in the schema with a default of false. The description does not add further semantic meaning beyond what the schema already provides, and schema coverage is 100%, warranting a baseline score of 3.

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

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

The description clearly states 'List the caller's active subscriptions', providing a specific verb and resource. It lists the fields returned (id, type, params, etc.) and distinguishes from sibling tools like subscribe/unsubscribe by explaining it is for reviewing monitored items and finding ids to cancel.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and usage guidance, though it does not explicitly mention when not to use it or name alternative tools.

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

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

The description adds substantial behavioral context beyond annotations: explains the claim_token return flow, rate limiting ('5 per identifier per day'), that it's free and doesn't count against quota, and that the team reads digests daily. All this enriches the agent's understanding of side effects and expectations. 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 longer than average but every sentence carries useful information: purpose, types, exclusions, claim_token flow, and limits. It is front-loaded with the main purpose and structured logically. Slightly verbose but justified given the tool's complexity.

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

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

For a tool with 4 params, a nested context object, and no output schema, the description covers all necessary aspects: when to use, what to provide, claim_token workflow, rate limits, and what to avoid. It is complete enough for an agent to invoke correctly without further clarification.

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 workflow context for claim_token (how to obtain and use it) and clarifies the type enum semantics ('bug = something broke...'). It doesn't overspecify nested context fields, but the schema already covers those, and the description's additions are valuable.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools by explicitly scoping to Pipeworx tools only and clarifying it's for feedback, not for questions like ask_pipeworx.

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

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

Provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and an explicit exclusion: do not use for tools from other MCP servers. Also explains the claim_token workflow for later retrieval, giving clear context and alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds valuable behavioral details: data sourced from CF analytics-engine, no PII, cached 5min-1h depending on window. This goes beyond annotations to inform agent 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?

Two sentences plus a bullet list, zero wasted words. Front-loaded with the core function. Maintains readability while conveying all necessary information.

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

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

Given simple tool with one param and no output schema, description adequately covers return values (top tools, packs, volume), data source, privacy, and caching. No gaps identified.

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

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

Only one param 'window' with 100% schema coverage (enum with descriptions). Description adds further semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which clarifies the interpretation of values beyond the enum labels.

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 top tools, top packs, and call volume over a window. Uses specific verbs ('returns', 'calling') and resource ('Pipeworx trending'). Distinct from siblings like 'ask_pipeworx' or 'discover_tools' which serve different purposes.

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

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

Provides three explicit use cases (discovering hot data, confirming canonical choice, checking alignment). Mentions window implications. However, does not explicitly state when NOT to use it or alternative tools like 'discover_tools', but the context is clear enough.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral detail: how the scan works, partition checks, similarity filtering, placeholder filtering, and fill check logic. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections for modes, filters, and responses. Every sentence is informative, though slightly verbose. Could be more concise but not excessively 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 tool with multiple modes and internal algorithms, the description is remarkably complete. It explains the algorithm, filters, response structure, and references other tools. No output schema is provided, but the description adequately covers return values.

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 provides 100% coverage with descriptions for both parameters. The description greatly expands meaning, explaining what each mode does, how slugs are used, and what the response includes. Adds significant 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 via monotonicity violations and partition-sum checks. It distinguishes between modes (trending_scan, event, topic) and differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for a specific market slug, topic for cross-event scanning. Also warns against trading when realizable edge ≤0 and suggests polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond the readOnlyHint, openWorldHint, and idempotentHint annotations. It reveals internal logic (three model families, Kelly sizing, caching at KV level, diagnostics, edge calculation) and caveats (Fed bet exclusion, 'Market moved X.Xpp in 24h' warning). 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 comprehensive but verbose (~600 words). While well-structured with labeled segments and key points, an AI agent might benefit from a more concise summary. Every sentence provides value, but length reduces conciseness.

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

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

Despite no output schema, the description details the response structure (by_segment, fed_candidates, _diagnostics), explains edge calculation, and covers all 9 parameters with usage context. It is remarkably 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%, so baseline is 3. However, the description adds meaningful context beyond schema descriptions, e.g., explaining why min_kelly doesn't apply to partition arbs and detailing the tradeable-edge knobs. This extra semantic 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly targets the use case 'what should I bet on today' and distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement.

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

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

The description provides clear usage context ('discover opportunities without paging hundreds of markets') and details parameters like min_liquidity and max_spread_pp for filtering. However, it does not explicitly state when to avoid this tool or compare with alternatives, slightly reducing the score.

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 extensively covers behavior beyond annotations: output structure, trend computation, decay calculation, snapshot timing, and limitations (60-day TTL, daily closes). No contradiction with readOnlyHint or other annotations.

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

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

The description is relatively long but well-structured with a purpose statement, output details, and limitations. Each sentence contributes value, though it could be slightly more streamlined.

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

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

Given no output schema, the description comprehensively explains the return fields (tracked, expired, snapshot_dates) and their meanings. Limitations and caveats are clearly stated, making the tool's behavior fully transparent.

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 parameters, but the description adds defaults (days=14, window='1wk'), maximum days (30), and context about snapshot families. This adds meaningful 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 provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It distinguishes from sibling tools by focusing on historical time-series analysis rather than raw edge data.

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

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

The description implies usage for distinguishing between fresh and aged edges, but does not explicitly state when not to use or provide direct comparisons to siblings. The context is sufficient for an informed 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds detailed operational behavior (walks the ladder, returns specific fields like slippage, verdict, etc.) and warns about forced directional risk, without contradicting annotations.

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

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

The description is well-structured with clear sections for modes and an explicit 'USE THIS' directive. While slightly lengthy, every sentence adds value given the complexity of the tool.

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 enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict; basket fields like theoretical_sum, realizable_sum). All 4 parameters are fully documented. The tool's complexity is well-served.

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%. The description adds significant context beyond schema, such as the dual-mode (market vs event), the meaning of size_usd in basket mode (settlement notional), and auto-detection for side in basket mode.

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 a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly positions itself as a pre-trade risk check before using arbitrage or edges tools.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the risks of partial fills and uncapturable overround, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant behavioral context: it explains the compatibility_warning field's two cases (non-equivalent bet shapes or semantically unrelated events), temporal alignment constraints, and skipped comparison counters. It does not contradict any annotation; the readOnly nature is consistent with a query that does not modify state.

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

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

The description is dense and contains all necessary information, but it is somewhat long and uses long sentences (e.g., the safety fields explanation is a single paragraph). It is front-loaded with the main purpose, and the structure (modes, response, safety) is clear. Slightly more conciseness could improve readability, but it still earns a high score.

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?

There is no output schema, so the description carries full burden for explaining output. It details the response: each venue's leg-by-leg prices, matched spread with top_spreads_pp, compatibility_warning, skipped_cross_type/subtype counters, and temporal_alignment. This is complete for a complex tool with 3 parameters and no output schema.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds meaning beyond schema: it explains that 'topic' is a shortcut mapping to specific events on each venue, and that 'kalshi_event_ticker' and 'polymarket_event_slug' override the topic-mapped side. The schema examples (topic: fed, btc) further clarify usage.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses a specific verb ('compute spread') and identifies the two venues and the outcome equivalence. This differentiates it from sibling tools like polymarket_arbitrage (which focuses on intrapolymarket arbitrage) and polymarket_edges (which estimates edge).

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 two usage modes: topic shortcuts and explicit tickers. It warns that most pre-mapped topics return compatibility_warning and that real spreads are rarer than the shortcut list suggests. It also explains when to avoid: when bet shapes are not equivalent or temporal alignment is false. This is comprehensive guidance on when and 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?

Annotations already declare readOnlyHint and idempotentHint. Description adds scoping details (user identifier) beyond annotations, which is useful behavioral context.

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

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

Description is three concise sentences, front-loaded with the core action, followed by use case and scoping. No wasted words.

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

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

Given the simple interface (1 param, no output schema), description covers purpose, usage, scoping, and sibling relationships. Could explicitly mention return format (value or list).

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

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

Schema covers the sole parameter with clear description. The tool description reiterates the omit-to-list behavior but does not add new semantic information beyond the schema.

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

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

Description clearly states the tool retrieves a value by key or lists all keys. It specifies the resource (values saved via remember) and distinguishes from siblings like remember and forget.

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 when to use (look up stored context), and mentions pairing with remember/forget. Could be more explicit about when not to use, but overall provides solid 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description explains the returned fields (source, citation_uri, payload), the effect of mark_read, and that the feed is also accessible via a GET URL. 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?

Three sentences, each adding value. Front-loaded with the core purpose. Concise without any redundant information.

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

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

Description covers input parameters, behavior, output format, and even an alternative access method. No output schema exists, but return fields are described. Given the simplicity of the tool, it is complete.

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

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

Schema coverage is 100%, providing baseline 3. The description adds extra context for mark_read ('so the next call only shows newer ones') and explicitly mentions filtering by type and since, enhancing parameter understanding beyond schema.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts. It distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on reading alerts.

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

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

Provides explicit guidance on filtering by type and since, using mark_read to manage state, and notes that polling works fine. Also mentions an alternative HTTP endpoint for scripts, indicating when to use this tool vs others.

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

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

Annotations already indicate read-only and idempotent behavior. Description adds significant context: parallel call structure, source fallback (GDELT to GNews), soft-failure for patents, return format with grouped changes and citation URIs.

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 efficient with front-loaded query examples. Every sentence adds value, though slightly longer than minimal.

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

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

Covers multiple sources, fallback, return structure, and soft-failure. Lacks explicit error handling but is sufficient for a read-only tool without 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 coverage is 100% so baseline is 3. Description enriches with examples of 'since' formats, recommended default ('30d'), and explains 'value' can be ticker or CIK, and 'type' is limited to 'company'.

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

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

The description clearly states it is a change feed for a company in a time window, lists specific sources (SEC EDGAR, GDELT/GNews), and explicitly distinguishes from entity_profile for static profiles.

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

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

Description provides explicit query examples and directly tells when to use entity_profile instead. It also explains fallback mechanisms for news sources, giving clear usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds value by explaining MMI scale, clamping behavior, and output fields (magnitude, depth, etc.), which go beyond what annotations provide.

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 filler. It front-loads the source and purpose, then provides parameter guidance and output details. Every sentence contributes meaningful 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 there is no output schema, the description fully covers the return fields (magnitude, depth, locality, felt intensity, coordinates) and ordering (newest first). It addresses the core query parameters and their behavior. For a read-only query tool, this is complete and self-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 description coverage is 100%, but the description adds significant context: it explains the MMI scale (e.g., '3 ≈ widely felt, 5 ≈ damaging'), specifies defaults (limit default 15, min_mmi default 3), mentions clamping for out-of-range values, and clarifies that -1 returns all quakes. This enriches the schema and helps the agent choose correct values.

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

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

The description clearly states it returns recent New Zealand earthquakes from GeoNet, filtered by MMI. It specifies the source (GNS Science), the filter parameter (MMI), and the output fields, making the purpose unambiguous and distinguishing it from sibling tools like 'get_quake' or 'volcano_alerts'.

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

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

The description tells when to use it (to get recent quakes filtered by MMI) and mentions it is 'Keyless', implying no authentication. It provides context on MMI thresholds. However, it does not explicitly state when not to use it or name alternatives, though sibling tool names provide implicit differentiation.

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

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

Beyond annotations (idempotentHint, destructiveHint), description adds persistence details (authenticated vs anonymous, 24-hour retention) and scoping by identifier. However, it does not explicitly state that storing the same key overwrites previous value, which is implied but could be clearer.

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-structured sentences, front-loaded with purpose, no redundant information.

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

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

For a simple tool with two parameters and no output schema, the description covers purpose, usage, behavior, persistence, and pairing with siblings, fully meeting the context needs.

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

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

Schema coverage is 100%, and the description adds naming conventions (e.g., 'subject_property') and value types beyond the schema, enhancing 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 'Save data the agent will need to reuse later' and provides concrete examples (ticker, address, preference), distinguishing it from siblings like recall and forget.

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 when you discover something worth carrying forward' and suggests pairing with recall and forget, providing clear guidance on when 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?

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context beyond annotations: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit labeling of unresolved identifiers, and source attribution for each identifier. This greatly enriches the agent's understanding of behavior.

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

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

The description is dense and front-loaded with examples and primary usage instruction. It is longer than a typical definition, but every sentence provides value (supported types, input formats, output composition, degradation behavior). It is well-structured despite its length, so it earns a 4 rather than a 5.

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 no output schema, the description fully covers return values for both types: for company, it lists CIK, ticker, company_name, LEI, parent/ultimate-parent/children, FIGI, and the `unresolved` field; for drug, it lists RxCUI, ingredient, brand, and citation. It also addresses edge cases (unavailability of sources) and the cascade behavior, making it 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% for both parameters, but the description adds crucial detail: accepted input formats (ticker, CIK, or name for company; brand or generic for drug) and the meaning of each type's output. This goes beyond the schema's basic descriptions, earning a score above the baseline of 3.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples (ticker, CIK, LEI, RxCUI). It distinguishes itself from siblings by noting it provides identifiers other tools require as input and is to be used 'FIRST' when a name needs an ID.

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' and explains it replaces 2-3 manual lookups, providing strong context. However, it doesn't name alternative tools or explicitly state when not to use it, so it falls short of fully explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: it probes each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradictions.

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

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

The description is two sentences: the first states the core action, the second provides use context and output details. Every sentence is informative and there is no 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?

Even without an output schema, the description describes the output (ranked list with score, confidence, signal density). It also specifies constraints like 2-8 entities and first as subject. Given the complexity, the description is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning: it explains that the first entity is treated as the subject, that 'models' defaults to workers-ai and requires an API key for anthropic, and that 'context' disambiguates common names. This adds value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks by score. It distinguishes itself from sibling tools like ai_visibility_check (single probe) and compare_entities (general comparison).

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example query. It implies when to use this tool over ai_visibility_check (single vs. multiple entities), but does not explicitly state when not to use or list 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, idempotentHint, and destructiveHint. The description adds value by explaining partial failure behavior (bundlephobia timeout handling, sources_failed list) and the composite nature of the call. This goes beyond what annotations provide.

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 somewhat long but front-loaded with purpose and usage. Every sentence provides necessary detail (sources, return fields, limitations). It could be slightly more concise, but the structure is clear and efficient.

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

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

Given the annotations (readOnly, idempotent) and no output schema, the description adequately covers return content (summary, advisories, links, alternatives) and error behavior. It lacks mention of rate limits or pagination, but these are not critical for this tool's typical use.

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

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

Schema coverage is 100%, but the description adds practical context: scoped packages are accepted, version defaults to latest. This enhances meaning 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 adding an npm package, combining deps.dev and bundlephobia. It uses specific verbs ('scan', 'check') and resources ('npm package', 'deps.dev', 'bundlephobia'), distinguishing it from siblings.

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: 'Use whenever an agent asks...'. It also notes the npm ecosystem limitation and mentions partial failures. While it doesn't list alternatives, no siblings directly overlap, making the guidance 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 read-only, idempotent, non-destructive behavior. The description adds algorithmic details (BGE-base-en embeddings, cosine, 500-char windows), character cap (200K chars with truncation flag), and explains return format (offsets, scores). 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?

Three focused sentences with front-loaded purpose, followed by usage context, then technical details. No wasted words; 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?

Despite no output schema, the description explains return values (passages, offsets, scores) and flags truncation. It covers parameters, usage, limitations, and integration with sibling tools. 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%, so baseline is 3. The description adds examples for query (e.g., 'supply-chain risk') and clarifies text max length beyond schema. However, it does not explain the limit parameter in detail beyond defaults, so not a perfect 5.

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 semantic search inside a fetched record, with examples like SEC 10-K or article, and distinguishes it from general search tools by specifying it works on already-pulled text. It avoids tautology and provides specific verb and resource.

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

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

Explicitly advises when to use: when the record is too large for the prompt. It also mentions pairing with ask_pipeworx_grounded, providing a clear alternative strategy. This gives the agent explicit decision support.

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

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

Description provides extensive behavioral details beyond annotations: requires OAuth, returns id, has per-type params, delivery options with caps (10/day SMS), webhook auto-disable after 10 failures, and signing secret. 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?

Well-structured with purpose first, then requirements, types, delivery. Slightly verbose but each section is informative. Minor improvement could condense delivery descriptions.

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 covers input thoroughly with examples and constraints (limits, verification). Returns mentioned but not fully specified; still sufficient for typical use.

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

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

Schema coverage is 100%, but description adds examples for each type (sec_8k, polymarket_edge, etc.) and delivery options, providing meaningful beyond-schema guidance.

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 proactive monitoring subscription and returns a subscription id, distinguishing it from siblings 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?

Explicitly requires Pipeworx OAuth account, lists supported types with examples, and mentions delivery channel limitations. While it doesn't directly contrast with pull-based alternatives like recent_alerts, the context is clear enough.

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, and non-destructive. The description adds behavioral details beyond that: it explains the behavior with and without the 'topic' argument, the output structure (category-bucketed examples), and that examples are drawn from a live catalog.

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

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

The description is relatively long but well-structured, starting with alternative phrasings, then the core purpose, output details, and usage instructions. Every section adds value, though it could be slightly more 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 tool's simplicity (one optional parameter, no output schema, comprehensive annotations), the description fully covers purpose, when to use, how to invoke (with and without topic), and the nature of the output (example questions with tool/argument shapes). No gaps identified.

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

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

Schema coverage is 100%, with the 'topic' parameter described as an optional focus area. The description adds meaning by listing specific topic values (e.g., finance, pharma, economics) and explains the behavior when omitted ('Omit for a cross-category spread'), which is 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 states that the tool returns category-bucketed example questions with the exact tool and argument shape that answers each, serving as the onboarding entry point. It distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on getting started and learning meta-tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear guidance on when to use the tool, but does not explicitly state when not to use it or mention 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 annotations (idempotentHint=true, destructiveHint=false), the description adds crucial behavior: 'Ownership is enforced' and 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This clarifies side effects and constraints not in structured fields.

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

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

Two sentences front-load the core action and follow with essential behavioral details. Every sentence adds value; no redundancy or unnecessary elaboration.

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

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

Given the tool's simplicity (1 param, no output schema, adequate annotations), the description covers effect, ownership, and linkage to recent_alerts. Missing mention of response or idempotency, but those are handled 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?

The schema covers the single parameter 'id' with description 'Subscription id (uuid) returned by subscribe.' The description restates 'by id' without adding new semantic nuance, so meets baseline for 100% schema coverage.

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb 'cancel' and resource 'subscription'. It distinguishes from sibling tools 'subscribe' (creation) and 'recent_alerts' (historical events), and clarifies that the row is deactivated, not deleted.

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

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

The description provides clear context: ownership is enforced so only own subscriptions can be canceled, and deactivation preserves history accessible via recent_alerts. It implies when to use this tool, but does not explicitly exclude alternatives for scenarios like permanent deletion.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already establish safety, but the description adds substantial behavior: the two-path execution (structured vs grounded), the return of a verdict enum with specific meanings, the crucial distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source coverage), and the pipeworx:// citation format. 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?

Long but every sentence earns its place. Trigger phrases are front-loaded for quick scanning, the two execution paths are clearly separated, and the callout about could_not_verify vs unsupported is a necessary caveat. No redundant or filler content.

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 fully covers return value semantics: the six possible verdicts, the actual value with citation, and reasoning. It also explains edge cases (could_not_verify, unsupported) and the tool's internal routing logic. This is complete for a tool of this 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%, so baseline is 3. The description enhances parameter meaning by explaining tolerance_pct's role: 'Overrides the tolerance implied by the claim wording — set 1–2 for hallucination detection where any material error must be refuted. Default: implied by wording, capped at 5.' This adds actionable guidance beyond the schema's plain description.

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

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

The description opens with concrete trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and a clear verb+resource: natural-language claim verification against authoritative sources. It sharply distinguishes from sibling tools by explicitly scoping to factual correctness checks and by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance: company-financial claims take the SEC EDGAR + XBRL fast path, anything else falls through to the grounded pipeline. The 'Replaces 4–6 sequential calls' line gives a clear alternative, making when-to-use unambiguous.

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 value by mentioning it is 'Keyless' and explaining the scale (0-5) and what is included (activity description, hazards, aviation colour code), which provides behavioral context beyond annotations.

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

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

The description is four sentences, front-loaded with the core purpose, and every sentence provides unique information (data source, scale, included details, keyless access). 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?

For a zero-parameter, read-only tool, the description is comprehensive. It covers data source, geographic scope, scale explanation, and return fields. No output schema exists, so the description substitutes effectively. Possibly missing update frequency, but not crucial.

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

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

There are zero parameters, so the description is not required to add parameter info. However, it explains the output format and scale, which is helpful given the lack of an output schema. Baseline 4 is appropriate.

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

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

The description clearly states it provides 'Current Volcanic Alert Levels for all monitored New Zealand volcanoes' from GeoNet, distinguishing it from USGS. The name and title match. Among siblings like get_quake or recent_alerts, this tool is uniquely positioned for NZ volcano alerts.

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

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

Implicitly, the description suggests using this tool for NZ volcano data where USGS doesn't cover, but it doesn't explicitly state when to use versus alternatives or when not to use. 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.