Attom

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds useful behavioral context: default free model, payment model for Anthropic, and return format with score, confidence, signals, raw_response. 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 concise sentences: first states core function, second adds model and key details, third lists use cases. No filler, front-loaded, and every sentence earns its place.

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

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

Given no output schema, the description explicitly describes the return format (per-model and combined view). With 4 parameters (1 required) and no nested objects, the description covers all necessary information including use cases and model options.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning: explains the default model, clarifies that `_apiKey` is only needed for Anthropic, and notes that 'context' helps disambiguate. 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 provides a specific verb ('Probe'), resource ('LLMs'), and outcome ('score visibility 0-100 per model'), clearly differentiating from sibling tools like 'ask_pipeworx' (Q&A) and 'scan_competitor_ai_presence' (similar but not same). Use cases (AI-marketing audits, pre-launch checks) further clarify purpose.

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

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

The description explains when to use the tool (audits, brand checks, monitoring) and gives concrete guidance on the default model and optional API key for Anthropic. However, it does not explicitly state when not to use it or compare to specific alternatives among the siblings.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds behavioral context by explaining it routes to multiple tools, fills arguments, returns citations, works on all tiers, and is a single fast call. It also clarifies news routing. This goes beyond 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 long but each sentence contributes: scope, behavior, examples, alternatives, and edge cases like news. It's front-loaded with the strongest usage signal ('PREFER OVER WEB SEARCH'). Some redundancy exists (repeating 'even if web search could also answer it'), but overall the length is justified for a meta-tool handling 5,529 tools.

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 this is a routing tool with no output schema, the description adequately covers what happens: returns structured answer with pipeworx:// citation URIs. It also covers when to use it vs grounded/deep_research, domain coverage, and that it works on all tiers. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all properties described as aliases for question, and the description doesn't add direct parameter syntax details. However, it enriches the meaning with a long list of example questions and domain categories, helping the agent formulate appropriate natural-language inputs. This justifies moving 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 it answers factual questions by routing to 5,529 tools across 1455 verified sources and returning structured answers with citations. It opens with 'PREFER OVER WEB SEARCH' and lists many domains, making the verb and resource unmistakable. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance: prefer over web search for factual questions, use whenever the user asks 'what is', 'look up', etc. It also names specific alternatives and when to step up: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. 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 thoroughly explains the experimental nature, including that candidate routing improvements are enabled live, that no candidate is currently active, and that it is a full working router with no fallback. This adds significant context beyond the readOnly and idempotent annotations, making the tool's behavior very transparent.

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

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

The description is front-loaded with the key purpose and is moderately concise at four sentences. Each sentence adds useful detail, though the parenthetical about the last retired candidate could be trimmed without losing essential meaning.

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

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

Given the tool's complexity as a beta router, the description covers the relationship to the stable version, current status, and routing behavior. It lacks an explicit explanation of what 'routing' accomplishes or example use cases, but the schema and sibling tool names provide enough context for selection.

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 schema already documents all parameters and aliases. The description mentions 'same arguments' as ask_pipeworx but adds no new meaning beyond the schema, which fits the baseline for high 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 identifies this as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling tool by emphasizing the experimental routing edge, which is exactly what sets it apart.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, providing clear context for when to choose this tool. It also notes the current state (no active candidate) and that results are compared against the stable router, though it could be more explicit about when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context beyond that: it returns {answer, evidence, confidence, ...} with explicit refusal reasons, restricts answers to 'ONLY what the tool result contains,' and discloses the cost of 'one extra LLM call.' This is rich context the annotations don't 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 dense but every sentence earns its place: purpose, routing mechanism, exact return shape, refusal reasons, when to use, and cost tradeoff. It is front-loaded with the primary purpose and ends with a practical preference note. 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?

With no output schema present, the description takes full responsibility for explaining the return value structure. It does so completely with a detailed success object and a refusal object containing all possible refusal_reason values. It also covers the routing behavior and the extra-cost tradeoff, 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?

The input schema already covers 100% of parameters with descriptions for all aliases (question, q, text, input, query, prompt). The description adds only a general claim that the tool 'fills arguments' automatically, which restates what the schema implicitly provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description starts with a specific verb+resource+mode: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the sibling tool ask_pipeworx by stating 'Same routing as ask_pipeworx... then EXTRACTS the answer using ONLY what the tool result contains.' This unique extraction behavior differentiates it from the plain ask_pipeworx.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides a direct alternative: 'prefer ask_pipeworx for casual lookups.' This fully addresses when to use this tool vs. the sibling.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds value by specifying the return fields (assessed value, market value, etc.) and the data source ('public assessor data via ATTOM'), providing 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 extremely concise, front-loaded with example queries, and every sentence adds value. No waste; it efficiently conveys purpose, source, and return data.

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 three simple parameters, thorough annotations, and an output schema (not shown but present), the description sufficiently covers purpose, source, and return fields. Minor gaps like data freshness or geographic coverage do not significantly impact completeness for a tax-assessment 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 clear descriptions for all three parameters (_apiKey, address1, address2). The description adds minimal extra semantic value beyond the schema, though the example queries provide contextual hints. 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 uses multiple specific verb phrases (e.g., 'Property tax / taxes on [address]', 'assessed value of [house]', 'tax bill for [property]') that clearly indicate the tool retrieves county tax-assessor data for US properties. It lists return fields (assessed value, market value, tax amount, etc.) and distinguishes it from siblings like attom_avm or attom_property_detail by focusing on tax assessment.

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 example queries ('Property tax on [address]' etc.) that implicitly guide when to use the tool. It does not explicitly state when NOT to use it or list alternatives, but the context of sibling tools (e.g., attom_avm for market values) makes the use case clear.

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

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

Annotations already declare read-only and idempotent behavior. The description adds context by specifying return values (estimated market value, confidence score, low/high range) and scope (US residential properties), which go beyond the structured annotations.

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

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

The description is three sentences, front-loaded with example queries, and each sentence serves a distinct purpose (examples, explanation, 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?

The description adequately covers the tool's purpose, output, and usage. An output schema exists to document return values. It could mention the API key requirement explicitly, but that is already in the schema.

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

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

Schema coverage is 100% with clear parameter descriptions for address1, address2, and _apiKey. The description does not add further parameter-level meaning, so a baseline score of 3 is appropriate.

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

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

The description clearly states it provides an automated valuation model for US residential properties and lists example queries. However, it does not explicitly differentiate from sibling ATTOM tools like attom_assessment or attom_rental_avm, which could cause confusion for an agent.

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

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

It advises using for 'instant home-price questions' and suggests pairing with attom_sales_history, but does not specify when not to use it or contrast with alternatives like attom_assessment. Some context is provided, but exclusions are missing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description complements them by listing example attributes (bedrooms, bathrooms, etc.) and noting the data source (ATTM Data Solutions). No contradictions; adds some 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 two sentences plus example queries, front-loaded with the core purpose and examples. Every sentence adds value with no redundancy or fluff.

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

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

The description explains the tool's output (property characteristics), data source, and usage context ('for a US residential or commercial address'). With an output schema present, no additional return value details are needed. Complete for its 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 description coverage is 100%, so the schema already explains all parameters. The description does not add new semantics beyond the schema's field descriptions and examples. 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 uses specific verbs and resources ('returns full property characteristics') and distinguishes from sibling tools like attom_assessment and attom_property_search by focusing on structured attribute lookup by address. Example queries like 'how many bedrooms / bathrooms' reinforce the purpose.

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

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

The description explicitly says 'Use whenever an agent needs structured property attributes by address,' providing clear context. It does not explicitly state when not to use it or mention alternatives, but the sibling tools list and the tool's specificity imply appropriate use cases.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds context about the return format (addresses and property IDs) but does not contradict annotations. It adds minor behavioral information 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 a single, well-structured paragraph. It front-loads natural language examples, states the core function, and ends with usage guidance. Every sentence adds value without redundancy.

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

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

Given the tool has 12 parameters, full schema coverage, an output schema, and multiple sibling tools, the description adequately covers the main usage patterns (ZIP vs. radius search, filtering options, and follow-up workflow). It is complete for agent understanding.

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 each parameter described in the input schema. The description provides high-level context (search by ZIP or radius, filters) but does not add meaning beyond what the schema already provides, hence baseline 3.

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

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

The description clearly states it searches US residential and commercial properties by ZIP or lat/lng radius with filters. It provides natural language examples like "Find houses / homes / properties..." and lists what it returns (addresses, ATTOM property IDs). It also explicitly differentiates from sibling tools by naming attom_property_detail, attom_avm, and attom_sales_history as follow-up calls.

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

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

The description gives explicit usage guidance: "Use first when you need to find candidate addresses, then call attom_property_detail / attom_avm / attom_sales_history on the picks." This tells the agent when to use this tool versus the 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, etc. The description adds that the tool returns rent, yield, and range, but does not disclose behavioral traits like error handling, rate limits, or address validation. It does not contradict annotations.

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

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

The description is concise (about 50 words) and front-loaded with example questions. Every sentence adds value, though it could be more structured with bullet points. No wasted words.

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

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

Given the tool's simplicity (3 required params, no enums) and presence of an output schema, the description adequately covers what the tool does and returns. It does not explain error scenarios or prerequisites, but the annotations and schema compensate.

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% with clear parameter descriptions. The description provides context but no additional semantics 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 provides rental AVM for US properties, returning estimated monthly rent, rental yield, and range. It distinguishes itself from sibling tools like attom_avm (property value) by focusing on rental income, though it does not explicitly name 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 gives example queries and mentions use cases (landlord/investor/cash-flow analysis), but does not specify when not to use it or provide alternatives. The context is clear but lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the return data (sale dates, prices, deed types, buyer/seller details) and the data source (public deed records via ATTOM). 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 with embedded example queries, immediately conveying purpose. It is front-loaded and contains no fluff. Every word serves a purpose.

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

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

With an output schema present and rich annotations, the description covers the core functionality and return types. It could mention that it only works for US properties (implicit in ATTOM data) or that a valid address is required, but it is largely complete for this API 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%, and the description mentions 'by address', which aligns with the two address parameters. However, the description does not add new meaning or constraints beyond what the schema already provides (e.g., format of address). Baseline 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 starts with example queries like 'When was [house] last sold' and explicitly states it returns 'complete sales/transaction history for a US property by address' including specific data points (sale dates, prices, deed types, buyer/seller details). This clearly distinguishes it from sibling tools like attom_assessment or attom_avm.

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 through example queries but does not explicitly state when to use this tool versus alternatives like attom_assessment or attom_property_detail. No direct comparison or exclusions are provided, relying on the tool name and examples to guide selection.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable context by specifying the aggregated nature of the data, the return fields, and the time-range/interval options, which go beyond what annotations alone convey.

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, front-loaded sentence with example queries, followed by a concise explanation of the output and use case. Every clause earns its place, with no redundancy or fluff.

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

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

For a read-only market trends tool with complete schema coverage and an output schema, the description covers purpose, usage context, and return type sufficiently. It does not dwell on edge cases or limitations, but these are less critical given the annotations and 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 the baseline is 3. The description mentions the date range and intervals in prose, mirroring the schema's param descriptions but not adding new semantic depth beyond what is already present in the input 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 aggregated real estate market trends by ZIP, listing the specific outputs (average/median sale price, sales volume, price changes) and time intervals. It distinguishes itself from sibling tools like attom_sales_history and attom_property_detail by emphasizing aggregate market-level data rather than individual addresses.

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

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

It gives concrete example queries and explicitly advises using it for market-direction questions 'before pulling individual addresses,' which implies a distinction from address-level tools. However, it does not explicitly name alternative sibling tools or provide exclusion conditions beyond the address-level contrast.

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 readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, which are not contradicted. The description adds that the tool returns school name, type, grade levels, distance, and performance rankings, which is useful behavioral context beyond the annotations.

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

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

The description is a single, well-structured paragraph with front-loaded example queries. Every sentence is meaningful and there is no fluff. At about 50 words, it is appropriately 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 has an output schema (indicated true), the description does not need to detail return values. It covers the core purpose, example use cases, and key return fields (school name, type, grade levels, distance, performance rankings). This is complete for a search tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond what the schema provides (radius default and max, lat/lng required). It mentions 'by lat/lng radius' but that is already implicit.

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

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

The description uses specific verbs ('find', 'returns') and clearly states the resource ('K-12 schools near a US location by lat/lng radius'). It includes concrete example queries (e.g., 'Schools near [address]'), which distinguishes it from sibling tools like property search or assessment.

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

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

The description explicitly states the use case: 'Use for relocation / family-housing questions paired with property search.' This provides clear context. However, it does not explicitly mention when not to use this tool or name alternatives, though the sibling list lacks other school tools, making the guidance sufficient.

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

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

Annotations declare readOnly, openWorld, idempotent. Description adds extensive behavioral details: resolution logic, fan-out examples, response shapes, resolver contract, parent_event extractor, news fallback, safety short-circuits, closed market handling, illiquid spread, cancellation rules. No contradictions.

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

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

Description is long and detailed, but front-loaded with main purpose. Could be more concise; some redundancy and excessive detail may overwhelm. Structured with sections but verbose.

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 tool complexity (multiple sub-results, edge cases), description is very complete. Covers inputs, process, outputs, error states, safety, cancellation rules. No output schema, so description fully explains 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 covers all 3 parameters (100%). Description provides useful context: explains market parameter types, depth enumeration (quick/thorough), include_raw purpose. Adds examples and extra semantics beyond schema.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and what it returns (evidence packet, comparison). Distinguishes from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says when to use: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z'. Does not explicitly mention when not to use or alternatives, but context from siblings provides some distinction.

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 behavior. Description adds specifics: sorting by primary metric, handling off-calendar fiscal years, returning paired data and citation URIs. This adds value beyond annotations but could detail pagination or limits.

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

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

The description is detailed and front-loaded with key trigger phrases. While dense, every sentence contributes value. Slightly long but acceptable for the 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?

Given the tool's complexity, no output schema, and annotations present, the description fully explains behavior, return format, and constraints, enabling correct invocation. It covers all necessary contextual aspects.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches parameter meaning: explains 'company' pulls SEC data with fiscal year handling, 'drug' pulls regulatory data, and max 5 items per array.

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

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

The description clearly identifies the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It uses trigger phrases like 'compare X and Y' and specifies what each entity type retrieves, distinguishing it from single-entity tools.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also notes it replaces 8-15 sequential lookups, reinforcing efficiency.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses extensive behavioral details: decomposition into facets, parallel routing to 5,529 tools, return format (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, 'never invented' policy, contradictions[] for standard/thorough, hop fields, semantic excerpting, latency expectations, and depth-dependent behavior. This goes far beyond the annotations, enriching the agent's understanding of what happens when the tool is invoked.

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 dense paragraph, but every sentence adds necessary information. It is front-loaded with the account requirement and fallback, then explains core behavior, use cases, depth variations, citations, and latency. It could be better structured with paragraphs or bullet points for readability, but the length is justified given the tool's complexity and the absence of an output schema.

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 the return values: a findings packet with evidence, confidence, source, fetched_at, stable pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers account prerequisites, depth behavior, latency, and semantic excerpting. The tool is complex with 2 parameters and rich behavior, and this description leaves no critical aspect unexplained.

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%, providing a baseline of 3. The description adds extra semantics beyond the schema: it notes that depth:'thorough' requires a paid plan, clarifies that 'quick' is single-hop while 'standard' and 'thorough' include gap recovery and contradiction scans, and gives additional context about latency (15-60s, thorough up to ~90s). While the schema already covers the meaning of each parameter, the description enhances it with operational constraints and expectations, pushing it above baseline.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It names a specific verb (research), the resource (1455 structured data sources), and distinguishes it from siblings (ask_pipeworx for single lookups, open-web search). This immediately differentiates it from the alternative tools in the sibling list.

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: 'Best for broad/multi-part questions over structured data' and direct exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also explains when not to use it (if not signed in) and names the fallback tool (ask_pipeworx). This leaves no ambiguity about when to select this tool over 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=true, idempotentHint=true, and destructiveHint=false. The description adds beyond this by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' 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 concise at three sentences, front-loading purpose and usage. It efficiently covers the tool's function, when to use it, and what it returns. Every sentence adds value, though it could be slightly tighter by removing the list of domains.

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 (no output schema, straightforward input), the description provides sufficient context: return format, parameter aliases, and usage guidance. It could mention the default limit explicitly, but overall it is complete for a discovery 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 6 parameters described in the schema. The description adds context about query aliases and provides example queries ('look up FDA drug approvals', 'analyze housing market trends'), but this is marginal value beyond the schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific data domains (SEC filings, FDA drugs, etc.), making it distinct from sibling tools that target individual domains. As a meta-discovery tool, it differentiates itself effectively.

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

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

The description includes explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context for when to use the tool, though it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds detail: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), lists returned data, and notes that USPTO patents API may sunset May 2025 and soft-fails. 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 fairly long but front-loaded with example intents and every sentence adds value. Could be slightly more concise, but informative and well-structured.

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

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

Given the tool's complexity (multiple data sources), the description provides a comprehensive overview of what is returned (cik, filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail, only companies). No output schema needed because description covers it thoroughly.

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 repeats parameter descriptions (ticker or CIK, names not supported) but adds slight extra context about zero-padded CIK. Not enough to elevate above baseline.

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

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

The description clearly states it provides a full cross-source profile of US public companies, with explicit examples of user intents like 'tell me about X' or 'brief me on Tesla'. It distinguishes itself from sibling tool resolve_entity by noting that names are not supported.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed, and instructs to use resolve_entity first if only a name is available. This gives clear when-to-use 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 declare destructiveHint=true and idempotentHint=true. Description confirms deletion by key but adds no extra behavioral detail. No contradiction.

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

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

Two sentences: first states purpose, second provides usage guidelines. 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?

Simple tool with one parameter and no output schema. Annotations cover safety. Description adds pairing guidance, fully sufficient.

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

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

Schema has 100% coverage with description 'Memory key to delete'. Description repeats 'by key' without adding new meaning. Baseline 3 acceptable.

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' – specific verb and resource. Distinguishes from siblings 'remember' (store) and 'recall' (retrieve).

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

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

Explicitly lists three scenarios (stale context, task done, clear sensitive data) and names complementary tools. Lacks explicit when-not-to-use, but guidance is strong.

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 valuable procedural detail (fetches page, extracts specific elements, outputs standard markdown) that goes beyond annotations, clarifying the tool's operation without contradiction.

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

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

The description is concise, front-loading the core purpose in the first sentence, and every subsequent sentence adds value (process, output, use cases). No unnecessary words.

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

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

For a simple two-parameter tool with no output schema, the description sufficiently explains the output ('single text blob ready to drop at site-root/llms.txt') and the extraction logic, covering all essential aspects without 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%, with both 'url' and 'max_links' already documented. The description adds no new semantic information beyond what is in the schema, achieving the baseline for high-coverage cases.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, explaining the process (fetches page, extracts title/description/key links) and output format. It is specific and distinct from sibling tools, none of which produce llms.txt files.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing crawler view. It implies context but does not state when to avoid using the tool or mention alternatives, though no direct alternatives exist among siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it returns specific fields and that include_inactive controls inclusion of cancelled subscriptions, adding context beyond annotations.

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

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

Two sentences: first states purpose and output, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

Despite having no output schema, the description explicitly lists all output fields. Given low complexity (1 optional parameter) and good annotations, the description is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with a clear description of the single parameter (include_inactive). Description does not add extra detail about the parameter, but schema already provides sufficient meaning. 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 'List the caller's active subscriptions' with specific verb and resource, and lists returned fields (id, type, etc.). It distinguishes from siblings like subscribe and unsubscribe.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. Does not mention when not to use, but the alternatives are clear from sibling names.

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

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

Beyond the false annotations, the description discloses key behaviors: filing returns a claim_token for later status checks, rate limiting ('5 per identifier per day'), cost/free status, and that the team reads digests daily. It also explains the consequence of misreporting other servers ('only delays you').

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?

Although the description is relatively long, every sentence provides distinct, actionable value: purpose, use cases, exclusion, phrasing, token mechanics, team review, and rate limit. It is front-loaded with the core purpose and maintains a logical structure.

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

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

Given the tool has no output schema, the description compensates by explaining what is returned (claim_token) and how to use it for later resolution. It also covers rate limits and the fact that it doesn't count against tool-call quota, making it complete for a feedback/reporting 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?

While the schema already documents all parameters at 100% coverage, the description adds crucial meaning: it explains the claim_token round-trip flow with the example `pipeworx_feedback({claim_token:"pwfb_…"})`, and gives guidance on the message parameter (describe in terms of tools/packs, not end-user prompts).

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 a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from siblings by positioning itself as the feedback channel for Pipeworx tools and explicitly excludes feedback for other MCP servers.

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

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

The description gives explicit when-to-use scenarios (bug, feature/data_gap, praise) and when-not-to-use ('if the tool came from a different MCP server... file it with that server instead'). It also provides phrasing guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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 valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h depending on window), and self-aggregating nature.

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: two main sentences plus a bulleted list of use cases. It is front-loaded with the core functionality and uses no superfluous 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 parameter (one optional enum), no output schema, and comprehensive annotations, the description covers everything needed: what it returns, how it works, and why it's useful.

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 description adds meaning to the single parameter 'window' beyond the schema's enum description, explaining that shorter windows surface current trends while longer windows show steady-state demand.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a recent window, with three explicit use cases. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by focusing on trending 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 provides explicit when-to-use scenarios (discovering hot data sources, confirming canonical choice, seeing alignment) but does not mention when not to use it or direct alternatives among siblings.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: semantic anchor (Jaccard similarity), partition filter (placeholder slugs dropped), fill check against live CLOB depth, and realizable vs theoretical edge. No contradictions with annotations.

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

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

The description is well-structured with clear sections (modes, semantic anchor, partition filter, fill check) and uses punctuation effectively. It is somewhat lengthy but every sentence adds value. 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?

The tool has no output schema, so the description must explain return values. It does so clearly: opportunities[] with fields, and in event mode partition_check object. It also covers edge cases like fill check and custom sizing. Comprehensive 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 both parameters having descriptions. However, the tool description adds significant meaning: acceptable formats for event slug, full URLs accepted, explanation of topic mode as seed question. This goes well beyond the schema.

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

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

The description clearly defines the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (trending_scan, event, topic) and explains what each does. This clearly separates it from sibling tools like polymarket_edges or polymarket_edge_tracker.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, 'event' for specific event, 'topic' for cross-event scanning. It explains the recommended use case for event mode. However, it does not explicitly compare to sibling tools or state when not to use this tool, though the context is implied.

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 annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing the three response segments, the meaning of edge_pp_net and kelly_fraction, the tradeable-edge knobs, the caching policy ('Cached 1h at the KV level keyed on all knobs'), and the diagnostic output. It fully discloses the behavioral traits of the tool.

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

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

The description is very detailed and well-structured with clear sections (segments, opportunity fields, knobs, response top-level), but it is quite long. While front-loaded with the core purpose, the length may reduce conciseness. Every sentence adds value, but it could be more compact.

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

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

The description covers all critical aspects of the tool: the three model families, response structure (by_segment, fed_candidates, diagnostics), edge fields, parameter details, and caching behavior. Given no output schema, the description fully defines what the agent can expect, making it complete for a complex tool.

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

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

The input schema already has 100% coverage with detailed descriptions for all 9 parameters. The tool's description adds further context, such as explaining min_liquidity and max_spread_pp as 'tradeable-edge filters' and clarifying the behavior of min_partition_leg_kelly. While the schema does the heavy lifting, the description enhances understanding of the parameter roles.

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 specifically targets the use case 'what should I bet on today' and distinguishes from potential siblings by detailing its unique approach with five model families and a diagnostic output.

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

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

The description provides a clear context for when to use the tool ('agents discover opportunities without paging hundreds of markets'), but it does not explicitly compare with sibling tools such as polymarket_arbitrage or polymarket_edge_tracker. No guidance on when not to use or alternatives is given.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds context: data comes from daily snapshots, has a 60-day TTL, and decay is computed from daily closes (not intraday). It also details the response structure (tracked, expired, snapshot_dates). This adds significant behavioral clarity 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 longer than average but well-organized: it starts with the core purpose, then explains output format, and ends with limitations. Every sentence adds value, though some could be trimmed. It is front-loaded with the most important information.

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

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

Given there is no output schema, the description compensates by thoroughly explaining the response structure (tracked, expired, snapshot_dates arrays with their fields). It also covers limitations like TTL and decay computation. For a tool with two optional parameters, this is 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?

The input schema already covers both parameters with descriptions (100% coverage). The description adds minor extra context: default values (days=14, window='1wk') and explains that 'window' refers to snapshot family. This is helpful but the schema already provides adequate meaning.

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

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

The description clearly states it provides edge persistence and decay telemetry, answering the specific question of how long an edge has existed and whether it is shrinking. It distinguishes itself from the sibling 'polymarket_edges' by focusing on historical time-series analysis rather than just current edges.

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

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

The description implicitly tells when to use this tool (to evaluate edge persistence vs. recency) by contrasting 'fresh wide edge' with '3-week-old wide edge'. It does not explicitly state when not to use it or list direct alternatives, but the contrast provides adequate 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 non-destructive. Description adds rich behavioral details: walks the ladder, returns verdict (clean|degraded|cannot_fill), explains basket mechanics, per-leg fill detail, and forced_directional_risk. No contradictions with annotations; description significantly augments 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?

Description is long but well-structured: begins with core purpose and requirements, then splits into single-market and basket sections. Every sentence is informative. Could be slightly more concise, but 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?

High tool complexity with two modes and no output schema. Description compensates by detailing output fields for both modes, including warnings about partial fills and directional risk. Covers all necessary contextual information for correct agent invocation.

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

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

Schema description coverage is 100% (baseline 3). Description adds meaning: explains size_usd as 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. Clarifies side default behavior in basket mode ('auto from partition sum'). Adds value beyond schema.

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

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

Description states a specific verb+resource: 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It clearly distinguishes between single-market and basket modes, and uses precise terms like 'top_of_book', 'vwap_fill_price', 'slippage_pp', etc. The tool is differentiated from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why alternative approaches fail ('theoretical overround on thin books is not capturable', 'partial basket fills convert an arb into an unhedged directional position'), providing strong 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 declare read-only, idempotent, non-destructive. The description adds extensive behavioral context: compatibility_warning cases, temporal_alignment, skipped_cross fields, and the caveat that most pre-mapped topics return warnings today. No contradiction.

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

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

The description is long but well-structured with clear sections (purpose, modes, response, safety fields). Every sentence adds important information, though it is somewhat dense for quick parsing.

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

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

Despite no output schema, the description thoroughly explains the response structure (venue prices, spreads, compatibility_warning, temporal_alignment, skipped counters) and handles edge cases. It is complete for a complex cross-venue 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?

Input schema has 100% coverage with descriptions for each parameter. The description adds value by explaining the two modes, listing pre-mapped topics, and describing how explicit parameters override topic-mapped sides. Example usage is provided.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools (Polymarket-only or arbitrage). It also explains two modes and the response structure.

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

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

The description explicitly explains when to use the tool (to compare prices across venues) and warns about scenarios where spreads are not meaningful via compatibility_warning and temporal_alignment. It does not explicitly name alternatives but provides enough context for appropriate 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 provide readOnlyHint, destructiveHint, idempotentHint. Description adds scoping to identifier, listing behavior when key omitted, and context-lookup purpose, which are valuable 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?

Three sentences, front-loaded with action, no waste. Every sentence adds meaningful information about usage, pairing, and scoping.

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

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

Given one optional parameter, no output schema, and rich annotations, the description fully covers retrieval and listing, scoping, and pairing with sibling tools. 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 coverage is 100% with one parameter. Description adds the key nuance: omit to list all keys, which complements the schema. No extra syntax but sufficient.

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 saved value or lists all keys, with specific verb and resource. It distinguishes from sibling tools like remember and forget by naming them and explaining pairing.

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

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

Explicitly advises when to use: to look up context stored earlier without re-deriving it. Mentions scoping and pairs with remember/forget, providing clear guidance on 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 signal read-only, idempotent, non-destructive. Description adds that mark_read:true flags events as read for next call. Also describes return fields (source, citation_uri, payload). No contradictions.

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

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

Three sentences: purpose, return details, filtering/behavior, plus alternative access. Front-loaded with purpose. 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?

No output schema, but description covers return values. All parameters explained. Includes behavioral nuance (mark_read). Mentions alternative endpoint for scripts. Comprehensive for a list/read 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 covers 100% of parameters. Description adds practical meaning: examples of type values ('sec_8k'), ISO timestamp for since, effect of mark_read on future calls. Enhances 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 it 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. Specific verb and resource. Distinct from sibling tools like list_subscriptions.

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

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

Provides guidance on filtering (type, since), mark_read for incremental reads, and mentions polling works fine. Also notes alternative HTTP endpoint. No explicit when-not-to-use, but 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 declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds significant behavioral context: fans out to multiple sources in parallel, fallback from GDELT to GNews, soft-fail for USPTO, and describes output format (changes grouped by source, total_changes, pipeworx:// URIs). No contradictions noted.

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

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

The description is structured with front-loaded example queries, then details on sources, parameters, and output. Every sentence adds value; there is no redundancy or filler. It efficiently conveys 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 the complexity (multiple data sources, fallback logic, output format) and lack of output schema, the description thoroughly covers behavior and return structure. It also correctly contextualizes the tool among siblings by pointing to entity_profile for static 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%. The description elaborates on each parameter: 'type' explains it's only 'company', 'since' gives ISO date and relative shorthand examples ('7d', '30d', '3m', '1y') with recommendation ('Use 30d or 1m for typical monitoring'), and 'value' explains ticker or zero-padded CIK. This adds meaning beyond the schema.

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

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

The description explicitly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It gives example queries like 'latest on Y' and lists sources (SEC EDGAR, GDELT/GNews, USPTO), clearly distinguishing from sibling 'entity_profile' by directing users to use that 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?

The description provides explicit usage guidance with natural language examples ('What's new with X', 'updates on Acme') and specifies when not to use it: 'Use entity_profile instead when you want the static profile...' This clearly differentiates between the two tools.

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

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

Annotations indicate write operation (readOnlyHint=false), idempotent (idempotentHint=true), non-destructive. Description adds key details: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. Does not contradict annotations.

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

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

Four sentences, each earning its place. Front-loaded with purpose, then usage, then persistence details. No fluff or repetition.

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

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

Given simple schema (2 required params, no output schema), annotations cover behavior, and description adds persistence scope, the description is fully complete for an agent to understand and use correctly.

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

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

Schema has 100% coverage with clear key and value descriptions. Description adds value with examples like 'subject_property', 'target_ticker' and explains value as 'any text — findings, addresses, preferences, notes', going beyond schema.

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

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

The description clearly states the tool saves data for later reuse across conversations or sessions, using verbs like 'save' and 'reuse'. It distinguishes itself from siblings recall and forget by mentioning them directly.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward' (e.g., resolved ticker, user preference). Also mentions pairing with recall and forget, providing clear context for usage.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safety. The description adds substantial behavioral detail: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), cascading internal lookups, explicit labeling of unresolved identifiers ('stated explicitly under `unresolved` rather than omitted'), and source attribution for each identifier. This goes well 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 long but information-dense. It front-loads with concrete example queries and a clear purpose statement, then adds behavioral nuances. While a more structured layout (e.g., bullet points for supported types) might improve scannability, every sentence earns its place 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?

For a tool handling multiple entity types and external data sources, the description is remarkably complete. It specifies the data sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), the fields returned (CIK, ticker, LEI, FIGI, RxCUI, etc.), fallback behavior, and even the citation format for drugs. Despite lacking an output schema, an agent has a clear picture of what will come back.

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 schema descriptions for 'type' and 'value' already explain acceptable inputs. The description echoes this (e.g., 'accepts ticker, CIK, or company name as input') but does not add new syntax or format details beyond what the schema provides. It does offer contextual examples, which is marginal value over baseline.

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

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

The description opens with concrete query examples ('What's the ticker for…', 'find the CIK for…'), then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly identifies the verb (resolve), the resource (entity names to IDs), and its role relative to sibling tools ('other tools require as input'). This distinguishes it from related tools like entity_profile 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 gives an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also notes the efficiency advantage ('replaces 2-3 manual lookups'), helping an agent know when to prefer this tool. However, it does not name specific alternative tools or state exclusions (e.g., 'if you already have an ID, use entity_profile'), so it lacks a fully explicit when-not-to-use comparator.

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 return format ('ranked list with score, confidence, signal density per entity') and mentions probing with ai_visibility_check, providing useful 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?

Four efficient sentences, front-loaded with main action, each sentence adds value with no redundancy.

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

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

Despite no output schema, description fully explains output (ranked list with score, confidence, signal density) and provides a concrete example. Covers all needed context for a multi-entity comparison tool.

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

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

Schema already describes all 4 parameters with descriptions. Description adds that the first entity is treated as 'subject' for narrative and that _apiKey is optional unless using anthropic model, adding meaningful context.

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

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

The description clearly states the verb 'compare' and the resource 'AI visibility across multiple entities'. It distinguishes from sibling tool 'ai_visibility_check' by specifying side-by-side comparison and ranking.

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

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

Provides explicit use case ('competitive AI-marketing audits') and implies when to use instead of single-entity check. Does not explicitly state alternatives or when not to use, but sibling context provides clarity.

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), the description discloses graceful partial failures and potential delays (5-30s for bundlephobia first measurement), adding critical 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 somewhat lengthy but efficient, front-loading the composite nature and fans-out. Every sentence contributes essential information, though minor trimming might be possible.

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 (multiple data sources, no output schema), the description fully covers purpose, return fields, behavior (delays, partial failures), ecosystem boundaries, and parameter details, making it complete.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by explaining defaults (version defaults to latest) and acceptance of scoped packages, though it does not significantly expand beyond schema.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, fans out across deps.dev and bundlephobia, and returns a detailed summary. It distinguishes from siblings by specifying the npm ecosystem focus.

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

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

Explicitly states when to use the tool (e.g., 'is X safe / popular / small') and provides guidance on alternatives (PyPI, Maven, etc. fall under deps.dev:version directly).

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

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

Annotations already cover safety and idempotency, but the description adds critical details: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and offset for verification. This goes well beyond annotations.

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

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

Single paragraph, front-loaded with purpose, then usage guidance, then technical details. Every sentence adds value. Slightly verbose but not excessive.

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?

Missing output schema is partially compensated by describing return contents (passages, offsets, scores). Given good annotations and clear param descriptions, the description is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds concrete examples ('supply-chain risk', etc.) and clarifies constraints (max ~200K chars for 'text', range 1-20 for 'limit', default 5). This adds meaningful context.

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

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

The description clearly states it performs 'Semantic search INSIDE a fetched record', specifies the inputs (text + query) and outputs (passages with offsets and scores). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and use case for large records.

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 the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded, providing clear when-to-use and an alternative.

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

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

Discloses important behaviors: webhook secret returned once, auto-disabling after 10 failures, SMS 10/day cap, and phone verification requirement. Annotations already indicate mutability; description adds concrete constraints.

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

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

Front-loaded with purpose, every sentence adds value despite length. Could be slightly tighter but no unnecessary words.

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

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

Given the complexity (nested objects, multiple types, delivery options, no output schema), the description covers return value, prerequisites, type-specific parameters, error conditions, and channel details comprehensively.

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 concrete examples for each type's params, clarifying nested object structures beyond the schema's generic descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID, distinguishing it from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides explicit prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel options. However, it does not explicitly state when not to use this tool versus alternatives like 'recent_alerts'.

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

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

Beyond annotations (readOnly, idempotent, not destructive), description adds behavioral details: returns categorized examples, optional topic focusing, and that it draws from live tool 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?

Front-loaded with common user queries, but the description is longer than necessary. Every sentence adds value, but could be tightened.

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 discovery tool with one optional parameter and no output schema, the description fully covers what the tool does, when to use it, and how to use the parameter.

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 single optional parameter with description. Description adds practical examples of topic values and explains that omitting gives full spread, adding value.

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

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

Description uses specific verbs 'returns category-bucketed example questions' and clearly states the resource (onboarding entry point). Distinguishes from siblings like ask_pipeworx by targeting discovery use case.

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: 'Use this FIRST when you do not yet know what Pipeworx can do'. Context of when to call is clear, though no exclusion cases are mentioned.

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

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

Beyond annotations (destructiveHint=false, idempotentHint=true), description adds key behavioral context: deactivation not deletion, ownership enforcement, and historical data persistence. 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?

Two sentences covering purpose, ownership, and effect. Front-loaded with action and resource. 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 single-parameter tool with good annotations, description fully covers safety (non-destructive), ownership, and consequences (history retained). 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 already describes the id parameter well, but description reinforces its origin ('returned by subscribe') and usage ('by id'), adding value beyond schema.

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

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

Description clearly states the action (cancel/unsubscribe) and resource (subscription by id). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying ownership enforcement and deactivation behavior.

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

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

States ownership enforcement and that the action is for own subscriptions only. Mentions non-destructive deactivation, but does not explicitly list when not to use or provide direct sibling comparisons.

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, the description adds crucial behavioral context: the dual pipeline (SEC EDGAR fast path vs. grounded pipeline), the full verdict set, the requirement not to treat could_not_verify as evidence, and the meaning of unsupported. This is essential for a caller to correctly interpret results and goes far 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 dense but well-structured: trigger phrases, use case, pipeline distinction, output shape, error semantics, and efficiency benefit each earn their place. It is front-loaded with the purpose and maintains conciseness while covering all essential aspects.

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 a complex tool with no output schema, the description fully covers the return structure (verdicts, citation, reasoning) and clarifies the critical failure modes (could_not_verify and unsupported). It also explains the two processing paths, giving the agent sufficient information to invoke the tool and interpret results correctly.

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

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

Schema description coverage is 100%, so the schema already fully explains both parameters (claim and tolerance_pct). The description adds domain context about financial vs. other claims, which indirectly relates to claim processing, but it does not enrich the parameter syntax or semantics beyond what the schema already provides.

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

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

The description states a specific verb ('verify') and resource ('natural-language factual claim'), explicitly defining the tool as 'claim verification against authoritative sources.' It also distinguishes from siblings by emphasizing the verdict-based output and the scope (checking truth of user statements), setting it apart from generic research or Q&A 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 gives clear when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and clarifies the interpretation of special verdicts like could_not_verify and unsupported. However, it does not name specific alternative tools or state explicit when-not-to-use conditions, so it falls short of full exclusion guidance.

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