Obis

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds valuable context: probing multiple LLMs, scoring algorithm, per-model output structure, and the fact that Workers AI is free while Anthropic requires user's own key. No contradiction with annotations.

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

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

Three concise sentences. First sentence states core functionality and output. Second explains optional aspects. Third lists use cases. No fluff, every sentence earns its place.

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

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

Given 4 parameters (all documented), no output schema, moderate complexity (multiple models, varied outputs), the description is complete. It covers the return structure (per-model {score, confidence, signals, raw_response} + combined view) and the behavior of each parameter. No gaps remain.

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?

All 4 parameters are described in schema (100% coverage). Description adds meaningful context: explains the purpose of each parameter, provides examples (e.g., 'Pipeworx' for entity), and clarifies that `_apiKey` is only needed for Anthropic. This goes 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?

Specifically states it probes LLMs for brand/business visibility and scores (0-100) per model. Clearly distinguishes from siblings by focusing on AI visibility scoring for entities, not general Q&A or search.

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

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

Explicitly suggests use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides guidance on optional parameters (default model free, API key for Anthropic) but does not explicitly state when not to use or list direct alternatives.

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description adds behavioral context the schema can't: it routes to one of 5,724 tools, returns stable pipeworx:// citation URIs, makes one fast call, and works on every tier. It doesn't cover failure modes or rate limits, but those are not disclosed in annotations either; 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 longer than the ideal minimum but is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and every block adds routing value—domains, trigger phrases, examples, and upgrade paths. A little redundancy (e.g., 'even if web search could also answer it' echoing 'PREFER OVER WEB SEARCH') keeps it from a 5.

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

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

For a broad natural-language router with no output schema, the description covers the essential behavior: what it does, when to use it, what it returns (structured answer with pipeworx:// citations), and the two sibling tools that should be used instead in specific cases. An agent can decide whether to call this tool without opening the schema.

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

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

Schema coverage is 100% and the schema already documents 'question' plus five aliases, so the baseline applies. The description reinforces that input is a natural-language question and gives trigger-phrase examples, but adds no format, length, or syntax detail 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 names the verb 'ask' and resource: natural-language factual questions across many domains, and explicitly frames it as the default router over web search. It lists concrete categories (SEC, FDA, FRED/BLS, etc.) and examples, and distinguishes it from ask_pipeworx_grounded and deep_research so an agent can tell siblings apart.

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

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

It gives an explicit when-to-use rule ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), trigger phrases like 'what is'/'look up', examples, and identifies alternatives for when to step up: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part fan-out. No exclusion is left to inference.

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, the description discloses experimental status, live candidate-testing behavior, the absence of an active candidate as of a specific date, and the fact that it is a fully functional router with no degraded fallback. This directly addresses likely misconceptions about a beta tool.

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

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

The four sentences are mostly front-loaded and each adds context, but the 2026-07-26 date detail is more than strictly necessary. Overall it is compact and readable.

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 rich annotations, the description explains current behavior, experimental intent, and response-shape parity with the stable tool. It does not detail the response format itself, but explicitly references the same response shape as ask_pipeworx, which is 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 input schema already documents the question parameter and all five aliases with 100% coverage. The description only notes 'same arguments' as ask_pipeworx, adding no parameter-specific behavior 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 identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,724 tools, arguments, and response shape. This is a clear purpose, though it leans on comparison to ask_pipeworx rather than defining the behavior from scratch.

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 like ask_pipeworx when the newest routing is desired and notes results are compared against the stable router. It does not discuss other siblings such as ask_pipeworx_grounded, so the guidance is focused rather than exhaustive.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals the refusal mechanism, return shape with evidence verbatim, refusal reason enum, and the extra LLM call cost. It also explains that answers are extracted only from tool results, which is a key behavioral trait not captured by annotations. No contradiction with annotations.

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

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

The description is dense but well-organized: it front-loads the core purpose, then details the mechanism, return/refusal formats, usage guidance, and cost. A couple of phrases could be trimmed, but every sentence carries distinct information and the structure aids quick scanning.

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 bears the full burden of explaining return values—and it does so in detail, providing both success and refusal shapes with enum values. It also covers the tool's routing scope, cost implications, and high-stakes use cases, making it fully sufficient 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 coverage is 100%—all six parameters are aliases for 'question' and the schema already describes them fully. The description adds no additional parameter semantics, which is acceptable given the high schema coverage, so the baseline of 3 applies.

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

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

The description opens with a precise, discriminative phrase ('Hallucination-resistant answer mode for high-stakes reads') and explicitly positions itself against the sibling ask_pipeworx by explaining it uses the same routing but then grounds the answer in tool output. This allows an agent to immediately distinguish it from ask_pipeworx and ask_pipeworx_beta without inspecting schemas.

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 ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when-not-to-use guidance ('prefer ask_pipeworx for casual lookups'), including a cost tradeoff. This is textbook usage guidance—clear, specific, and 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?

The description goes far beyond annotations (readOnly, idempotent, etc.) by detailing the resolution contract, fan-out behavior, response shapes, failure modes (low-confidence, closed markets, wide spreads), resolution-rule risk, and parent event extraction. This comprehensive disclosure prepares an agent for all eventualities.

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

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

The description is very long (~600 words) and front-loads the core purpose, but then expands into dense technical details. While every sentence adds value, it could be more concise for an agent to parse quickly. Balanced between thorough and verbose.

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

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

Given the complexity of the tool (multiple inputs, rich output, edge cases), the description covers everything: input formats, parameters, response fields, error states, and safety checks. It is fully complete even without an output schema, detailing the structure of result.market, result.analysis, result.evidence, etc.

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

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

While the schema already covers parameter descriptions (100% coverage), the description enriches them with examples (slug, URL, question text for market), explains the impact of depth and include_raw, and clarifies the implications of choices. It adds meaningful context 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 opens with a specific verb-resource pair ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call'), clearly distinguishing it from siblings like ask_pipeworx or polymarket_edges. It further clarifies by giving explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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 three use cases for the tool ('Use for...'), providing clear context. However, it does not explicitly contrast with similar sibling tools (e.g., polymarket_edges, compare_entities) or state when not to use it, leaving some ambiguity.

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 description adds: it pulls latest 10-K data handling fiscal year offsets, sorts results by primary metric, and for drugs summarizes FAERS, FDA approvals, trials. No contradictions; the description enriches the behavioral context beyond the annotation safety profile.

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?

A single dense paragraph that front-loads examples and key advice, then methodically covers types and data sources. Every sentence adds value—no redundancy. The structure is easy to scan and understand.

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 adequately explains output format: 'paired data + pipeworx:// citation URIs per entity' and mentions sorting. It covers all input variations and provides enough detail for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, but the description adds critical context: explains type='company' means SEC financials (revenue, net income, cash, debt) and type='drug' means regulatory/trial counts, and clarifies values array expects tickers/CIKs vs drug names with explicit bounds (2–5 items). This goes well beyond the schema's minimal 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 starts with concrete query examples ('Compare X and Y', 'X vs Y', etc.) and precisely states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It clearly distinguishes from sequential lookups and specifies the data pulled per type (SEC financials for companies, FAERS/FDA/trials for drugs).

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', provides example queries, and notes it replaces 8–15 sequential lookups. This gives clear when-to-use guidance and implicitly sets boundaries (use when comparing, not for single entity profiles).

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavior beyond these: parallel faceted decomposition, findings packet structure, explicit gaps[] that are never invented, contradictions[] for standard/thorough, hop fields, citation_uri fetchability, semantic excerpting, and latency expectations. This fully discloses operation without contradicting 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 long but every sentence earns its place: it front-loads the critical account requirement, then covers functionality, usage boundaries, depth behaviors, return format, and latency. There is no filler; the structure logically moves from prerequisites to when-to-use to how-it-works to expectations.

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

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

With no output schema, the description fully documents the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers prerequisites, alternatives, edge cases, and runtime expectations, making it complete for both calling and interpreting results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the enum descriptions: it explains how each depth value behaves ('standard' re-angles gaps, 'thorough' chases leads), provides example questions, and clarifies that broad/multi-part questions are the intended use. This is a meaningful addition over 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources... in ONE call.' It clearly distinguishes itself from siblings by explicitly naming ask_pipeworx as the alternative for single lookups and current news, and it positions itself as 'NOT open-web search.'

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data,' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It even handles the account prerequisite: 'If you are not signed in, use ask_pipeworx instead.'

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, destructiveHint=false. The description adds that results include 'full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This aligns with and enriches the annotations without contradiction.

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

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

The description is a single, well-structured paragraph with no filler. Every sentence adds value: purpose, use case, input examples, output format, and strategic advice ('Call this FIRST'). It is front-loaded with the core action.

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

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

For a tool discovery function with no output schema, the description adequately explains what the tool returns (names, descriptions, schemas) and that results are call-ready. It covers the key behavioral aspects. A minor gap is not detailing that the output includes examples, but it mentions 'curated examples' implicitly.

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 clarifies that multiple aliases (q, task, search, description) all serve as the query parameter, and mentions the limit parameter's default and max. This adds practical usage context beyond the schema's individual property descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, FDA drugs, etc.) and explicitly states it returns top-N relevant tools with schemas. This unambiguously differentiates it from all sibling tools.

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

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

The description provides explicit context: '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.' This is strong guidance, though it does not explicitly state when not to use it or name alternative tools for specific 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 indicate read-only, idempotent, non-destructive behavior. The description builds on this by detailing the internal fan-out across SEC EDGAR, XBRL, USPTO, GDELT/GNews, GLEIF, and specific return fields. It also discloses a known limitation (USPTO patent source sunset May 2025) and fallback behavior, providing rich behavioral context beyond the annotations.

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

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

The description is relatively long but well-organized: it starts with trigger phrases, then states the core purpose, followed by a bullet-like list of return components. Every sentence contributes information; the length is justified by the tool's complexity. Could be pared down slightly, but it 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 (multi-source aggregation) and lack of an output schema, the description comprehensively covers what the tool returns: CIK, company name, filings with URIs, fundamentals with specific fields, patent status with sunset date, news sources, and LEI. It also addresses the input constraint (names not supported) and provides a fallback reference.

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

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

Schema coverage is 100% with both parameters having clear descriptions (type only 'company', value accepts ticker or CIK). The description reinforces that names are not supported and references resolve_entity, adding practical value. While the schema already does a good job, the description's examples and context slightly enhance 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 defines the tool's purpose as generating a holistic profile of a US public company from multiple sources in a single call. It distinguishes itself from sibling tools like resolve_entity and from chaining multiple single-purpose lookups, with explicit instructions to prefer this tool when a broad view is needed.

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

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

The description provides clear usage guidance: it gives trigger examples, states when to use (holistic queries) and when not (if only a name is available, use resolve_entity first). It explicitly says 'ALWAYS PREFER over chaining single-pack lookups', offering direct comparison to alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining that the tool returns a total match count plus a sample of records (not all results), and lists the fields included. This contextualizes the behavior beyond the annotations.

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

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

The description is only two sentences: the first states the core function and output fields, the second mentions optional filtering and return format. It is front-loaded, every sentence adds value, and no unnecessary words are present.

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 that there is no output schema, the description explains the return value (match count + sample of records) and lists the fields. This is sufficient for an agent to understand what to expect. However, it could clarify what 'sample' means (e.g., random or top records), but the overall completeness is high.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new parameter-level detail beyond what the schema already provides (e.g., the optional date range filter is mentioned, but the schema already describes startdate, enddate, and limit). The description focuses on overall purpose rather than 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 uses a specific verb ('find') and resource ('georeferenced marine occurrence records'), lists the key fields returned, and names the data source (OBIS). This clearly distinguishes it from sibling tools like get_taxon, which deals with taxonomy rather than occurrence records.

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

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

The description implies the tool is for searching occurrence data by scientific name with optional date filtering, but it does not explicitly state when to use this tool over alternatives (e.g., search_within, entity_profile) or when not to use it. There are no direct comparisons 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 indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, but does not disclose additional behavioral traits beyond what annotations provide. 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 two sentences, front-loaded with the action, and contains no fluff. Every sentence adds value.

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

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

Given the simple single-parameter schema and no output schema, the description is complete: it explains purpose, usage, and pairing with siblings.

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

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

Schema coverage is 100% and the parameter 'key' is described as 'Memory key to delete'. The description does not add substantial meaning beyond this.

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 'Delete a previously stored memory by key' which is a specific verb and resource. It distinguishes from siblings 'remember' and 'recall' by implying these are storing and retrieving operations, respectively.

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

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

The description provides explicit usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with siblings, indicating when not to use.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by detailing the process (fetch page, extract info, emit markdown) and output format, providing context beyond annotations.

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

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

The description is concise (2-3 sentences), front-loaded with main purpose, then details, then use cases. Every sentence serves a purpose with 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?

Given low complexity (2 params, no output schema), the description sufficiently explains the tool's function and output. Annotations cover safety, and the description clarifies the output format and application.

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 does not add extra parameter information beyond what's in the schema, but the schema itself is clear.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action, resource, and use cases. It distinguishes itself from sibling tools like ai_visibility_check by focusing on llms.txt generation.

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 use cases (client site indexing, personal projects, competitor auditing) but does not explicitly mention when not to use or compare with alternatives, though context is sufficient.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds that it returns total occurrence records, distinct taxa, etc., but does not disclose additional behavioral traits like response size limits or data freshness.

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 sentence, front-loaded with main purpose, no fluff. Every word adds value.

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

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

Given simple input (one string), rich annotations, and no expected output schema, description sufficiently explains what the tool returns. Minor gap: no mention of potential ambiguity in taxon resolution, but acceptable.

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 the single parameter 'scientificname', which already provides example. Description adds no extra meaning beyond the schema, 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?

Description uses specific verb 'Get' and resource 'aggregate OBIS statistics for a marine taxon', listing exactly what stats are returned. Distinguishes from siblings like 'find_occurrences' (individual records) and 'get_taxon' (taxon details).

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 guidance on when to use this tool vs alternatives or prerequisites. Implied by sibling names but lacks direct 'use this when' or 'instead of' statements.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds beyond annotations by specifying the tool is 'keyless' and detailing the exact return fields, which is valuable context for the agent. 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 extremely concise: two sentences. The first sentence front-loads the core purpose and return values, and the second adds useful context (OBIS, marine focus, keyless). No wasted words.

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

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

For a simple tool with one parameter, no output schema, and rich annotations, the description covers all essential aspects: what it does, what it returns, the data source, and authentication status. It is fully complete for an agent to understand and use the tool correctly.

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

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

The schema description for the single parameter 'name' is already clear (scientific name with examples). The description adds context by specifying 'marine' and giving an example, aligning with schema examples. Since schema coverage is 100%, baseline is 3, but description adds meaningful marine context, justifying a 4.

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 'Resolve' and the resource 'marine species/genus/family name against OBIS', and lists the specific fields returned (taxon ID, rank, accepted name, kingdom/phylum/family/genus, total occurrence-record count). It distinguishes from sibling tools like 'resolve_entity' by specifying the marine focus and OBIS database.

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 context that OBIS complements GBIF with a marine focus, and mentions 'keyless' implying no authentication is needed. However, it does not explicitly state when to use this tool over alternatives or when not to use it, lacking explicit usage constraints.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, which cover safety. Description adds return field details (id, type, params, timestamps, fire_count) and usage intent, but does not contradict annotations. Minor missed opportunity to explicitly state no side effects, but annotations already convey safety.

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

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

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

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

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

Given the tool's simplicity (one optional param, no output schema), the description, combined with rich annotations and schema, is complete. It covers purpose, return fields, and usage. The lack of an output schema is compensated by listing fields in the 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 coverage is 100% with a clear description for the single optional parameter include_inactive. The tool description does not add any additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description states 'List the caller's active subscriptions', specifying verb (list), resource (subscriptions), and scope (caller's active). It lists return fields and distinguishes from sibling tools like subscribe and unsubscribe by indicating when to use it: to review before adding more or to find an ID to cancel.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use (before subscribing or to get cancellation IDs) and implying alternatives (subscribe and 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?

The description adds substantial behavioral context beyond the sparse annotations: rate limiting ('Rate-limited to 5 per identifier per day'), free usage, the no-account claim_token flow, and the team's daily digest/roadmap signal. It also clarifies the scope boundary, so the agent knows what Pipeworx can and cannot fix.

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: core purpose, then scope exclusions, then follow-up mechanics, then rate limits and cost. It is front-loaded with the primary action and structured logically, 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?

With no output schema and minimal annotations, the description carries the full burden — and succeeds. It covers when to use, when not to use, how to structure feedback, what the artifact of filing is, how to retrieve resolution status, and rate-limit/cost constraints. The agent can invoke and follow up confidently.

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%, establishing a baseline of 3. The description adds meaningful param-level value by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), the fact that filing without an account returns the token, and by reinforcing which type enum value maps to which situation.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories (bug, feature, data_gap, praise) and clearly distinguishes this tool from sibling query/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 explicitly states when to use ('wrong/stale data', missing tool, praise) and when not to use: 'ONLY for tools served by this Pipeworx connection' — directing other-server issues elsewhere. It even explains the claim_token follow-up flow, giving clear operational guidance.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, and cache duration per window.

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

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

Three well-structured sentences with bullet points, front-loaded main purpose, no unnecessary words.

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

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

For a simple read-only tool with one parameter and no output schema, the description fully covers purpose, use cases, data source, caching, and window semantics.

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

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

The single parameter 'window' has an enum and schema description. The description adds caching behavior based on window selection, going 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 returns 'top tools, top packs, and total call volume' over a window. It distinguishes itself from siblings like discover_tools and get_statistics by focusing on trending usage derived from other AI agents.

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?

Lists three explicit use cases and explains window semantics. However, it does not mention when not to use or directly compare to 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?

Adds significant context beyond annotations: explains monotonicity checks, partition_sum check, Jaccard similarity filter, placeholder fraction filter, and fill check with live CLOB depth. Warns not to trade if realizable edge ≤ 0. No contradiction with annotations.

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

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

Well-structured and front-loaded with core purpose. All sentences add value, but some technical details (like Jaccard threshold, placeholder filtering) could be slightly more compact. Still efficient.

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

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

No output schema, but description fully explains return fields: opportunities[] with gap_pp, suggested_trade, reasoning, violation context, and partition_check details for event mode. Also covers fill check. Complete for this complex tool.

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

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

Schema covers 100% of parameters with descriptions. Description adds depth: examples of slugs, explanation of what each mode does internally, and behavior like partition check or Jaccard matching. Greatly enhances understanding beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args for trending scan, event for single market, topic for cross-event), making it distinct from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance: when to use no args (trending scan of top 200 markets), event (recommended for a specific market with slug example), and topic (cross-event scanning with seed question). Provides examples and explains cross-event mode catches patterns missed by single-event mode.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive detail: caching (1h KV), model families, edge calculation, slippage handling, tradeable-edge knobs, segment logic, diagnostic output, and limitations (Fed bets excluded). This far exceeds 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 very long and dense, containing implementation details (e.g., exact model parameters, sports-specific alpha values). While informative, it could be more concise. The first sentence does clearly state the purpose, but the length may overwhelm an 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?

Despite no output schema, the description thoroughly explains the response structure (segments, opportunity fields, diagnostics), edge calculation, caching behavior, and filter knobs. It leaves no major gaps for a complex tool with 9 parameters and multiple segments.

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?

All 9 parameters have schema descriptions, but the tool description adds high-level context about knobs like min_liquidity and min_partition_leg_kelly, explaining their purpose and effect beyond the schema. It does not redundantly repeat parameter details, which is appropriate given 100% schema coverage.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself from sibling tools by focusing on opportunity discovery without manual pagination.

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 strong context for when to use the tool ('discover opportunities without paging hundreds of markets') but does not explicitly state when not to use it or compare to alternatives like polymarket_arbitrage or polymarket_edge_tracker. It implies its niche but lacks direct 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds detailed behavioral context: data sources, response structure (tracked/expired/snapshot_dates), constraints (60-day TTL, snapshot gaps), and decay computation specifics. 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 well-structured with clear sections (purpose, args, response) and front-loaded with the main question. Every sentence adds value, though some analogies (e.g., 'the latter is wide for a reason') are insightful but slightly verbose.

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

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

Given the tool's complexity (time-series, multiple response parts, constraints) and lack of output schema, the description thoroughly explains return values, computed fields, limitations, and edge cases. No gaps.

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

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

Schema coverage is 100% and the description repeats parameter info (days, window) with defaults and constraints, adding little beyond the schema. However, it clarifies 'snapshot family' context, which is marginal. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('answers'), identifies the resource ('edge persistence and decay telemetry'), and distinguishes from siblings by focusing on time-series analysis of edges, contrasting with tools like 'polymarket_edges'.

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

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

The description implicitly guides usage by stating it answers 'how long has this edge existed and is it shrinking?' and contrasts fresh vs. stale edges. However, it lacks explicit when-to-use or when-not-to-use compared to 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 mark it as read-only, open-world, idempotent, non-destructive. Description adds rich behavioral details: walks order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict. In basket mode, returns theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk. Alerts about risks of partial fills. No contradictions with annotations.

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

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

Description is comprehensive but somewhat lengthy; however, every sentence provides necessary information. Structure with sections (SINGLE-MARKET, BASKET) improves readability. Could be slightly more concise but justified given complexity.

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

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

Given the tool's complexity (two modes, risk assessment), no output schema, and well-defined annotations, the description covers all necessary aspects: purpose, parameters, return values, usage context, and risk warnings. No gaps identified.

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

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

Schema coverage is 100%, but schema descriptions are minimal. The tool description adds significant meaning: explains side defaults per mode, clarifies size_usd interpretation vary by mode (spend vs target proceeds vs settlement notional), and emphasizes that market and event are mutually exclusive. Adds value beyond schema.

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

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

Description clearly states it checks realizable-vs-theoretical edge against live CLOB order-book depth, with explicit separation into single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying its role as a pre-execution check. Specific verb+resource+scope.

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 before acting on certain signals from polymarket_arbitrage and polymarket_edges, and provides a threshold (~$500). Explains why: theoretical overround on thin books is not capturable, and partial basket fills convert arb into directional position. Clear when-to-use and when-not-to-use.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing compatibility_warning and compatibility_codes, the gross-vs-net fee distinction, skipped unclassified legs, per-entry flags, and the fact that both modes run the same token-overlap matcher. This is exemplary behavioral disclosure for a complex comparison tool with no output schema.

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 highly structured, with clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and the core purpose front-loaded. A few disclosures are repeated across different sections for emphasis, so it is not maximally concise, but every sentence carries substantive safety or usage information.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility fields, per-entry flags, temporal_alignment semantics, fees_note, and skipped-comparison counters. An agent has enough information to interpret results safely and 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?

Although the schema already documents the three parameters at 100% coverage, the description adds critical semantics: topic expands to ten named macro shortcuts, explicit tickers override the topic-mapped side, and both modes run identical matching logic. It tells the agent how parameters interact and what each mode produces, which the schema alone does not 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 opening sentence—'Cross-venue spread between Kalshi and Polymarket for the same resolving question'—names a specific resource and computation clearly. It does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or polymarket_edges, so it misses the top bar for sibling distinction.

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 clearly explains the two modes—topic shortcuts versus explicit event pairings—and tells agents when each is appropriate, including that pre-mapped topics often return compatibility warnings. It gives strong context about output reliability but does not explicitly say 'use this instead of X' or name alternatives, so no exclusions are provided.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds scope (identified user) and pairing with forget/remember, but no hidden behaviors.

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 concise sentences with clear flow: retrieve, list, use case, scope, related tools. No wasted words.

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

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

Given simple tool with one optional param and no output schema, description covers usage, scope, and relationship to siblings comprehensively.

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

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

Schema covers parameter 100%; description adds examples of content (ticker, address, notes) and explains omit-to-list, but doesn't add deep semantics beyond schema.

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

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

Explicitly states it retrieves values saved via remember or lists keys, distinguishing from siblings 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?

Describes when to use (look up context stored earlier) and how to list all keys, but lacks explicit when-not-to-use or direct alternatives.

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

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

The description adds significant behavioral context beyond annotations: it explains return fields, filtering, and the optional side effect of marking events as read. However, annotations declare readOnlyHint=true, which contradicts the possibility of mutation via mark_read. This reduces the score from a perfect 5.

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

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

The description is four sentences, front-loaded with the primary action, and every sentence adds necessary detail without redundancy. It is concise and well-structured.

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

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

Given no output schema, the description adequately covers return format, filtering options, and side effects. It also mentions an alternative access URL, making it complete for a read tool with high schema coverage and clear annotations.

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 some value by giving a concrete example for 'type' ('sec_8k') and clarifying how 'mark_read' affects subsequent calls. However, it does not explain parameter interactions (e.g., both 'mark_read' and 'unread_only') 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 verb 'Pull' and resource 'fired events from your subscription feed'. It specifies what is returned (source, citation_uri, raw event payload) and distinguishes from sibling tools like 'list_subscriptions' and 'subscribe' by focusing on the feed's 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 provides context for when to use: polling is fine, filtering by type/since, and using mark_read to control next calls. It also mentions an alternative direct URL. However, it does not explicitly state when not to use the tool or compare it directly to siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds multi-source fan-out, fallback logic, API status, accepted date formats, and return structure, all 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?

One dense paragraph containing all key information. Could be slightly more structured (e.g., bullet points for sources), but every sentence earns its place without redundancy.

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

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

Despite no output schema, the description fully describes return structure (changes grouped by source, total_changes, citation URIs). Given complexity (multi-source, date parsing, fallbacks), this is comprehensive.

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

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

Schema descriptions are complete, and the description adds crucial context: explains `since` accepts ISO date or relative shorthand like '30d', `value` accepts ticker or CIK, and `type` is limited to 'company'. This meaningfully enhances schema docs.

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

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

The description clearly states the tool returns a change feed for a company over a time window, covering SEC filings, news, and patents. It uses explicit query examples and distinguishes from sibling tool entity_profile for static profiles.

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

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

Provides explicit usage examples and direct comparison with entity_profile, telling the agent when to use this tool vs. alternatives. Also explains fallback behavior for news sources and limitations.

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

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

Description adds behavioral context beyond annotations: scoping by identifier, persistence differences between authenticated and anonymous users (24-hour TTL). No contradiction with annotations.

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

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

Description is concise (4 sentences), front-loaded with purpose, and every sentence adds value. No redundant or vague statements.

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 key-value storage tool, description covers scope, persistence, and pairing with recall/forget. Minor omission: no mention of overwrite behavior or confirmation, but idempotentHint covers safety.

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

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

Schema coverage is 100% with parameter descriptions. Description does not add additional semantics beyond what the schema already provides. Baseline score of 3 applies.

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

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

Description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from sibling tools 'recall' and 'forget' by explaining pairing, and provides examples of use cases.

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

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

Description explicitly says 'Use when you discover something worth carrying forward' and gives concrete examples. It does not explicitly state when not to use, but the context is clear.

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

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

The annotations already cover readOnly, idempotent, open-world, and non-destructive behavior. The description adds rich behavioral context: graceful LEI/FIGI degradation, explicit unresolved identifiers, source-labelled results, and ambiguous matches returning figi_candidates without asserting a single answer. 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 long, but nearly every sentence carries operational detail that an agent needs, and the trigger phrases are front-loaded. It could be tightened with better structure, such as bullets for the supported types, but the density is justified for a tool with heterogeneous sources and edge cases.

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

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

There is no output schema, so the description carries the burden of explaining results, and it does: CIK, ticker, LEI, FIGI, RxCUI, unresolved fields, figi_candidates, source labels, and degradation behavior are all disclosed. Both supported types and their input variants are covered well enough 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 description coverage is 100%, but the description adds substantial value by explaining the exact value formats for both types, the entity-name-only rule, and why trailing security-class words break FIGI lookups. This goes well beyond the schema and meaningfully reduces misuse.

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 names an exact verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It is further scoped by 'Use FIRST whenever you have a name but need an ID' and by enumerating supported entity types (company, drug), which clearly separates it from profile or comparison tools among the 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?

It provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and documents accepted input formats and edge cases like ambiguous bond issuers. It does not name a fallback or alternative tool for out-of-scope cases, so the when-not guidance is somewhat implicit rather than fully explicit.

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, destructiveHint=false, so the safety profile is clear. The description adds that it calls ai_visibility_check multiple times, treats the first entity as the subject for narrative, and returns a ranked list with score, confidence, and signal density. This adds valuable behavioral context beyond the annotations.

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

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

The description is a single well-structured paragraph that starts with the core action, explains the process, gives a concrete use case, and states the output. Every sentence adds value with no redundancy or unnecessary 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?

The description explains the tool's purpose, process, and output format (ranked list with score, confidence, signal density). Given 4 parameters and no output schema, it provides sufficient context for an agent to use the tool. It does not cover edge cases like invalid entities or probe failures, but annotations (idempotent, read-only) mitigate risk.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal additional meaning beyond the schema (e.g., mentioning that entities are probed with ai_visibility_check). Achieves baseline adequacy but does not significantly enhance 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, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It provides a concrete use case (competitive AI-marketing audits) and differentiates from siblings like ai_visibility_check (single entity) and compare_entities (more general).

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

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

The description explicitly says it is useful for competitive AI-marketing audits and implies when to use (comparing multiple entities). It mentions probing each entity with ai_visibility_check, indirectly indicating that for a single entity, that tool should be used. However, it does not explicitly state when not to use or list alternatives, but the context from sibling tools is clear.

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

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

Adds behavioral details beyond annotations: fans out across services, returns specific summary fields, degrades gracefully on partial failures, and mentions potential timeout for bundlephobia. 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?

Four sentences, well-organized: purpose, usage, output, caveats. No unnecessary words, all information earns its place.

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

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

Despite no output schema, description fully explains output fields and structure. Also covers version fallback and error handling. Complete for the tool's complexity.

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

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

Schema has 100% coverage. Description adds that version defaults to latest, package accepts scoped names. This adds value beyond the schema but is not extensive.

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

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

The description clearly states it's a composite check for evaluating npm packages, specifying the sources (deps.dev, bundlephobia) and the questions it answers. It distinguishes itself from siblings by focusing on npm package analysis.

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

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

Explicitly says when to use ('is X safe/popular/small', 'what does adding lodash cost me') and when not to use (only npm, other ecosystems use deps.dev directly). Also covers partial failure behavior.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description reveals the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), input cap (200K chars), truncation behavior, and output details (offsets, similarity scores), contradicting nothing.

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?

A single well-structured paragraph of ~110 words, front-loading purpose, then usage, then technical details. Every sentence contributes essential information with no redundancy.

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

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

Despite no output schema, the description explains output format (top-N passages with offsets and similarity scores), input limits, and truncation behavior, fully covering information needs for an AI agent.

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

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

With 100% schema coverage, the description enriches parameters: adds max 200K chars to 'text', provides query examples ('supply-chain risk', 'drug interactions'), and specifies limit range (1-20, default 5), all beyond 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 uses clear verbs ('Semantic search INSIDE a fetched record') and specific resource examples (SEC 10-K, article, long tool result), differentiating it from siblings like ask_pipeworx_grounded by specifying it operates on already-fetched text.

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 ('record too big to cram into the prompt'), why it's beneficial ('saves context, returns only passages that matter'), and recommends pairing with a sibling (ask_pipeworx_grounded), providing clear 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?

Adds significant behavioral details beyond annotations: OAuth requirement, type-specific parameters, delivery options, SMS daily cap, webhook secret one-time return, and auto-disable after failures. Annotations only provide readOnlyHint and destructiveHint.

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

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

Description is long but well-structured with examples and constraints. Nearly every sentence adds value, though it could be slightly more concise.

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

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

For a tool with 3 parameters and no output schema, the description covers all inputs, return value, prerequisites, and behavioral nuances. Complete for its complexity.

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

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

Schema coverage is 100%, and description adds concrete examples for each type parameter, delivery channel constraints, and verification steps. Adds value beyond the schema.

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

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

Description clearly states it creates a proactive monitoring subscription and returns the new subscription ID. It distinguishes from sibling tools like list_subscriptions (listing) and unsubscribe (removal).

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 OAuth account requirement and lists supported subscription types with examples. Does not explicitly exclude alternatives, but context with siblings implies when to use versus other tools.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context about the output structure (category-bucketed) and that examples are drawn from a live catalog of thousands of tools, which is useful beyond the annotations.

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

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

The description is moderately long but well-structured, starting with the core purpose, then the output format, and ending with usage guidelines. Every sentence adds value, though a slight trimming could improve conciseness without losing clarity.

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

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

Given the simple schema (one optional parameter, no output schema), the description covers all necessary aspects: purpose, when to use, parameter usage, and behavioral context. It provides sufficient information for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, with a description listing possible topics. The description adds semantic value by explaining the effect of omitting topic (full spread) and providing examples like 'finance', 'pharma', 'betting', which aids agent reasoning.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding, using explicit phrases like 'what can I ask Pipeworx' and 'the onboarding entry point'. It distinguishes itself from sibling meta-tools by specifying it is for initial orientation, not for answering specific queries.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and suggests alternative tools like ask_pipeworx or entity_profile for other purposes. It also explains how to use the optional topic parameter to focus results.

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

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

The description adds context beyond annotations by clarifying that the row is deactivated (not deleted) and that ownership is enforced. This aligns with the non-destructive and read-only 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?

Two sentences with zero waste. The first sentence immediately states the action, making it efficient and well-structured.

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

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

Given the tool's simplicity (one parameter, no output schema), the description sufficiently covers the behavior and constraints. Could mention idempotency but annotation covers it.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter. The description does not add further parameter details, meeting baseline expectations.

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

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

The description clearly states 'Cancel a subscription by id.' using a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by indicating it is the cancellation action.

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 ownership enforcement and the effect (deactivation, not deletion), but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. It implies usage context well.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive. The description adds critical behavioral detail beyond annotations: the distinction between could_not_verify (failure, not evidence) and unsupported (no source), the tolerance_pct override behavior, and the citation requirement. This is essential for correct interpretation of results.

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 carries unique value: examples, routing logic, verdict list, caller warning, and efficiency note. It is well-structured and front-loaded with the most important use-case information. No fluff.

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

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

For a complex tool with two pipelines, multiple verdicts, and an error state, the description covers all necessary aspects: when to use, what it returns, how to interpret could_not_verify, and parameter semantics. Even without an output schema, the verdict list and citation explanation make the behavior predictable.

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 enriches both parameters. For claim, it gives concrete examples. For tolerance_pct, it explains how it overrides the claim's implied tolerance and suggests values for hallucination detection. This goes far beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides multiple example phrasings and distinguishes itself by returning a structured verdict, making it distinct from general-purpose query tools like ask_pipeworx 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?

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the two routing paths (company-financial vs. other claims), giving clear context for expected behavior. No alternatives are named, but the trigger conditions are unambiguous.

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