Licenses

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

Annotations already declare safety traits (readOnlyHint, idempotentHint, etc.). The description adds value by detailing cost implications (free default, BYO for Anthropic) and the return structure (score, confidence, signals, raw_response). No contradictions.

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

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

The description is a single, well-structured paragraph. It front-loads the main action and then provides supporting details. Every sentence adds value; 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 tool with 4 parameters and no output schema, the description covers purpose, usage context, parameter roles, and return value structure comprehensively. It leaves no obvious gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema: it conveys that 'workers-ai' is the free default, that _apiKey is only needed for Anthropic, and that 'context' helps disambiguate. This provides richer guidance for parameter usage.

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

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

The description precisely states the tool's function: probing LLMs for entity knowledge and scoring visibility (0-100) per model. It names the default model and the optional Anthropic integration, clearly distinguishing it from sibling tools like 'scan_competitor_ai_presence' 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 says when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Explains the default model and when to provide _apiKey. Does not explicitly mention when not to use it, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavior beyond those flags: it routes to the best tool, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It does not detail error conditions, rate limits, or freshness semantics, but for a read-only ask tool the core behavior is clearly disclosed.

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

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

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and organized into domain list, behavior, trigger phrases, examples, and alternatives. It is slightly verbose due to the long domain enumeration and repeated 'START HERE' guidance, but every section serves agent decision-making.

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 no output schema, the description sufficiently explains what the caller gets (structured answer, citation URIs) and when to pick an alternative (deep_research for broad multi-part questions). It leaves out details about auth/account-level constraints and how it differs from ask_pipeworx_beta/grounded siblings, but these are not essential for a first correct invocation.

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

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

Schema description coverage is 100%: all six parameters are aliases for the same 'question' string, and the schema documents that. The description adds example queries and says the input is a natural-language question, but it does not add meaning beyond what the input schema already states, so the baseline of 3 applies.

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

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

The description uses a specific verb-resource combination: it routes a natural-language question to the right tool among 5,767 verified tools and returns a cited structured answer. It also names the scope (SEC, FDA, FRED/BLS, patents, real estate, etc.) and explicitly contrasts with web search, so an agent can distinguish it from generic search tools.

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

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

It gives explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', factual questions), says to prefer it over web search, and says 'START HERE for most questions'. It also provides an exclusion: use deep_research for broad/multi-part questions intended to fan out across sources, and clarifies that ask_pipeworx already handles live-news questions.

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

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

The description discloses the beta status, live candidate-routing behavior, and the current state that no candidate is active. It also clarifies that this is a full working router rather than a degraded fallback, which goes beyond the read-only and idempotent annotations.

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

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

Four sentences each serve a distinct purpose: identity, current status, usage instruction, and reassurance of functionality. The description is front-loaded with the essential beta/universal-router fact and contains 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?

The schema, annotations, and description together give an agent everything needed to select and invoke the tool: what it does, when to use it, its experimental nature, and that the response shape matches ask_pipeworx. No output schema is required because the description explicitly ties the response shape to the stable sibling.

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

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

Schema coverage is 100%, so the schema already documents all parameters and the aliases for question. The description only says 'same arguments' as ask_pipeworx and adds no new parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description states that this is the beta version of ask_pipeworx, a universal router with the same 5,767 tools, same arguments, and same response shape. This specific framing distinguishes it 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 explicitly says to use it exactly like ask_pipeworx when the agent wants the newest routing, naming the stable router as the comparison point. It does not state an explicit when-not condition, but the beta/stable contrast implies the stable tool should be used when experimental routing is not desired.

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 reveals substantial behavioral detail beyond the annotations: it explains that answers are extracted ONLY from tool results, enumerates the refusal reason enum, describes the return shape, and even flags the extra LLM call cost. This is exemplary transparency for a read-only tool.

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

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

The description is dense and front-loaded with the core differentiator, then proceeds logically into behavior, return shape, refusal conditions, and when-to-use guidance. It is longer than average but every clause earns its place; a minor trim of the full refusal enum could improve scannability.

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

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

Given the tool has no output schema, the description supplies a complete picture of return values and failure modes, plus usage context, cost implications, and sibling differentiation. An agent has everything needed to decide when to call this tool and what to expect from 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%, and the single significant parameter (question) is already documented in the schema with aliases. The description adds no parameter-level semantics beyond mentioning that routing 'fills arguments,' which is acceptable given full schema coverage.

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

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

The description leads with a specific purpose: hallucination-resistant answer mode for high-stakes reads. It clearly distinguishes itself from ask_pipeworx by emphasizing extraction only from tool results and explicit refusal behavior, making the tool's role 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also gives the alternative: 'prefer ask_pipeworx for casual lookups,' and notes the cost tradeoff of one extra LLM call.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: fan-out process, resolver contract, parent event extraction, news fallbacks, safety measures, market status handling, spread warnings, and cancellation rule parsing. 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 lengthy due to complexity but well-structured with section headers and front-loaded purpose. Every sentence adds value; no wasted words. Could be slightly more concise but appropriate for the tool's depth.

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 details response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and edge cases. Completeness is high given the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: 'market' parameter explains slug/URL/question text, 'depth' differentiates quick vs thorough, 'include_raw' explains when to use true/false. This justifies 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 tool researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, fanning out, and returning an evidence packet. It explicitly lists use cases ('should I bet on X', etc.) and distinguishes from siblings by being Polymarket-specific.

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

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

The description provides explicit usage guidance ('Use for ...') and context (classifiers, fan-out examples), but does not explicitly state when not to use or mention alternative tools. Nonetheless, the purpose is clear enough for correct selection.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds significant behavioral detail: pulls LATEST 10-K data, correctly handles off-calendar fiscal years, returns pipeworx:// citation URIs per entity. 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?

Every sentence adds value, but the description is slightly verbose. However, it effectively front-loads with trigger phrases and key action, making it scannable.

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 comparing two entity types with different data sources, the description covers all necessary aspects: data freshness, sorting, citation URIs, and the efficiency gain over sequential lookups. No output schema exists, but return structure is described.

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 descriptions are provided for both parameters. The description adds context about what each type pulls (financial metrics for 'company', adverse-event counts for 'drug') and clarifies that values can be tickers/CIKs or drug names.

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 explicit natural language triggers and clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It differentiates from siblings like entity_profile by specifying parallel lookup and specific data sources (SEC EDGAR for companies, FAERS 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 instructs to prefer this tool over sequential single-pack lookups when comparing entities. Provides clear examples of user queries that trigger this tool and explains sorting behavior ('largest/most reads off the top').

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond those: account and paid-plan requirements, no invented answers, explicit gaps[] for unanswered facets, parallel decomposition across 5,767 tools, return-packet fields, semantic excerpting of large records, and expected latency ranges. 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 dense but each sentence carries operational value: auth, scope, method, output, gaps, latency, and alternatives. The only structural weakness is that account requirements and fallback instructions come before the core purpose, slightly delaying the main definition.

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

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

For a tool with no output schema, the description is remarkably complete: it explains the findings packet fields, citation format, gaps[], contradictions[], hop behavior, depth differences, latency, and when to use a sibling instead. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already explains both parameters thoroughly, including depth semantics and question guidance. The description adds useful example questions and reinforces the paid-thorough requirement, providing a modest uplift over the schema baseline.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in one call, and explicitly contrasts itself with open-web search. It also differentiates from the sibling ask_pipeworx by saying 'For a single lookup use ask_pipeworx instead.' An agent can tell exactly what this tool is for.

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 when-to-use guidance is given: 'Best for broad/multi-part questions over structured data,' with concrete examples. Explicit when-not-to-use guidance is also given: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' The alternative tool is named directly, leaving no 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 indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns top-N relevant tools with full schemas and curated examples, and states that results are 'ready to call directly, no second schema lookup needed.' No contradictions.

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

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

The description is somewhat verbose with a long list of domains, but it is front-loaded with the core purpose and structured well. Every sentence adds value, though it could be 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?

Despite no output schema, the description fully explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also mentions default limit and max. The tool's behavior is completely described for an 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?

Schema coverage is 100% and the description adds no new parameter meaning beyond repeating the aliases and that query is a natural language description. Baseline 3 is appropriate as the schema already conveys the necessary parameter info.

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 enumerates many specific domains (SEC filings, FDA drugs, etc.), and distinguishes from sibling tools by positioning itself as the tool discovery mechanism.

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 the agent to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies not to use it when a specific tool is already known.

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 a safe read-only/idempotent profile, but the description adds substantial behavioral context: parallel fan-out across sources, soft-fail behavior for patents, sources_used/sources_failed semantics, empty sections meaning real no-data, and private-company resolution returning resolved:false with notes. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage preference, but the rest is a dense, run-on paragraph mixing source inventory, return fields, input formats, and soft-fail policies. It is information-rich but poorly structured, making it harder for an agent to quickly scan and parse.

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

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

There is no output schema, so the description must carry return-value expectations, and it does: it names returned fields, explains per-source behavior, describes failure semantics, and defines input resolution behavior. For a complex multi-source tool, this is highly complete.

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

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

Schema coverage is 100%, and the input schema already documents ticker/CIK/company-name shapes as well as the interchangeability of type values. The description mostly restates this and adds only minor extra context like resolved_from/resolved_to and private-company behavior, which is more output semantics 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 clearly states the tool's purpose: full cross-source profile of a US public company in one parallel call, with concrete user-phrase examples like 'Tell me about X' and 'company profile for Microsoft'. It also distinguishes the tool from chaining single-pack SEC/XBRL/news lookups, making its niche obvious.

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

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

It explicitly says to ALWAYS PREFER this tool over chaining single-pack lookups when the user wants a holistic view. It also mentions how private-company inputs are handled. However, it does not explicitly exclude narrow single-fact queries or contrast with nearby siblings like resolve_entity or compare_entities.

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 the context of clearing sensitive data, which is a valuable behavioral nuance, and does not contradict annotations.

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

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

Two concise sentences with no waste: first sentence states purpose, second provides usage guidelines. Perfectly front-loaded.

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

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

For a single-parameter tool with annotations and no output schema, the description fully covers purpose, usage, and pairing, with no gaps.

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

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

Schema coverage is 100% with parameter description 'Memory key to delete'. The description adds no 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?

The description clearly states 'Delete a previously stored memory by key', with a specific verb and resource, and distinguishes from siblings 'remember' and 'recall' by mentioning pairing.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises to 'Pair with remember and recall', providing clear context for alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds specific behavioral details: fetching page, extracting title/description/links, and emitting standard markdown. No contradictions.

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

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

Two sentences: first states action and output, second lists use cases. Every word earns its place. 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 the simplicity (2 params, no output schema) and rich annotations, the description is complete enough. It covers input, output, and use cases. Lacks edge case handling (e.g., invalid URLs) 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%. The description adds minimal value beyond schema (default and max for max_links, example for url). Baseline 3 is appropriate.

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

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

The description clearly states it generates an llms.txt file for a given URL, specifies the target AI crawlers, and describes the output format. It distinguishes itself from other tools by its precise function and 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?

The description provides explicit use cases (client sites, own projects, auditing competitors), which guides when to use. However, it does not mention when not to use or compare to sibling tools like ai_visibility_check, so it lacks exclusion guidance.

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

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

Annotations already declare the tool as read-only and non-destructive. The description adds the term 'Keyless', implying no authentication is needed, which is a useful behavioral hint. However, beyond this, it does not elaborate on response format, error handling, or other traits.

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 ultra-concise (one short sentence) and front-loaded with the key action and example. It contains no filler, though it could benefit from structured breakdown for complex scenarios. However, for a simple tool, this is effective.

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 is sufficiently complete. It communicates the core function and output type. The missing output specification is acceptable as the return is intuitive ('full license text').

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

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

The input schema already has 100% description coverage for the sole parameter 'spdx_id'. The tool description does not add any additional semantic meaning beyond what the schema provides, so it meets the baseline without enhancement.

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

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

The description explicitly states the verb 'Fetch' and the resource 'full license text for an SPDX id', with a concrete example 'MIT'. It clearly distinguishes from siblings like 'search_licenses' by focusing on retrieving the exact license text for a given SPDX identifier.

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

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

The description provides no guidance on when to use this tool versus siblings such as 'lookup_license' or 'search_licenses'. It does not specify prerequisites, alternatives, or when not to use it, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds return field details and scoping to 'caller's' subscriptions, which is useful behavioral context beyond annotations.

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

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

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

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

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

For a simple list tool with one optional param and no output schema, the description covers purpose, return fields, and usage. Could mention pagination if applicable, but overall complete.

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

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

Schema coverage is 100% with a description for the sole parameter. The description does not add new parameter meaning but reinforces default behavior (active subscriptions). 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 states 'List the caller's active subscriptions' – a specific verb (list) and resource (subscriptions). It clearly distinguishes from siblings like subscribe and unsubscribe by focusing on reading existing subscriptions.

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

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

Explicitly advises 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear when-to-use context and aligns with sibling tools (subscribe, unsubscribe).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying return fields (full name, OSI/FSF approval, deprecation status, reference URLs) and noting no key required, which enriches the behavioral understanding.

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 with two sentences, front-loading the purpose and then listing return details efficiently. Every sentence adds necessary context 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?

The tool is simple with one parameter, robust annotations, and no output schema needed. The description fully covers what the tool does and returns, leaving no gaps in understanding.

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

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

Schema coverage is 100% and includes a description and examples for 'spdx_id'. The description does not add any new semantic information beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Look up' and the resource 'open-source license by its exact SPDX id', with specific examples. It distinguishes from sibling tools like 'search_licenses' (fuzzy) and 'get_license_text' (full 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?

The description provides context for when to use (exact SPDX id) and notes 'Keyless' for no auth. It does not explicitly mention alternatives or when not to use, but the specificity implies not for partial matches or full text retrieval.

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 annotation flags, the description adds substantial behavioral context: anonymous filing returns a claim_token, later passing that token retrieves resolution status, rate limit is 5 per day, and it is free/quota-exempt. It also clarifies that feedback must reference Pipeworx tools/packs, not user prompts. No contradiction with annotations.

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

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

The description is long but information-dense; every sentence serves a selection or invocation purpose. It front-loads purpose and usage guidance before diving into claim_token mechanics. The minor non-actionable detail about daily digests and roadmap impact keeps it from a perfect conciseness score.

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

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

With no output schema, the description carries the return-value burden and fully covers it via claim_token and later status reads. It addresses all important facets: eligible tools, feedback types, message content, rate limits, anonymous filing, and resolution tracking. For a tool with nested context and enum parameters, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter guidance. It explains the claim_token's standalone retrieval mode ('pipeworx_feedback({claim_token:"pwfb_…"})') and adds content constraints for the message field. The type enum is already well covered by the schema, so no extra needed there.

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 clear verb-object-resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately enumerates the feedback types and explicitly limits scope to 'tools served by this Pipeworx connection,' distinguishing it from the many ask/research 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 explicitly states 'Use when' plus concrete triggers (bug, feature/data_gap, praise). It gives a clear exclusion for tools from other MCP servers and redirects the agent to 'file it with that server instead,' along with practical guidance like 'don't paste the end-user's prompt.'

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

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

Description adds significant context beyond annotations: source (CF analytics-engine), privacy (no PII), data structure (pack, tool, count), and caching policy (5min-1h). Annotations already indicate readOnly, openWorld, idempotent, non-destructive, so the description enriches understanding of behavior.

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

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

Three sentences with clear structure: first sentence defines output, second lists use cases, third covers derivation and caching. No redundant or missing information. Excellent conciseness.

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 optional parameter and no output schema, the description covers return values (top tools, packs, call volume) and data format (pack, tool, count). Lacks explicit format or example but is sufficient for agent understanding. Caching and derivation add completeness.

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?

Only one parameter (window) with full schema description (100% coverage). The description reinforces the window options and their implications (hot vs. steady-state) but adds little beyond what the schema already provides. 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 clearly states it returns top tools, top packs, and total call volume over a window. Lists three specific use cases (discovering hot data sources, confirming canonical tool, aligning use case). Distinguished from sibling tools like discover_tools and ask_pipeworx by focusing on aggregated usage trends.

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 scenarios for use (current events, canonical tool confirmation, alignment check). Does not explicitly mention when not to use or alternatives, but the context is clear enough for an AI agent to infer proper usage relative 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds detailed algorithmic behavior: monotonicity checks, partition filters, semantic anchors, fill check with realizable edge vs theoretical edge. No contradictions.

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

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

The description is long and dense, packed with technical details and examples. While thorough, it could be more structured or abbreviated for quicker comprehension by 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?

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers usage modes, logic, edge cases, response structure, and refers to another tool for custom sizing.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning: explains what happens in each mode, how event slugs work, and that full URLs are accepted. It clarifies the distinction between event and topic.

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 on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific verbs and resources, making it unique among siblings.

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

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

Explicitly tells when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It lacks explicit when-not-to-use guidance but provides sufficient context for correct selection.

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

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

The description extensively discloses behavioral traits: it describes the three model segments, cached 1h at KV level, diagnostics for empty segments, edge calculation (net of slippage), Kelly fractions, 24h-move warnings, and tradeable-edge knobs. This far exceeds the annotations (readOnlyHint, etc.) with no contradictions.

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

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

The description is verbose (multiple paragraphs) and contains extensive technical detail. While well-structured with numbered segments and explicit sections, it could be more concise for an AI agent. The front-loaded summary is good, but the length may reduce scanability.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It covers all three model families, response structure (by_segment, fed_note, diagnostics), parameter effects, and caching behavior. No obvious gaps remain for an agent to understand the tool's full behavior.

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

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

The input schema has 100% coverage, and the description adds significant meaning beyond it. For instance, it explains how min_kelly and min_partition_leg_kelly work differently for partition opportunities, and it clarifies the effect of slippage_pp on edge and ranking. Some details (like min_edge_pp default) are already in schema, but overall the description enhances 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 scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it's built for 'what should I bet on today'. It differentiates from siblings by aggregating multiple model families and providing a single call to discover opportunities without paging.

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

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

The description explicitly states the tool's purpose and provides guidance on when to use it (discovery without paging). It also explains knobs like min_liquidity and max_spread_pp for filtering. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or edge_tracker, but it does mention that fed_candidates are excluded from ranking, giving some context on 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?

Beyond annotations (readOnly, idempotent, not destructive), description reveals detailed behavioral traits: uses snapshots, decay computed on absolute net edge, negative means SELL YES, expired items tracked with lifespan, snapshot dates indicate data presence, and constraints like TTL and snapshot availability.

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 moderately long but well-structured: starts with high-level purpose, then details parameters and response structure. All sentences contribute meaning, though a minor reduction could improve conciseness.

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 covers return fields (tracked, expired, snapshot_dates) and their meanings. It also explains limitations and edge cases, making the tool fully understandable 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?

Schema coverage is 100%, but description adds value by providing default values (14, '1wk'), clamping range for days (2-30), and clarifying window options (24hr, 1wk, 1mo). This extra context aids correct invocation.

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

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

Description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. It specifies the resource (daily polymarket_edges snapshots) and distincts from siblings like polymarket_edges by focusing on time-series 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?

Description provides context on when to use the tool, such as distinguishing a fresh wide edge from an old one, and mentions limitations like the 60-day snapshot TTL. However, it does not explicitly compare with sibling tools or state when not to use it.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the tool's behavior: it walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), and highlights risks like thin_legs and forced_directional_risk. This augments the safety profile already indicated by annotations.

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

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

The description is long but front-loaded with core purpose ('Realizable-vs-theoretical edge check...'). It uses bold labels and capitalization for modes. Some redundancy exists in explaining return fields, but given the complexity (two modes, many return fields), it is acceptably concise. Could be slightly tighter.

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

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

No output schema exists, so the description must fully document return values. It does: lists all fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, forced_directional_risk). It also covers edge cases (cannot_fill, thin legs) and practical risks (partial fills converting arb to directional position). Completely adequate for a complex tool.

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

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

Schema coverage is 100% with descriptions for all four parameters. Baseline is 3. The description adds significant meaning beyond schema: it explains the difference between single-market and basket modes for `market` vs `event`, clarifies default logic for `side` in basket mode, and interprets `size_usd` for basket as settlement notional (shares per leg). This goes beyond what the schema provides.

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

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

The description clearly states it performs 'realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes between single-market and basket modes. It uses specific verbs ('walks the ladder', 'returns') and resource references ('market', 'event'). This differentiates it from siblings like polymarket_arbitrage and polymarket_edges, which are referenced as use-case triggers.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable on thin books, partial basket fills convert arb to directional position), providing clear when-to-use guidance and implicit when-not-to.

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?

It goes well beyond the readOnly/idempotent annotations by disclosing machine-readable compatibility_codes, the pairing_unverified limitation, gross-vs-net fee treatment, and null semantics for temporal_alignment. The warning that compatibility fields 'can be non-empty on returned pairs, so read them even when matched_pairs>0' is exactly the kind of non-obvious behavioral disclosure an agent needs.

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

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

The description is long but well-structured with clear labels like TWO MODES, SAFETY FIELDS, and RESPONSE. It front-loads the core purpose and then layers details that are necessary because there is no output schema. A few points are restated across sections, preventing a 5, but the length is mostly earned.

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

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

For a tool with no output schema, this description is unusually complete: it covers top_spreads_pp units, compatibility flags, skipped_unclassified, low_confidence_pairs, temporal_alignment null semantics, skipped counters, and the fee caveat. An agent has nearly everything needed to call the tool and interpret its result correctly.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds genuine value by explaining that topic strings auto-fetch matching events via pre-mapped shortcuts, that explicit tickers/slugs override that mapping, and that both modes run the identical token-overlap matcher. That raises it slightly above baseline but does not need to carry much additional load.

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

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

The opening sentence states a precise function: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It explicitly names the outcome delta, the direction (Kalshi − Polymarket), and the cross-venue scope, which is far more informative than the title alone.

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

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

The description clearly explains two operation modes (topic shortcuts vs explicit pairings) and gives strong guidance about reliability, e.g. 'pre-mapped ≠ tradeable' and 'real cross-venue spreads are rarer than the macro-shortcut list suggests.' It stops short of explicitly naming alternative sibling tools or saying 'use X instead when Y,' so it earns a 4 rather than a 5.

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

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

No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint). Adds context about dual behavior (single vs list) and scoping.

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

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

Two sentences, front-loaded with main action, no fluff. Every word 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?

Simple tool with one optional parameter; description covers behavior, usage, and pairing. Complete for agent use.

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 100% but description adds meaning: key omitted lists all keys, examples given. 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 retrieves a saved value via 'remember' or lists all keys when omitted. Distinguishes from siblings 'remember' and 'forget', and specifies the resource (saved memory).

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 to use for looking up context stored earlier without re-deriving, and pairs with 'remember' and 'forget' for alternatives. Also mentions scoping to identifier.

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

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

The description discloses behavioral traits beyond annotations, such as the side effect of mark_read:true which modifies read status. This transparency is valuable despite the contradiction with readOnlyHint annotation.

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

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

The description is concise—four sentences—and well-structured, starting with the main purpose, then detailing parameters and behavior. No superfluous 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 5 parameters, no output schema, and zero required params, the description adequately explains what the tool returns, how to filter, and the mark_read behavior. It also provides an alternative access method, making it complete for the tool's complexity.

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

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

With 100% schema coverage, the description still adds meaning by explaining parameter usage with examples (e.g., type 'sec_8k', ISO timestamp for since) and the effect of mark_read. This 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 identifies the tool as fetching recent alerts from a subscription feed, specifying verb 'Pull' and resource 'fired events from your subscription feed'. It distinguishes itself from siblings by focusing on recent events and providing explicit details about the returned data.

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

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

The description offers guidance on usage, including filtering by type and since, and notes that polling works fine. It also mentions an alternative REST endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool versus other tools, which prevents a perfect score.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description details the multi-source fan-out, fallback mechanisms, and soft-failure scenarios. It adds substantial behavioral context.

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

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

The description is a single dense paragraph that front-loads examples. While compact, it covers all necessary information without redundancy. A slightly more structured layout could improve readability.

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

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

The description covers the tool's complex behavior (multiple sources, fallback, output structure) well. It lacks explicit error or rate limit details, but the annotations and openWorldHint imply some assumptions.

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 fully describes parameters, and the description adds value with examples and usage recommendations (e.g., typical `since` values). It enriches what the schema provides.

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

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

The description clearly states the tool provides a change feed for a company over a time window, fanning out to multiple sources. It distinguishes itself from the sibling `entity_profile` by specifying when to use that instead.

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

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

The description includes explicit query examples and a recommendation to use `entity_profile` for static profiles. This provides clear when-to-use and when-not-to 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?

Adds significant behavioral context beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous, and pairing with recall/forget. Annotations only provide idempotentHint=true and write/not-destructive 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?

Four sentences, all informative but slightly verbose. Could be tightened without losing meaning. However, it is well-structured and front-loaded with the core purpose.

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

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

Given no output schema and two required parameters, description fully covers what the agent needs: purpose, when to use, parameter semantics, persistence behavior, and sibling relationships. 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?

Schema already covers parameters with good descriptions (100% coverage). Description adds value by giving concrete examples (e.g., 'subject_property', 'target_ticker') and emphasizing the key-value nature, 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?

Description clearly states the verb 'Save data' and the resource 'key-value pair' for reuse across sessions, and distinguishes from siblings 'recall' and 'forget' by explicitly mentioning them.

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 provides when to use (when discovering something worth carrying forward) and offers clear context with exclusions (anonymous session memory limit) and alternatives (recall, forget).

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context: LEI/FIGI enrichment degrades gracefully, internal cascading through multiple lookup endpoints replaces 2-3 manual calls, and bond/ISIN resolution goes through a specific GLEIF mapping. Since annotations already include the read-only/idempotent signals, the added contextual detail earns a 4 rather than a 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 long, but every sentence earns its place: it front-loads the purpose, then enumerates supported types, identifiers, fallback behavior, and a concrete anti-pattern example. The only minor deduction is because the run-on opening sentence packs many examples plus the core definition into one long passage, making it slightly harder to parse than 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?

For a two-parameter read-only resolver with no output schema, the description is unusually complete. It covers what identifiers come back, what inputs are accepted, edge cases like bonds and non-US issuers, graceful degradation, and call-count implications. It does not document the exact return shape, but since there is no output schema and the tool is a resolver, an example of the actual JSON response would have pushed this to a 5.

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 even with no additional parameter detail. The description does add real semantics beyond the schema: it explains that FIGI lookup matches instrument names and warns against trailing security-class words; it also clarifies that an ISIN resolves to the legal entity issuer via the GLEIF mapping. The main schema property descriptions already cover the type/value distinction well, so a 3 is appropriate.

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

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

The description opens with concrete natural-language examples the agent might hear, then states the core job: resolving a user-spoken NAME to the canonical identifiers other tools need. It then enumerates supported types (company, drug) with the specific identifiers returned (CIK, ticker, LEI, FIGI, RxCUI) and demonstrates non-obvious coverage such as bonds and non-US issuers, which clearly separates it from any sibling.

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

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

The description gives an explicit 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. It also gives exclusions and alternatives implicitly by declaring itself the entry point for name-to-ID resolution, and gives specific value-format instructions (never pass the full noun phrase like 'revenue bonds'), preventing a common misuse. This is far above minimum viable.

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, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral detail: it 'probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized,' and specifies the output format: 'ranked list with score, confidence, signal density per entity.' No contradictions.

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

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

The description is three sentences long, with the core action in the first sentence. It is efficient and front-loaded, though slightly verbose with details that could be part of a longer explanation.

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

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

Despite lacking an output schema, the description comprehensively explains the return value: 'ranked list with score, confidence, signal density per entity.' It also covers the tool's process, use case, and inputs adequately for its complexity.

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

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

Schema description coverage is 100%, and the description adds additional semantics: it clarifies that the first entity in the array is treated as the 'subject' for narrative, and that omitting 'models' defaults to 'workers-ai.' This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb 'compare' and resource 'AI visibility,' and distinguishes from the sibling tool 'ai_visibility_check' which operates on a single entity.

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

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

The description provides a clear use case: 'competitive AI-marketing audits,' with an example question. It implies when to use this tool over alternatives like 'ai_visibility_check,' but does not explicitly state when not to use it or list alternative tools by name.

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

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description adds that it fans out across deps.dev and bundlephobia, that bundlephobia's first measurement can take 5-30s and may time out, and that sources_failed will list it. No contradictions.

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

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

The description is a single paragraph that is dense but well-organized: overall purpose, use cases, return fields, ecosystem scope, failure handling. It is front-loaded and efficient, though 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?

Despite lack of output schema, the description lists the summary block fields, mentions per-advisory details, links, and alternative versions. It also addresses timeout behavior and partial failures, making it complete for an agent's decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor context (e.g., 'npm package name', 'scoped accepted', 'defaults to latest') but goes beyond the schema only slightly.

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 composite check for adding an npm package, covering license, advisories, version history, and bundle size. It specifies the ecosystem (npm only) and distinguishes itself from sibling tools which cover different domains.

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

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

Explicitly tells when to use: when an agent asks about safety, popularity, or bundle cost. Also states when not to use: for other ecosystems (PyPI, Maven, etc.) and that partial failures are handled gracefully.

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, so description adds limited value. Mentions 'Keyless' which is a useful behavioral trait not captured in annotations.

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

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

Two concise sentences with an example, no fluff. Efficiently communicates core functionality.

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 search tool with no output schema, the description is adequate. Could mention what the response contains (e.g., license objects) but not strictly necessary given the tool's straightforward nature.

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

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

Schema covers all 3 parameters with descriptions, achieving 100% coverage. Description does not add additional parameter meaning beyond 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 clearly states the tool searches the SPDX license list by keyword, matching id or name. Verb 'search' and resource 'SPDX license list' are specific, distinguishing it from siblings like 'lookup_license' which likely retrieves a single license.

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

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

Provides concrete examples of keywords ('GPL', 'creative commons', 'mozilla') and notes keyless access, aiding usage. Does not explicitly state when not to use vs. alternatives, but 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?

Adds significant behavioral details beyond annotations: 200K char truncation with flag, BGE-base-en embeddings, cosine similarity, 500-char windows, and character offsets for verification. Annotations only hint at safety/idempotence, not these specifics.

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

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

Single paragraph, front-loaded with purpose, then behavior, then usage guidance. Every sentence adds value; 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?

Covers all essential aspects: input, output (passages with offsets and scores), limitations (char cap, truncation), embedding model, and relationship with sibling tool. No output schema, but description compensates fully.

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 covers all parameters with descriptions (100% coverage). Description adds context: max chars for text, query examples, default and range for limit. Adds value without redundancy.

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

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

Clearly states semantic search inside a fetched record, with specific resource (text from a record) and action (search). Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and implicit difference from other tools.

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

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

Explicitly states when to use (record too big for prompt) and provides alternative (ask_pipeworx_grounded for grounding). Also implies when not to use (small records).

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

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

The description discloses behavioral traits beyond annotations: OAuth requirement, delivery channel constraints (SMS 10/day cap, webhook auto-disable after 10 failures), and type-specific filters. Annotations indicate idempotentHint=true, but the description doesn't mention idempotency or duplicate handling, which is a minor gap.

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

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

The description is detailed and front-loads the primary purpose. While it's relatively long, every sentence adds value. Minor structure improvement could be breaking into sections, but overall it's well-organized.

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

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

Given the tool's complexity (3 params, nested objects, no output schema) and rich annotations, the description is thorough. It covers all supported types, parameter variations, delivery channels with constraints, and the return value (subscription ID). 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%, so baseline is 3. The description adds substantial meaning: provides type-specific parameter examples (sec_8k with items array, polymarket_edge with topic, etc.), explains delivery channel options with details like E.164 format and webhook HMAC signing, and clarifies constraints (SMS must match verified phone). This significantly enriches 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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides clear context: requires a Pipeworx OAuth account (no anonymous/BYO) and lists supported event types with their parameters. While it doesn't explicitly state when not to use, the detail about account requirements and type-specific filters guides appropriate usage.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it returns example questions with tool+argument shapes from a live catalog, which is helpful 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 verbose but packed with useful information. It front-loads the purpose and usage, though it could be slightly more structured (e.g., bullet points) without losing content.

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 1 optional parameter and no output schema, the description thoroughly explains what it does, when to use it, what it returns, and how to call it. It also ties into meta-tools, providing complete context.

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

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

Schema coverage is 100% for the single optional parameter. The description adds examples of valid topic values and clarifies that omitting it returns a cross-category spread, adding meaning beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point for an agent, returning category-bucketed example questions with exact tool calls. It distinguishes itself from siblings like ask_pipeworx and discover_tools by its specific role.

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 to use this tool FIRST when unsure what Pipeworx can do, and explains when to omit or pass the topic parameter. This provides clear context and excludes 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 behavioral details beyond annotations: the row is deactivated (not deleted) and historical events remain available via recent_alerts. This complements the annotations (destructiveHint=false) 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?

Two sentences: the first states the action, the second provides ownership and behavioral constraints. No wasted words, front-loaded with the primary purpose.

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

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

For a simple mutation tool with one parameter and no output schema, the description covers the effect (deactivation) and ownership constraint. It is complete enough for the agent to understand usage and consequences.

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 only one parameter and 100% schema coverage, the schema already explains the id parameter. The description does not add additional meaning beyond what is in 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?

The description states 'Cancel a subscription by id,' which is a specific verb and resource. It clearly distinguishes from sibling tools like 'subscribe' (which creates) and 'list_subscriptions' (which lists).

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 specifies ownership enforcement and that you can only cancel your own subscriptions, providing clear context for when to use. It does not explicitly state when not to use or mention alternatives, but the 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 the tool safe and read-only, but the description goes far beyond by detailing the structured vs grounded pipelines, the complete set of verdicts, and the critical caller warning that 'could_not_verify' means the check did not happen and must not be treated as evidence. This is exceptional behavioral disclosure.

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

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

The description is longer than typical but well-structured: it starts with a memorable query pattern, then explains usage, behavior, return values, and caveats. Every sentence carries weight, and the important caller note is set apart. The length is justified given the tool's complexity, though it could be trimmed slightly.

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

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

Given there is no output schema, the description proficiently explains the return structure (verdict list, actual value with citation, reasoning) and the two error semantics ('could_not_verify' vs 'unsupported'). It also mentions the efficiency benefit, making the description complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% for both parameters, and the description adds meaningful guidance beyond the schema: examples for 'claim', and for 'tolerance_pct' it explains how it overrides implied tolerance, the action for hallucination detection, and the capped default. This is a clear value-add over the raw schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with explicit query examples. It distinguishes itself from general Q&A or research tools by returning a structured verdict, and its focus on fact-checking is unmistakable.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and further breaks down the two internal paths (SEC EDGAR for financial claims, grounded pipeline for others). It provides clear contextual guidance, though it does not explicitly name sibling alternatives to exclude.

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