Anapioficeandfire

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

The description adds valuable context beyond the readOnlyHint/openWorldHint/idempotentHint annotations by specifying the default model (Workers AI Llama-3.3-70b, free), the BYO-key cost implication for Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This helps the agent anticipate cost and output shape. It doesn't discuss rate limits or error cases, so it's strong but not maximal.

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, tightly packed with the essential API behavior: what it does, default vs. optional model, return shape, and typical use cases. There is no filler or redundant repetition of schema details, making it easy to scan and immediately act on.

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 moderate complexity (4 params, no output schema), the description provides a complete mental model: one required entity param, optional models/key/context, and a clear return shape. It also states the practical purpose, covering both invocation and interpretation. Missing details like enum values or error handling are not necessary because the schema already covers constraints.

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

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

The schema already documents all 4 parameters with clear descriptions, achieving 100% coverage, so the description doesn't need to repeat them. The description adds a small hint about _apiKey ('BYO key') and the default model, but the schema already captures the key semantics (e.g., _apiKey 'only needed if anthropic is in models'). Thus, the description contributes marginal additional meaning beyond the schema, which is the baseline for full schema coverage.

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

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

The description uses a specific verb+resource: 'Probe one or more LLMs for what they know' and explicitly defines the output as a visibility score (0-100). This clearly distinguishes it from sibling tools like ask_pipeworx (likely conversational Q&A) and deep_research by focusing on scoring business/brand visibility rather than general Q&A or deep research.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the default Workers AI model versus passing `_apiKey` to probe Anthropic, giving clear context on model selection. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it lacks direct exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it routes to the right tool, fills arguments, returns structured answers with stable citation URIs, and works on every tier with one fast call. No contradictions detected.

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-front-loaded with the critical guidance ('PREFER OVER WEB SEARCH') and immediately clarifies scope. It includes examples and routing rules, but some redundancy exists (e.g., repeated mention of 'question' and citation URIs). It earns a 4 for thoroughness without being bloated.

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

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

Despite no output schema, the description explains what the tool returns (structured answer with citation URIs), when to use it, when to use alternatives, and provides concrete examples. It also covers edge cases like breaking news. For a tool of this complexity, nothing essential is missing for an agent to invoke it 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%, and all six parameters are aliases for 'question', which the schema already documents fully. The tool description adds no new parameter-level semantics beyond what the schema provides; it only implies that the question is a natural-language request. 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: routes questions to over 5,708 tools across 1,494 verified sources and returns structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and the examples ('current US unemployment rate', 'Apple's latest 10-K') make the scope concrete.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives and conditions. It also lists trigger phrases ('what is', 'look up', 'find'). This is exemplary usage guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive traits. The description adds valuable context about its live experimental status, the lack of an active candidate, and that it is a full working router rather than a fallback. This exceeds the minimal annotation coverage without contradicting it.

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 five sentences and each sentence delivers meaningful context: beta status, identity, current state, usage instruction, and verification role. It is slightly dense but front-loaded with the most critical distinction (beta of ask_pipeworx) and avoids redundancy.

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

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

Given the tool's complexity as a router with 5,708 tools and no output schema, the description covers essential operational details: current behavior (matches ask_pipeworx), relationship to the stable version, and expected usage. The absence of an output schema is mitigated by the reference to the same response shape as ask_pipeworx, making the description complete for 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 coverage is 100%, with the schema fully describing all six parameters (question and five aliases). The description only mentions 'same arguments', which adds no new meaning; the schema does the heavy lifting, matching the baseline of 3.

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

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

The description immediately identifies the tool as a beta version of ask_pipeworx, a universal router, and specifies that it has the same 5,708 tools, arguments, and response shape. It differentiates itself from the stable sibling by its experimental routing improvements, making the purpose clear and distinct.

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, and explains that results are compared against the stable router. It also notes that no candidate is currently active, so it currently matches ask_pipeworx, helping the agent decide when this variant is appropriate.

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 annotations (readOnly, openWorld, idempotent) by detailing the return shape on success, the structured refusal reasons on failure, and the principle of extracting answers only from the tool result. It also discloses the extra LLM call cost, which the agent can factor into decisions.

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

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

The description is dense but every sentence earns its place: it opens with the core value proposition, explains the mechanism, spells out return and refusal formats, gives use cases, and closes with the cost tradeoff. It is well-structured and front-loaded without padding.

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 absence of an output schema, the description fully covers what an agent needs: purpose, routing behavior, success return fields, refusal reasons, usage timing, and cost comparison with the sibling. No critical detail is missing for correct 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 coverage is 100% with all parameters documented as aliases for the 'question' field. The description adds no new parameter-level meaning, but none is needed since the schema already fully explains the input. 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 a 'hallucination-resistant answer mode for high-stakes reads' and explains its behavior: it routes to the right tool, fetches data, then extracts the answer using only the tool result. It explicitly distinguishes itself from the sibling ask_pipeworx by noting it is the same routing but with extraction and refusal semantics.

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 it whenever an answer will be quoted, cited, or acted on and the agent must not invent facts. It also names the alternative ask_pipeworx and states the tradeoff ('costs one extra LLM call'), advising to prefer ask_pipeworx for casual lookups.

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

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

The description extensively discloses behavior beyond annotations: it explains low-confidence short-circuiting, closed-market handling, wide-spread tradeability flags, news fallback mechanisms, cancellation-rule risk, and resolver match confidence. These are non-obvious behaviors that significantly affect how an agent should interpret results and size bets. 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 long but extremely well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.). The core purpose and usage are front-loaded in the first two sentences. While dense, each section adds necessary detail for a complex tool; only minimal redundancy exists.

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

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

Given the tool's complexity (multiple classifiers, fan-out behaviors, response shapes, safety mechanisms) and the absence of an output schema, the description is remarkably complete. It covers return values, edge cases, safety guards, and even resolution-rule risk. An agent could invoke this tool confidently with no additional documentation.

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

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

Despite full schema coverage, the description adds substantial semantic value for each parameter: market acceptance of slug/URL/question text, depth behavior (quick vs thorough fan-out), and include_raw size trade-offs. It also provides concrete fan-out examples that clarify what each parameter controls. This goes far beyond the schema's descriptions.

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

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

The description states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_edges or polymarket_arbitrage by focusing on per-market data fan-out and evidence collection. The one-line purpose is immediately clear and actionable.

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 'Use for' scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes usage-critical warnings (e.g., inspect resolver contract before trusting analysis). However, it does not explicitly name alternative tools or provide 'when-not-to-use' exclusions, so it falls just short of a full 5.

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

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

Annotations already disclose read-only, idempotent, and non-destructive behavior. The description adds no extra behavioral context such as what happens if the book is not found or whether related data is included. It is consistent with annotations but does not enrich 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, concise phrase that directly states the tool's function. Every word earns its place, and the structure is front-loaded with the core 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?

Given the simple one-parameter design, safety annotations, and presence of an output schema, the description is sufficient. However, it does not explicitly contrast with the sibling 'books' tool or mention behavior for invalid ids, so it is slightly under-specified.

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

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

The only parameter 'id' is referenced in the description and the schema includes an example. However, with 0% schema description coverage, the description could have been more explicit about the id's origin or constraints. The meaning is inferable from 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 'Single book by id' clearly states the tool fetches one book by its identifier. This distinguishes it from the sibling 'books' tool, which likely handles multiple books.

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

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

The description implies usage for fetching a single book by id but does not explicitly state when to prefer this over the 'books' tool or mention alternatives. It lacks clear when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by clarifying the return fields (ISBN, authors, publisher, pages, character lists) and the filtering capabilities, which are not explicitly covered by annotations. No contradictions found.

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

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

The description is a single, information-dense sentence that front-loads the purpose, lists all key parameters and return fields, and avoids waste. It is appropriately sized for the tool's complexity.

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

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

Given the presence of an output schema and comprehensive annotations, the description covers the core functionality, filters, pagination, and return values. It does not mention defaults or ordering, but these are minor given the output schema provides structural details.

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?

With 0% schema description coverage, the description fully compensates by explaining each parameter's role: name for filtering by book name, fromReleaseDate/toReleaseDate for date range, and page/pageSize for pagination. It adds meaning to all 5 parameters, though it could specify formats or combination semantics.

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

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

The description clearly states the tool's purpose: to search and list A Song of Ice and Fire books. It distinguishes the multi-result listing tool from the singular 'book' sibling by emphasizing filtering and pagination, making the scope specific.

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 its search/list phrasing but provides no explicit guidance on when to use this tool versus alternatives like the singular 'book' tool. It lacks exclusions or direct references to sibling tools, leaving usage inference to the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds no additional behavioral context such as not-found behavior or response format, which is acceptable for a simple read operation but does not elevate beyond the baseline.

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 character by id' is exceptionally concise, using only seven words with no filler or redundancy. It is front-loaded, immediately conveying the core 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?

The tool is a simple single-parameter lookup with a full output schema and strong annotations. The minimal description is sufficient for an agent to understand the core function. It does not address not-found behavior or selection guidance versus 'characters', but these are not critical given the output schema and sibling 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 description coverage is 0%, so the description must compensate. It does mention 'by id', tying the sole parameter to its purpose, but adds no detail beyond the parameter name and type already present in the schema. For a single obvious 'id' parameter, this meets the minimum but does not enrich understanding.

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

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

The description 'Single character by id' clearly indicates a lookup of a single entity by identifier, and the contrast with the sibling 'characters' (plural) helps distinguish it as a singular resource accessor. However, it lacks an explicit verb like 'get' or 'fetch', so it is not maximally explicit.

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

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

No explicit when-to-use or alternative guidance is provided. The phrase 'by id' implies use when a specific character ID is known, and the sibling 'characters' suggests the plural alternative, but this is implicit rather than directly stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description does not contradict them. It adds value by mentioning return fields (aliases, titles, house affiliations, appearances) but does not disclose other behavioral aspects like pagination limits, default ordering, or filtering nuances (e.g., exact vs partial matches).

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, front-loaded with the action and resource, and every part contributes meaning. It is concise without wasting words on irrelevant details.

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

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

Given the tool has 8 parameters, 0 required, and an output schema, the description covers the core purpose and main filters. However, it leaves out essential context like pagination (page/pageSize), which is critical for a list endpoint, and the ambiguous 'birth/death descriptor' could mislead users. The output schema likely covers return values, but the input semantics remain incomplete.

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 0%, so the description must compensate. It lists filterable attributes (name, culture, birth/death descriptor, gender, alive status) but does not explain parameter formats (e.g., what 'birth/death descriptor' means, whether 'gender' requires exact casing), nor does it mention pagination parameters (page, pageSize). This gives a general sense but leaves ambiguity.

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

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

The description clearly states the tool's purpose with a specific verb ('Search and list') and resource ('ASOIAF characters'), and distinguishes it from sibling tools like 'character', 'house', and 'book' by indicating it handles character lists and filtering.

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

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

The description implies when to use the tool (searching/filtering characters) but does not explicitly mention alternatives or exclusions. It provides clear context but lacks guidance such as 'use character for single entity details' or 'use book for book-specific queries'.

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 annotations (readOnly, idempotent, openWorld) by disclosing data provenance (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and return format (paired data + pipeworx:// citation URIs). It also highlights parallel execution ('ONE parallel call'), providing useful behavioral context without contradicting any annotation.

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 longer than minimal, every sentence earns its place: trigger examples, core function, preference instruction, type-specific data, sorting behavior, and return format. It is front-loaded with user intents (quotes/patterns) and structured logically, avoiding filler. The density is high yet clear, making it an appropriate and well-organized description.

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 sufficiently explains return values ('paired data + pipeworx:// citation URIs') and output ordering ('sorted by primary metric'). It covers both entity types with their respective metrics, addresses an edge case (off-calendar fiscal years), and even notes efficiency gains. For a tool with two parameters and no nested objects, this level of completeness is more than adequate.

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 100% of parameters with descriptions and examples, setting a baseline of 3. The description adds significant meaning by explaining how the 'type' parameter determines the data pulled (10-K metrics vs adverse-event/trial counts) and clarifies that 'values' are tickers/CIKs for companies or drug names. This supplementary context enhances the agent's understanding of what the parameter values represent and how they affect the output.

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 precisely states the tool performs side-by-side comparisons of 2–5 companies or drugs in ONE parallel call, with specific trigger phrases like 'Compare X and Y' and 'heads to head.' It clearly distinguishes this from sibling tools by emphasizing parallel execution and specific data sources (SEC EDGAR for companies, FAERS/FDA for drugs). The verb 'compare' is explicit and the resource scope is fully defined.

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

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

The description explicitly commands: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive on when to use this tool. It also enumerates trigger examples ('which is bigger', 'rank these companies') and states it replaces 8–15 sequential lookups, which informs selection. Although it doesn't name a specific alternative for single entities, the condition 'when comparing entities' inherently covers the exclusion.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive, and the description builds on this with extensive extra behavior: parallel tool routing, gaps[] for unanswered facets, 'never invented' evidence, contradictions[] for standard/thorough, semantic excerpting of large records, stable pipeworx:// citations, and expected latency. It also discloses the paid tier requirement for depth:'thorough'.

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 generally front-loads the most critical facts: account requirement first, then purpose, then routing to alternatives. There is some repetition of the 'use ask_pipeworx' guidance across three separate contexts, but given the tool's complexity and the absence of an output schema, the length is largely justified.

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 prerequisites, alternatives, scope boundaries, expected return packet contents (evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop), latency expectations, and depth semantics. Since there is no output schema, this behavioral documentation carries the full burden of explaining the return value, and it does so thoroughly.

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

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

Schema coverage is 100%, but the description adds meaning well beyond the schema. It explains what depth values actually do operationally: quick vs. standard gap recovery vs. thorough lead-chasing and contradictions scanning, plus typical latency. It also clarifies that the question parameter is meant for broad/multi-part natural-language questions and that decomposition is the tool's purpose.

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 1494 STRUCTURED data sources' that 'decomposes your question into focused facets' and 'returns a findings packet.' It also explicitly contrasts itself with open-web search and with ask_pipeworx, so an agent can distinguish it from siblings.

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

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

Gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' with concrete examples. It also provides clear exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... topics, prefer ask_pipeworx.' The account prerequisite and fallback to ask_pipeworx for unsigned-in users is also stated 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 declare readOnly, idempotent, and non-destructive. The description adds useful behavioral context about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'no second schema lookup needed.' This goes beyond the annotations and helps the agent know what to expect.

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 slightly long due to the domain list, but the first sentence is a clear front-loaded purpose. Each sentence adds unique value: usage context, return details, and a prioritization cue. The structure is logical, and the length is justified by the need to enumerate supported areas.

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

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

Despite no output schema, the description explains what the tool returns (names, descriptions, schemas, examples) and when to use it. It covers the core usage scenario ('Call this FIRST...') and the input requirement ('describing the data or task'). It does not mention the limit parameter's default or max, but that is minor.

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 provides 100% coverage with descriptions for all parameters, including aliases for 'query.' The description does not add additional meaning beyond what the schema already offers, though it does mention 'top-N' which indirectly relates to the 'limit' parameter. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It identifies a specific verb (find) and resource (tools), and differentiates itself from siblings by focusing on discovery rather than direct execution. The scope is further clarified with a list of domains, making it unambiguous.

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

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

It explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't list explicit alternative tools, the 'not just one answer' phrase implies you should use it for exploration rather than direct single-answer tasks.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns a specific list of fields, soft-fails on patents due to API sunset, and uses a GDELT→GNews fallback. It also notes the 'parallel call' execution model and the 'zero-padded CIK' requirement, which are not inferable from annotations.

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

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

The description is long but densely packed with useful information: usage examples, execution model, data sources, return fields, fallback behavior, and input constraints. It is front-loaded with examples and then systematically catalogs outputs. While the multiple example queries are somewhat redundant, they collectively help pattern-matching. It earns a 4 rather than 5 mainly due to the verbosity that could be trimmed.

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

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

There is no output schema, so the description must explain return values. It does this thoroughly: lists cik, company_name, recent_filings (with URI format), fundamentals (specific metrics and sort order), patents (with sunset warning), news (with fallback), and LEI. It also addresses the key limitation (names not supported) and directs to resolve_entity. Given the tool's complexity, the description is fully sufficient for an agent to select and invoke it 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 baseline is 3. The description adds meaningful extra semantics: it provides concrete examples ('AAPL', '0000320193'), clarifies the zero-padded CIK format, and explicitly excludes natural-language names. It also gives context that only 'company' is supported today, which matches the schema enum but is reinforced with 'person/place coming soon.'

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 a specific verb ('profile') and resource ('US public company'), with clear examples ('Tell me about X', 'research Acme'). It distinguishes from siblings by specifying it returns a full cross-source profile in one call and explicitly states preference over chaining single-pack lookups. The scope (US public companies) and key output fields are clearly enumerated.

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

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

The description explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides an alternative: 'names not supported (use resolve_entity first if you only have a name).' This gives clear when/when-not guidance with an alternative tool.

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

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

Annotations already disclose destructive and idempotent behavior, and the description reinforces this by saying 'delete'. It adds context about when deletion is appropriate (clear sensitive data) and implies it only affects previously stored memories. It doesn't mention error behavior for nonexistent keys, but given annotation coverage, the added context is sufficient.

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

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

The description is two sentences, action-oriented, and front-loaded with the core purpose. Every word 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?

For a simple one-parameter tool, the description covers purpose, usage, and complementary tools. The schema fully documents the parameter, annotations provide safety and idempotency information, and an output schema is not necessary. The description is complete.

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

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

The input schema already describes the 'key' parameter as 'Memory key to delete', achieving 100% coverage. The description does not add further detail about key format or constraints, so it provides no additional value beyond the schema.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb and resource, and distinguishes itself from sibling memory tools like '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?

The description explicitly provides usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with 'remember' and 'recall', giving clear guidance on when to use this tool versus 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 read-only, open-world, idempotent, and non-destructive. The description adds behavioral context beyond that: the steps of fetching the page, extracting fields, and producing a single text blob. It doesn't mention edge cases or rate limits, but given annotations, the added context is sufficient.

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

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

The description is compact and well-structured: first sentence states the core function, second explains the process and output, third lists use cases. No unnecessary words, and critical information is front-loaded.

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 only 2 parameters and no output schema, the description covers everything needed: what it does, how it works, what the output looks like ('single text blob'), and typical use cases. The tool is simple, and the description is fully adequate.

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%—both 'url' and 'max_links' have clear descriptions. The tool description does not add additional meaning beyond the schema, but with full schema coverage, a 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 clearly states the verb 'Generate' and the resource 'llms.txt file for any URL', then details what it does: fetches page, extracts title/description/key links, and emits standard markdown. This distinguishes it from siblings like scan_competitor_ai_presence by focusing on producing a file rather than just analyzing presence.

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

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

Provides concrete use cases: getting a client's site indexed, drafting your own llms.txt, and auditing a competitor's AI visibility. These imply when to use, though it doesn't explicitly name alternative tools or state when not to use, which would make it a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. However, the description adds no extra behavioral context such as what happens for a missing ID or how the response is structured. The description provides no value 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 extremely concise, consisting of a single short phrase with no filler. It is front-loaded and to the point, though it borders on under-specification for a novice agent.

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 read tool with an output schema and rich annotations, this description is adequate but minimal. It doesn't explain the domain meaning of 'house' or edge cases like non-existent IDs, but the output schema covers the return structure.

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?

With 0% schema_description_coverage, the description must compensate. 'by id' clarifies that the 'id' parameter is the lookup key, adding semantic meaning beyond the schema's bare type definition. However, it doesn't explain constraints, format, or domain meaning beyond that.

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?

Despite lacking an explicit verb, 'Single house by id' clearly identifies the resource (house) and the selection criterion (id), distinguishing it from the sibling 'houses' which likely lists all houses. It could be improved with a verb like 'get' or '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?

The description provides no guidance on when to use this tool versus alternatives such as 'houses' or other entity tools. There are no mentions of context, alternatives, or exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so safety is covered. However, the description itself adds no behavioral context beyond saying 'Search/list houses'—no mention of pagination, result shape, or filtering behavior, which is a gap.

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 short, but it is under-specified for a tool with 9 parameters and no parameter documentation. It is not appropriately sized because it omits essential detail, making it concise at the expense of usefulness.

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 (9 optional parameters, existing output schema, and sibling tools), the description is wholly inadequate. It does not explain search criteria, pagination, default behavior, or how this tool relates to singular 'house' or other entity tools, so the agent cannot use it 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?

With 9 parameters and 0% schema description coverage, the description should explain what each parameter means and how they combine, but it provides nothing. The schema only lists types, so the agent has no semantic understanding of 'name', 'words', 'region', or the boolean flags.

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

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

The description clearly states the action (search/list) and resource (houses). It is understandable but does not differentiate this tool from the singular 'house' sibling tool or other list tools, so it lacks sibling differentiation.

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

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

No guidance is provided on when to use this tool versus the singular 'house' tool or other entity list tools. It does not mention any use cases, filters, or exclusions, leaving the agent without decision context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations by enumerating returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only active subscriptions are returned by default. This exceeds the baseline expected given 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?

Two sentences, front-loaded with the action, and every sentence earns its place. The first states purpose and output, the second states when to use it. 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?

Despite no output schema, the description lists all return fields and the optional parameter. Complexity is low (one optional param), and the usage guidance covers when to use it. The tool is simple enough that this description is complete without additional details.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, so the baseline is 3. The description does not add extra meaning beyond the schema; it only implies the default behavior ('active') which is already in the schema description. No additional semantic value is provided.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions, and the phrase 'before adding more' explicitly ties it to the subscription lifecycle.

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

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

Explicit usage guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent exactly when to use this tool and implies alternatives (subscribe/unsubscribe).

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 sparse annotations, the description discloses the claim_token workflow, daily digest review, roadmap impact, per-identifier rate limit, and that it is free/non-quota. These are non-obvious behavioral traits an agent needs to know, and nothing 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 front-loaded with the core purpose and uses subsequent sentences for critical usage constraints and token mechanics. It is long (~160 words) but dense; every sentence earns its place for a tool with an unusual claim-token follow-up flow.

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

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

Given no output schema, the description compensates by explaining what the tool returns (claim_token), how to read the resolution later, rate limits, and scope restrictions. It is complete enough for an agent to decide when and how to invoke it 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%, but the description adds genuine value by mapping type values to use cases, explaining the claim_token round-trip with an example call, and advising on message content (don't paste the end-user's prompt). It stops short of clarifying whether type/message are semantically required despite the schema listing no required parameters.

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 resource ('Pipeworx team') and the action ('Tell ... something is broken, missing, or needs to exist'), followed by concrete categories (bug, feature, data_gap, praise). This distinguishes it from sibling Q&A, discovery, and data tools.

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

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

It gives explicit when-to-use conditions for each feedback type, names the exclusion ('ONLY for tools served by this Pipeworx connection'), and instructs filing with an alternative server for non-Pipeworx tools. It even offers a disambiguation rule: 'Pipeworx tool names are the ones this connection lists.'

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

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

The description discloses data provenance ('derived from CF analytics-engine'), privacy specifics ('no PII'), caching behavior ('Cached 5min-1h'), and aggregate output ('just (pack, tool, count)'). These go beyond the annotations, which only state read-only/idempotent/non-destructive.

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 a strong opening sentence, followed by specifics and a compact bulleted use-case list. It is moderately sized but every sentence carries information; no filler. Slightly verbose with the use-case enumeration, but acceptable.

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 read-only tool with no output schema, the description covers the return payload, caching, data source, and privacy, plus usage guidance. This is sufficient for an agent to select and call the tool correctly.

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

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

The schema already documents the window parameter with full coverage, including default and temporal semantics. The description merely repeats the window options without adding new parameter-specific meaning, so it does not significantly augment the schema.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'), and distinguishes it from sibling tools by focusing on what other AI agents are calling. It answers the 'what' and 'scope' 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 provides explicit use cases ('Useful for: discovering... confirming... seeing...'), which gives clear context for when to use the tool. It does not explicitly name alternatives or exclusion conditions, but the scenarios are 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?

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral traits: fill-check pricing against live CLOB depth, realizable vs theoretical edge, thin_legs reporting, placeholder filtering, Jaccard similarity threshold, and the explicit warning 'do not trade it' when realizable_edge_pp ≤ 0. This is rich context that annotations alone would not provide, with no contradiction.

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

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

The description is long but every sentence earns its place. It is front-loaded with a clear summary, then uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex behaviors. No redundant filler; the structure aids navigation.

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

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

Despite no output schema, the description details the response structure (opportunities[] with fields, partition_check fields), explains edge cases like skipped_low_similarity and placeholder fractions, and provides operational guardrails. It is fully complete given the tool's complexity and lack of a structured output definition.

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

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

Although the schema already describes event and topic, the description adds substantial meaning: concrete slug examples ('fed-decision-may-2026'), the behavior of walking child markets, the partition_check computation, and how topic mode searches related events. It also clarifies that passing no arguments triggers trending_scan, which the schema doesn't convey.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools by detailing three modes (trending_scan, event, topic) and explicitly references polymarket_fill_risk for custom sizing, leaving no ambiguity about what this tool does.

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

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

The description provides explicit when-to-use guidance for each invocation pattern: no args for a trending scan, event mode for a specific market (recommended), and topic mode for cross-event scanning. It even states when cross-event mode is superior and instructs users to use polymarket_fill_risk for custom sizing, making alternatives 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?

The description goes far beyond the annotations, disclosing caching behavior ('Cached 1h at the KV level'), the 24h-move warning ('your edge may already be in the price'), why Fed bets are excluded, the rarity of concentrated longshots, and the presence of diagnostics for empty segments. No contradiction with annotations exists; instead, it enriches the read-only, open-world, idempotent, non-destructive profile with actionable details.

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

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

The description is extremely long and dense, delving into model-specific details (e.g., FRED log-returns, GDELT ratios, per-sport α values) that are likely unnecessary for tool selection. While it is structured with clear all-caps sections, it reads like full documentation rather than a concise tool descriptor, making it less efficient for an agent to quickly parse.

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 carries the full burden of explaining return values. It thoroughly details the top-level response structure (by_segment, fed_candidates, _diagnostics), the fields in each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the logic for why segments might be empty (funnel counters). This is comprehensive enough for an agent to understand the tool's behavior.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema by explaining the rationale behind knobs like min_partition_leg_kelly (why it exists because partition arbs return kelly_fraction_half=0) and min_liquidity/max_spread_pp as 'tradeable-edge filters'. It also gives concrete examples ('Set to 2...') that help an agent understand the practical impact of each parameter.

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.' This is a specific verb+resource combination, and the 'Built for what should I bet on today' phrase establishes a distinct use case, differentiating it from siblings like polymarket_arbitrage 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 clear context for when to use the tool ('what should I bet on today') and gives practical guidance for parameter knobs (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). However, it does not explicitly mention alternative tools or when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds substantial behavioral detail: how snapshots are generated (cache-miss), response structure (tracked[], expired[], snapshot_dates[]), computation specifics (decay on |edge_pp_net|, signed values), and limitations (60-day TTL, daily closes not intraday). This goes far 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?

Despite being long, every sentence earns its place: purpose, args, response format, and limits are all essential. The structure is logical and front-loaded with the core concept. It's dense but not wasteful.

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

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

There is no output schema, so the description compensates by thoroughly explaining the return structure (tracked, expired, snapshot_dates) and their meanings. It also covers edge cases (snapshot gaps, TTL, decay computation). For a tool with 2 simple params, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning: it restates days as lookback and window as snapshot family, but the schema already provides these details. It does note default/max values, but the schema's 'clamp 2-30' is even more precise. No significant 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?

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on persistence/decay rather than 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 provides clear context on when to use the tool (when edge age and decay matter, as opposed to fresh edges) and explains the significance ('a fresh wide edge and a 3-week-old wide edge are different trades'). It doesn't explicitly name alternatives or exclusions, so it falls short of a 5, but the implied usage 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 declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond. It discloses that the tool 'walks the ladder,' returns detailed fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), and exposes risks like 'forced_directional_risk naming the legs most likely to strand you unhedged.' 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?

Though lengthy, the description is well-structured with capitalized markers (SINGLE-MARKET, BASKET) and every sentence adds value. It front-loads the core purpose, then details modes, return fields, and usage rules. No fluff or redundancy.

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

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

For a complex tool with two modes and no output schema, the description is exceptionally complete. It explains both modes, listed return values, edge cases (thin_legs, partial fills), risk disclosure, and explicit usage context relative to sibling tools. The agent is fully equipped to decide when and how to invoke this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema: it clarifies the 'REQUIRES one of market or event' constraint (not in schema's required list), explains the default auto side behavior in basket mode, and gives practical meaning to size_usd ('max spend on buys, target proceeds on sells' and 'settlement notional' in basket). This extra orientation earns a 4, though the schema already carries most detail.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by focusing on fill risk, explicitly naming polymarket_arbitrage and polymarket_edges as related tools, and details two distinct modes (single-market and basket/partition).

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?

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk) and contrasts the two modes with clear conditions for each.

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

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

The description discloses extensive runtime behavior beyond the annotations: compatibility_warning and compatibility_codes can both be non-empty even when matched_pairs>0, unclassified legs are never paired, and skipped counters expose dropped comparisons. It also explicitly notes that pre-mapped pairings are unverified, which is exactly the kind of behavioral context annotations cannot convey. There is no contradiction with the readOnly/idempotent hints.

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 and dense, and while every sentence carries operational value, it is presented as a single wall-of-text paragraph with many nested clauses. It is front-loaded with the core definition and modes, but a bulleted structure would improve scannability. This justifies a 4 rather than 5.

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

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

Because there is no output schema, the description carries the full burden of explaining what the response will contain, and it does: leg-by-leg prices, matched spreads, safety fields, compatibility codes, temporal alignment, and skipped counters. It also covers edge cases like unclassified legs and non-equivalent bet shapes. An agent can invoke the tool and interpret results without missing critical caveats.

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 all three parameters. The description adds value by clarifying how topic triggers an auto-fetch on both venues and that explicit ticker/slug override the topic-mapped sides, plus enumerating the accepted shortcut values. This lifts it above the schema-only 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 first sentence states a specific operation: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. The description then enumerates two distinct operational modes and a concrete set of pre-mapped topics, making the resource and scope unambiguous. This clearly differentiates it from sibling tools focused on single-venue edges or arbitrage.

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

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

The description explicitly explains when to use topic mode (pre-mapped macro shortcuts) versus explicit ticker/slug mode (custom pairings), and cautions that most pre-mapped topics return a compatibility warning. It does not name sibling alternatives, but the mode-selection guidance and the warning 'pre-mapped ≠ tradeable' give an agent clear usage context. No exclusions are stated, so this is not a perfect 5.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that, such as scoping to the user's identifier and the ability to list all keys by omitting the argument, which is not evident from annotations alone.

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

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

The description is concise and well-structured, with three sentences each earning their place: clear action, usage context, and scoping/pairing information. It is front-loaded and avoids redundancy with the schema.

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

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

Given the tool's simplicity, a single optional parameter, full schema coverage, and strong annotations, the description is complete. It explains both retrieval and listing modes, usage context, and scope, leaving no critical gaps for an agent to select and invoke the tool correctly.

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

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

The schema already covers the parameter ('key') with 100% coverage. The description adds meaning by providing concrete examples of stored context (ticker, address, research notes) and explaining scoping to the agent's identifier, enriching the semantics beyond the schema description.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs and resources, and distinguishes itself from siblings by explicitly referencing 'remember' and 'forget'.

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

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

Provides explicit guidance on when to use the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also mentions pairing with 'remember' to save and 'forget' to delete, implicitly noting 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?

The description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which describes a state-changing side effect. This directly contradicts the readOnlyHint: true annotation, which implies no writes. The contradiction is severe, requiring a score of 1.

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 compact yet comprehensive, covering purpose, return fields, filtering, the mark_read side effect, and an alternative access method in five sentences. Each sentence earns its place, with the core purpose front-loaded.

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 usefully lists the return fields (source, citation_uri, raw payload) and explains pagination-like behavior via mark_read. It also mentions the HTTP fallback. It could mention unread_only and limit defaults, but the schema covers those, making this quite 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?

Although the schema already covers 100% of parameters, the description adds meaningful context by giving a concrete type example ('sec_8k') and explaining the behavioral effect of mark_read. This goes beyond simple schema descriptions and helps the agent use parameters correctly.

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

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

The description opens with 'Pull fired events from your subscription feed' and clarifies it returns the most recent alerts with source, citation_uri, and raw payload. This clearly distinguishes it from siblings like list_subscriptions and recent_changes by focusing on alerts from the evaluator's feed.

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 filtering by type and since, mentions that polling works fine, and provides an alternative endpoint for scripts/dashboards. It lacks explicit 'when not to use' compared to siblings, but the polling and alternative URL provide practical 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?

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds substantial non-obvious details: parallel fan-out across sources, GDELT-to-GNews fallback on rate limits/5xx, USPTO PatentsView sunset soft-failure, and the exact return shape (changes[], total_changes, pipeworx:// URIs). This goes well beyond annotation-only transparency.

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

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

The description is long but every clause earns its place: it front-loads user intent examples, explains the fan-out architecture, documents fallback behavior and failure modes, and ends with a clear alternative. The dense but structured flow keeps it scannable despite its length.

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

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

Even without an output schema, the description fully specifies return contents (structured changes[] grouped by source, total_changes count, citation URIs), input formats, and edge-case behavior (USPTO soft-fail). It covers all necessary operational context for an agent to invoke 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 coverage is 100%, so the baseline is 3. The description largely repeats what the schema already says for each parameter, but adds a minor usage recommendation ('Use "30d" or "1m" for typical monitoring') that slightly enhances the `since` semantics without introducing new meaning for `type` or `value`.

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

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

The description opens with concrete user phrasings and defines the tool as a change feed for companies over a date window, clearly distinct from sibling tools. It names the exact data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts with entity_profile, making the purpose unmistakable.

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 context: when users ask for "what's new" or "latest updates" in a time window, this tool is appropriate. It also provides a direct alternative: "Use entity_profile instead when you want the static profile... regardless of window," and recommends typical monitoring windows like '30d' or '1m'.

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 (which already indicate a write operation that is idempotent and non-destructive), the description adds critical behavioral context: storage as a key-value pair scoped by the agent's identifier, and the distinction between authenticated users (persistent memory) and anonymous sessions (24-hour retention). This is substantial behavior that annotations do not 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 three sentences, front-loaded with the core purpose, followed by usage scenarios and key storage behavior. Every sentence contributes distinct value: what it does, when to use it, and how persistence works. No filler or redundancy.

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

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

Given the tool's simplicity (2 required parameters, no output schema, no nested objects), the description covers all essential aspects: purpose, usage cues, storage format, scoping, persistence rules, and integration with recall/forget. The absence of output details is acceptable because no output schema exists, and for a save operation, the behavioral context is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'key-value pair' which aligns with the two parameters, but it adds no additional semantic details beyond the schema's own property descriptions. The examples in the schema ('subject_property', 'target_ticker', 'user_preference') already provide meaningful context, so the description does not need to compensate.

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 and resource: 'Save data the agent will need to reuse later,' clearly identifying the tool's function. It distinguishes from siblings by contrasting with recall (retrieve) and forget (delete), which are listed as companions. The purpose is unambiguous and well-scoped.

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 states exactly when to use the tool: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also provides complementary guidance by mentioning pairing with recall to retrieve and forget to delete, effectively covering both usage and alternatives within the same tool family.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds rich behavioral detail: cascading lookups, graceful degradation (if GLEIF/OpenFIGI fail, EDGAR data still returns), explicit unresolved identifiers, and source labeling. No contradictions.

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

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

Well-structured with front-loaded examples and usage guidance, then detailed breakdowns. However, it is somewhat verbose; a few sentences could be trimmed without losing value. Still clear and organized.

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

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

Given the tool's complexity (multiple entity types, data sources, fallback behavior, unresolved identifiers), the description covers all relevant aspects. It explains what is returned for each type, the sources, and degradation behavior. No output schema exists, but the description provides a strong mental model of the output.

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 substantial value beyond the schema: it explains accepted values for each entity type (e.g., ticker, CIK, ISIN for company; brand or generic for drug), provides examples, and describes what each type resolves to. This makes the parameters much more actionable.

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

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

The description clearly states the tool resolves names to canonical identifiers needed by other tools, with specific examples like ticker, CIK, LEI, and RxCUI. It distinguishes from siblings like entity_profile by emphasizing name-to-ID resolution, which is a prerequisite for other tools.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and implies it is the first step before using other tools. It does not explicitly state when to avoid using it (e.g., if you already have an ID), but the context is clear enough.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds behavioral specifics: it probes each entity via ai_visibility_check (multiple calls), ranks by score, and returns a ranked list with score/confidence/signal density. This goes beyond annotations by explaining the aggregation behavior and output structure, though it doesn't discuss rate limits or costs.

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 the core purpose, and every sentence adds value (purpose, mechanics, use case, output). No fluff or repetition of schema details. It's appropriately sized for the tool's complexity.

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

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

For a multi-entity read-only tool with no output schema, the description is quite complete: it describes inputs, behavior, return value shape, and use case. It doesn't mention edge cases like minimum entity count (though schema says 2-8) or error conditions, but annotations cover safety and schema covers parameter constraints, so the description fills the main 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%, so baseline is 3. The description adds meaning by specifying that the first entity in 'entities' is treated as the 'subject' for narrative, and the rest are competitors—a nuance not present in the schema. It also ties the models parameter to the probing behavior, slightly enriching parameter understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific verbs like 'Compare', 'Probes', 'ranks', and 'surfaces'. It distinguishes itself from sibling tool ai_visibility_check by explicitly mentioning it as the probing mechanism, and from generic compare_entities by focusing on AI presence.

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

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

Provides clear context for when to use: 'competitive AI-marketing audits' with an example question. It implies you use this when comparing multiple entities rather than a single one, but does not explicitly state 'use ai_visibility_check for single entity' or provide exclusion criteria. Still, the context 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 and idempotent behavior, but the description adds valuable context about partial failure degradation, a 5-30s first-measurement delay, and the sources_failed field. This goes well beyond the structured hints and provides actionable expectations.

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

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

The description is dense but every sentence earns its place: purpose, use cases, ecosystem scope, output summary, and failure behavior are all covered without fluff. It is front-loaded with the core purpose and organizes details logically.

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

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

Despite lacking an output schema, the description enumerates the return fields in the summary block and lists additional outputs (per-advisory detail, links, recent alternatives). It also covers failure modes, making it complete for an agent to invoke and interpret results.

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

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

Schema description coverage is 100% for both package and version, including scoped package acceptance and version defaulting. The description adds no new parameter-specific semantics beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's composite purpose: a one-call check for npm package adoption covering license, advisories, bundle size, and tree-shaking. It distinguishes itself from siblings by naming the specific external sources (deps.dev and bundlephobia) and explicitly scoping to NPM, which separates it from other research 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?

It gives explicit usage triggers ('is X safe / popular / small' or 'what does adding lodash cost me') and an exclusion: non-NPM ecosystems should use deps.dev:version directly. This provides clear when-to-use and alternative guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: returns passages with offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and has a 200K char cap with truncation flagged. It confirms read-only nature and adds algorithmic details not present in annotations.

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

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

The description is four sentences long, front-loaded with the core purpose, and every sentence adds value: what it does, when to use it, relationship to a sibling tool, and technical implementation details. No fluff or redundancy.

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

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

The tool has no output schema, so the description compensates by explaining the return structure (passages with offsets and similarity scores). It also covers edge cases like truncation, algorithm details, and pairing with ask_pipeworx_grounded. Combined with sibling context, this is a complete and self-sufficient description.

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 descriptive text for all parameters (text, query, limit). The description adds context like 'text you already pulled' and 'top-N passages' but does not add significant new meaning beyond the schema. The baseline 3 is appropriate as the schema carries the parameter semantics.

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

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

The description states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clarifies the scope (inside a fetched record), the input (text you already pulled), and the output (top-N passages with character offsets and similarity scores). It also distinguishes from siblings by emphasizing the 'inside a fetched record' context and pairing with ask_pipeworx_grounded.

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: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also names an alternative and relationship: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and workflow 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 only provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: OAuth account requirement, anonymous/BYO cannot persist, SMS phone verification and 10/day cap, webhook signing secret returned only once, and auto-disable after 10 consecutive failures. 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 front-loaded with the core purpose and return value, then covers requirements, types, and delivery in a dense but organized paragraph. Every sentence carries useful information, though the single-paragraph format could benefit from bullet points for scannability.

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

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

For a create-type tool with no output schema, the description is remarkably complete: it covers purpose, auth prerequisite, type-specific parameters, delivery channels, return value (subscription id and webhook secret), and failure behavior. The absence of an output schema is compensated by explicitly stating what is returned.

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

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

Although the input schema covers 100% of parameters, the description adds meaningful semantic depth: concrete examples per type (e.g., items:["5.02"] = officer change), clarifies that the feed is always on, and adds operational constraints like SMS cap and webhook auto-disable that go beyond the schema descriptions.

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

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

The description opens with a specific verb and object: 'Create a proactive monitoring subscription to a live-data event stream' and states the return value ('Returns the new subscription id'). It clearly distinguishes this from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description gives clear usage context: requires a Pipeworx OAuth account, lists supported subscription types, and explains delivery channels including 'feed (always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json)'. It does not explicitly contrast with sibling tools for creating vs listing/unsubscribing, so it stops short of a 5.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds context about the live catalog source, category-bucketed output, and the optional topic focus, which enhances transparency without contradicting annotations.

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

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

Though lengthy, the description is information-dense with every sentence contributing value. It front-loads with example queries, then explains purpose, output, and usage in a logical sequence, avoiding redundancy.

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

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

For a read-only, single-optional-parameter onboarding tool, the description fully covers purpose, output, parameter semantics, and usage context. The absence of an output schema is mitigated by the clear description of what is returned.

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 describes the 'topic' parameter with 100% coverage. The description adds concrete examples (finance, pharma, betting) and explains the omit-for-full-spread behavior, providing 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 precisely states the tool's function: an onboarding entry point that returns category-bucketed example questions with corresponding tool and argument shapes. It is clearly distinguished from sibling tools by emphasizing suggestion rather than execution or comparison.

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

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

Explicitly instructs to use this tool FIRST when unsure what Pipeworx can do, and mentions learning to call meta-tools. This gives clear when-to-use guidance and indirectly points to alternative tools for deeper tasks.

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 beyond the annotations by disclosing that the operation is a deactivation, not a hard delete, and that ownership is enforced. This adds meaningful behavioral context about side effects and constraints, though annotations already cover idempotency and non-destructiveness.

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 and front-loads the core action. Every sentence provides distinct valuable information: the operation, the ownership restriction, and the deactivation behavior with a pointer to recent_alerts. No filler 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?

For a single-parameter tool with no output schema, the description fully covers what the tool does, its constraints, and its effect on related data (preserving history for recent_alerts). It also provides enough context for an agent to correctly invoke it without additional documentation.

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

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

The schema already provides 100% coverage for the single 'id' parameter, including its type and description ('Subscription id (uuid) returned by subscribe'). The tool description only says 'by id' and adds no additional semantic detail beyond the schema, so a baseline score 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 function: 'Cancel a subscription by id.' It also differentiates from siblings by noting ownership enforcement and deactivation rather than deletion, making it distinct from subscribe, list_subscriptions, and recent_alerts.

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

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

The description conveys when to use the tool: when canceling a subscription you own. It implicitly contrasts with recent_alerts by explaining that historical events remain available, but it does not explicitly name alternative tools or specify when not to use it, so it stops short of full 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 establish safety (readOnly, idempotent, non-destructive), and the description adds crucial behavioral context: the financial vs. grounded pipeline split, the precise meaning of could_not_verify (check did not happen, not evidence), and the distinction from unsupported. This goes well beyond what annotations provide.

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

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

The description is long enough to cover a complex tool, but every sentence serves a purpose: usage trigger, routing logic, return payload, critical caveats, and efficiency benefit. It is front-loaded with examples and ends with actionable warnings, with no filler.

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

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

Given the tool's complexity (routing, multiple verdicts, error states) and the absence of an output schema, the description covers all essential aspects: verdict types, return values, citation, reasoning, error handling, and how to interpret non-verdict outcomes. An agent has enough information to know when to call it and how to interpret results.

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

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

The schema already covers both parameters with examples and constraints, but the description adds extra operational guidance: tolerance_pct overrides the claim-impled tolerance, is capped at 5, and should be set to 1–2 for hallucination detection. This supplements the schema without redundancy.

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 validate_claim as a natural-language claim verification tool against authoritative sources, with concrete example queries. It distinguishes itself from generic research tools by focusing on fact-checking user statements and even mentions replacing sequential lookup 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?

Explicitly instructs when to use it: whenever the agent needs to check factual correctness of a user statement, and gives routing details for financial vs. non-financial claims. However, it does not name specific sibling tools to avoid, only implies an alternative by saying it replaces 4–6 sequential calls.

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