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 declare readOnlyHint=true and openWorldHint=true. The description adds valuable context: it routes through 5,529 tools, fills arguments, returns structured answers with pipeworx:// citations, and works on every tier with one fast call. This goes beyond the annotations, but it could disclose more about potential failure modes or citation format limits.

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

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

The description is lengthy but every sentence earns its place: it fronts the key priority ('PREFER OVER WEB SEARCH'), gives concrete examples, names alternatives, and covers tier compatibility. It is well-organized and information-dense without fluff, making it appropriately sized for a default entry-point tool.

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

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

With no output schema, the description must convey return behavior, and it does: 'returns the structured answer with stable pipeworx:// citation URIs'. It also covers scope (real-world entities, events, numbers), alternatives, and tier support. For a simple input tool with complex routing behavior, this description is complete for an agent to use correctly.

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

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

Schema coverage is 100% (all 6 parameters are aliases for 'question'). The description adds value beyond the schema by providing concrete examples of questions ('current US unemployment rate', 'Apple's latest 10-K') and explaining that input is natural language. This helps the agent understand what to pass, though it doesn't detail each alias individually.

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 what the tool does: it routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It uses a specific verb ('ask'/'routes') and resource ('Pipeworx'), and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'find'. It also names alternatives with specific conditions: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'.

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

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

Beyond annotations (readOnly, idempotent), the description explains the experimental nature, that candidates can be active, that no candidate is currently active, and that this is a full working router with no fallback. It provides context on state-dependent behavior 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?

Four sentences that are front-loaded with the tool's identity and experimental status. Every sentence adds value: what it is, current state, usage guidance, and clarification that it's fully functional. No waste.

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 fully explains the tool's purpose, relationship to ask_pipeworx, current state (no active candidate), and usage. Even without an output schema, the response shape is said to match ask_pipeworx, which the agent can find among 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?

The input schema has 100% coverage with descriptions for all six parameters, all aliases for 'question'. The description adds no extra parameter detail beyond noting 'same arguments', so a baseline of 3 is appropriate.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_grounded by being the experimental edge while currently matching ask_pipeworx.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that it currently matches ask_pipeworx exactly, implying when to prefer the stable router instead. This gives direct usage context and identifies the alternative.

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

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

Annotations already indicate read-only, idempotent, non-destructive, open-world behavior. The description adds valuable behavioral context: it costs one extra LLM call, returns specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and guarantees evidence as verbatim quotes. This goes far beyond the annotations and fully discloses the tool's operational characteristics.

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 contributes unique value: what it does, how it routes, how it extracts, return shape, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the core purpose and structured logically, with no filler or repetition.

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

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

Given the tool's complexity (grounded answer mode with refusal logic), the description thoroughly covers the return format, all possible refusal reasons, and usage context. It also explains the cost difference vs. the sibling tool. No output schema exists, so the description carries full responsibility for explaining outcomes, and it does so completely.

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 has 6 parameters but all are aliases for the single question parameter, and the schema descriptions already document each alias. The description adds no additional parameter semantics beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states it is a hallucination-resistant answer mode that routes to the same tool as ask_pipeworx but then extracts answers from the tool result. It distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded extraction and explicit refusal behavior, making its purpose unambiguous.

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

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

The description explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and gives examples (financial verdicts, legal claims, etc.). It also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost. This is perfect when-to-use and when-not-to-use guidance.

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

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

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 declare read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral context: account/paywall requirements, expected latency (15-90s), gaps[] behavior, contradictions[] in standard/thorough modes, semantic excerpting of large records, and the guarantee that citations are always fetchable via pipeworx:// URIs.

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

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

The description is long but dense, with every sentence contributing meaningful operational detail. It is front-loaded with the account requirement and core purpose, though a more structured layout (bullets or headers) could improve scanability. Overall, appropriately sized for the tool's complexity.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally complete: it covers prerequisites, alternatives, time expectations, return packet structure (findings, gaps, contradictions), citation semantics, depth behaviors, and second-hop iteration. This fully equips an agent to select and invoke the tool correctly.

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

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

Schema already describes both parameters, but the description adds substantial meaning: depth is elaborated with concrete facet counts (quick=3, standard=5, thorough=8), hop behavior, and contradiction scanning. It also clarifies that question should be broad/multi-part, adding guidance not present in the schema.

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

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

The description clearly states the tool performs grounded multi-source research across 1455 structured data sources in one call, decomposing questions into facets routed in parallel. It explicitly contrasts with open-web search and distinguishes from ask_pipeworx as the single-lookup alternative.

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

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

Provides explicit when-to-use and when-not-to-use guidance: recommends ask_pipeworx for single lookups, breaking/current-news topics, and unsigned-in users. Also notes that deep_research is best for broad/multi-part questions over structured data.

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds extensive behavioral details: response structure (leg-by-leg prices, top_spreads_pp), compatibility_warning conditions, temporal_alignment, and skipped_cross counters. It discloses edge cases and mathematical meaningfulness, going well beyond annotations.

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

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

The description is verbose but well-structured with headings for modes, response, and safety fields. Every sentence adds value, though some details (e.g., skipped_cross counters) could be more concise. Overall, it is efficient for a complex tool.

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

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

Given the tool's complexity (3 optional parameters, no output schema), the description is remarkably complete. It explains both input modes, response format, safety fields, and edge cases. The user can understand exactly how to invoke the tool and interpret results.

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

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

Schema description coverage is 100%, and the description adds significant meaning: it explains the topic values list, how explicit parameters override topic, and provides examples. The description clarifies the interaction between parameters, adding value beyond the schema.

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

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

The description uses a specific verb-resource combination: 'Cross-venue spread between Kalshi and Polymarket'. It clearly distinguishes the tool from siblings like 'polymarket_arbitrage' by focusing on cross-venue comparison and detailing two modes (topic and explicit). The resource is precisely defined.

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

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

The description provides clear usage context: two modes for different needs, and warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'. It tells when the tool is useful and when it may yield warnings. However, it does not explicitly compare to sibling tools like polymarket_arbitrage for alternative use cases.

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

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

Annotations already 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?

Beyond the read-only and idempotent annotations, the description discloses valuable behavioral details: unresolved identifiers are explicitly listed under `unresolved`, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple lookup endpoints. These details add significant transparency about what the tool returns and how it behaves under partial failure.

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

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

The description is long but well-structured, with user-quoted examples at the front, clear type breakdowns, and caveats like graceful degradation. Every sentence adds useful information, though it is more verbose than strictly necessary.

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

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

There is no output schema, so the description must explain return values, and it does so thoroughly: CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand, source labels, unresolved field, and fallback behavior. For a tool with this complexity, the description is remarkably complete.

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

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

The schema already covers both parameters comprehensively, so the baseline is 3. The description adds meaning by explaining the accepted value formats for company (ticker, CIK, name) and drug (brand or generic), and what each type returns, enriching the schema's basic 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 defines the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides concrete example queries, names both supported entity types (company and drug), and distinguishes itself from sibling tools by explaining that it supplies the IDs other tools require as input.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID' and describes what each type accepts. It lacks named alternative tools, but clearly implies that other tools consume these identifiers, making the context of use clear.

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

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

Annotations already declare 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.