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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it routes questions internally, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and handles live news via feeds. It does not mention rate limits or failure modes, but the annotation coverage lowers the burden and the added detail is genuinely useful.

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 dense and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). It covers scope, examples, routing guidance, and sibling escalation. There is minor redundancy (the preference over web search is repeated in the opening and near the end), so it is not maximally concise, but every section 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?

For a complex routing tool with no output schema, the description covers all key aspects: what it does, what kinds of questions to use it for, what it returns (structured answer with citation URIs), when to choose alternatives, and illustrative examples. An agent has enough information to invoke it correctly and set expectations about the response.

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 does not add parameter-level syntax but embeds multiple natural-language examples ('current US unemployment rate', 'Apple's latest 10-K', 'active clinical trials for GLP-1') that clarify the expected format of the question parameter, which exceeds the baseline.

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

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

The description clearly states a specific purpose: answering factual questions about real-world entities by routing them to one of 5,743 tools across 1,500 verified sources and returning structured answers with citation URIs. It explicitly distinguishes itself from web search and from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them 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?

The description gives explicit when-to-use signals ('Use whenever the user asks what is...') and names concrete alternatives with trigger conditions ('Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also declares itself the default entry point ('START HERE'), which fully resolves the routing decision.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable runtime context: no candidate is currently active, it 'currently matches ask_pipeworx exactly,' and candidate improvements are enabled live when under test. This goes beyond the structured 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 few sentences and front-loads the key fact that this is a beta version of ask_pipeworx. It packs in current status, usage direction, and comparison behavior without excessive padding, though the final 'experimental edge' phrasing is slightly embellished.

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 router tool with no output schema, the description explains the relationship to ask_pipeworx, the current inactive candidate state, the expected usage pattern, and the evaluation purpose. An agent has enough context to invoke it correctly, and the response shape is defined by reference to ask_pipeworx.

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 coverage is 100% and every parameter is fully described as an alias for 'question.' The description only says 'same arguments' without adding new parameter details, so the schema carries the full semantic burden. 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 opens with 'Beta version of ask_pipeworx' and clearly identifies this as a universal router with 'the same 5,743 tools, same arguments, same response shape.' It distinguishes itself from the stable ask_pipeworx by emphasizing the experimental routing improvements.

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 a clear condition for selection. It also states that results are compared against the stable router to decide merges, implying the stable version is the alternative, though it stops short of explicit when-not-to-use guidance.

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

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

Beyond the annotations' readOnly/openWorld/idempotent hints, the description reveals the full behavioral contract: the return shape on success, the explicit refusal object with enumerated refusal_reason values, and the 'using ONLY what the tool result contains' guarantee. It also discloses the extra LLM call cost. Nothing here contradicts 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 information-dense but every sentence earns its place: it states the mode, the routing mechanism, the guarantee, the return contract, the use cases, and the cost tradeoff. It is front-loaded with the most decision-relevant trait and uses compact examples like the refusal enum list rather than wandering prose.

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 of this complexity and with no output schema, the description is unusually complete: it covers routing, grounding behavior, success and failure return shapes, refusal reasons, cost, and selection context. The annotations handle the safety profile, and the schema handles parameters, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema itself fully documents the aliases and the natural-language 'question' parameter. The description adds no new parameter-level semantics beyond what the schema already provides, so the 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 opens with a specific function — 'Hallucination-resistant answer mode for high-stakes reads' — and explains exactly what differentiates it from the sibling ask_pipeworx: it routes the same way but extracts the answer using only the tool result. It names the sibling directly and states the edge the grounded mode provides, so an agent can distinguish them without opening the schema.

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 and when-not-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains, then 'prefer ask_pipeworx for casual lookups.' It also transparently mentions the cost tradeoff ('Costs one extra LLM call'), which is exactly the kind of selection criterion an agent needs.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing auth/pricing constraints, parallel decomposition across 5,743 tools, the findings packet (evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, contradictions[], semantic excerpting, hop behavior, and latency. 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?

Dense but front-loaded: the auth gate and fallback appear before the core behavior. It is long for a two-parameter tool, but the complexity of the tool justifies most of the content; slight trimming would make it tighter.

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

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

Complete for a tool with no output schema: an agent knows when to use it, what it returns, how gaps are handled, whether citations are resolvable, and how long to wait. Nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real nuance by explaining what makes good questions, depth pricing, gap-recovery hops, and latency—but much of the depth semantics are already present in the schema's enum 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?

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources'. Explicitly differentiates itself with 'this is NOT open-web search' and names sibling tools ask_pipeworx and the news packs.

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?

Gives explicit selection rules: use for broad/multi-part structured questions; 'For a single lookup use ask_pipeworx'; prefer ask_pipeworx for breaking/current-news topics. Also provides fallback guidance for signed-out users and depth-level timing expectations.

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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses fan-out across multiple sources, source-specific soft-fail behavior (USPTO sunset, GDELT→GNews fallback), the meaning of sources_used/sources_failed, and that an empty FDA section is expected rather than a bug. It also explains resolved:false behavior for private companies.

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 definition is long and dense, but it is front-loaded with intent and examples, and every clause carries operational meaning (source list, return fields, failure semantics, input normalization). It structures the return contract inline rather than relying on an output schema, so the length is largely justified, though it could be broken into clearer sections.

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 defines the return shape (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed) and explains edge cases like empty source sections and private-company resolution. The agent has everything needed to call the tool and interpret its response correctly.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds value by giving concrete examples ('AAPL', '0000320193', 'Moderna'), explaining name resolution via SEC EDGAR, the resolved_from/resolved_to fields, and the private-company resolved:false behavior — all useful 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 leads with concrete user utterances and states the core operation: 'full cross-source profile of a US public company in ONE parallel call.' It further disambiguates from alternative approaches by explicitly preferring this tool over chaining single-pack SEC/XBRL/news lookups for holistic requests.

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 an explicit condition ('when the user asks for a holistic view') plus a clear directive ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'). It also tells the agent what input shapes are accepted and how private companies are handled, so routing and failure behavior are 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 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?

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing the matcher's limitations, compatibility codes, skipped-leg behavior, gross-vs-net fee treatment, and the precise meaning of temporal_alignment unknowns. It also explains that pairings are keyword-based and never fully verified, which is exactly the kind of behavioral caveat an agent needs. No contradiction with annotations exists.

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

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

The description is long, but it is organized into functional sections (modes, response, safety fields, codes, skipped comparisons, fees) and nearly every sentence carries operational meaning. It front-loads the core purpose and mode distinction, and the length is largely justified by the lack of an output schema and the complexity of the compatibility semantics.

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 must carry the full burden of explaining return values, edge cases, failure flags, and interpretation guidance, and it does so thoroughly. It covers response structure, compatibility_codes, per-pair flags, skipped/unclassified legs, temporal alignment nuances, fee treatment, and practical tradeability caveats. An agent can invoke this tool and interpret its output correctly without needing additional context.

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

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

Schema coverage is 100%, so the schema already documents each parameter, but the description adds valuable semantics: topic is a pre-mapped shortcut with an explicit list, kalshi_event_ticker and polymarket_event_slug override the mapped side, and both modes run the same matcher. This enriches the parameters beyond simple type/description information, justifying a score above the baseline.

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

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

The description states a specific purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes the tool from its siblings by emphasizing the two-venue comparison and the token-overlap matching approach, and it clearly enumerates the two modes (topic shortcut vs explicit ticker/slug). This is far more specific than merely restating the title.

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 usage context: when to use topic shortcuts vs explicit event identifiers, and it warns that pre-mapped topics often return compatibility warnings and are not necessarily tradeable. It does not explicitly name sibling alternatives like polymarket_arbitrage or polymarket_edges, so it falls just short of fully explicit when-to-use-versus-alternatives guidance, but the mode-level 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 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 already establish read-only, idempotent, non-destructive behavior. The description adds substantial detail beyond annotations: cross-source resolution via EDGAR, GLEIF, and OpenFIGI; graceful degradation when enrichment source is unavailable; explicit `unresolved` output; `figi_candidates` ambiguity handling; and internal endpoint cascading. 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 strongly front-loaded and information-dense, with the use-first guidance up front. However, the supported-types section is a long near run-on block with deeply nested parentheticals, making it harder to parse. Every sentence earns its place, but the structure could be clearer.

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

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

For a tool with no output schema, the description carries the full burden and succeeds: it covers input variants, supported entity types, edge cases like ambiguous bond issuers, unresolved identifiers, enrichment failure degradation, and why this tool replaces multiple manual lookups. An agent has enough context to decide when and how to call it.

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

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

Schema coverage is 100%, but the description adds meaning well beyond it: value must be the entity name only, not a noun phrase; bond issuers should be passed exactly as printed with a concrete warning about trailing security-class words; it gives ticker/CIK/ISIN examples for company and brand/generic examples for drug. This materially improves correct invocation.

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

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

The description clearly states the tool resolves a user-spoken name into canonical/official identifiers that other tools require as input, using verbs like 'resolve' and 'look up.' It lists concrete example queries and distinguishes itself from likely siblings such as entity_profile by focusing on identifier resolution across company and drug types.

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 an explicit directive: 'Use FIRST whenever you have a name but need an ID,' and enumerates the two supported types with examples. It stops short of naming sibling alternatives or giving explicit when-not-to-use guidance, but the context for use is crisp and immediately actionable.

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.