Data Lv

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable behavioral context: default model is free, Anthropic requires BYO key and charges, returns per-model details. 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, front-loaded with core purpose, no fluff. Each sentence adds value: what it does, default/optional behavior, return structure, use cases.

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

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

Despite no output schema, description explains return format (per-model fields + combined view). Covers all 4 parameters meaningfully. Lacks only minor details like rate limits, but annotations imply idempotent and read-only, so not critical.

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

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

Schema description coverage is 100% with good property descriptions. Tool description enriches: explains _apiKey passed through to Anthropic, context helps disambiguate, entity examples provided. Adds meaning 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?

States specific verb 'Probe' and clear resource 'LLMs for what they know about a business/brand/product/topic', with explicit output 'score visibility (0-100) per model'. Distinct from siblings like ask_pipeworx which are about 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?

Clearly states when to use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains default model and optional Anthropic probe. Does not directly compare to sibling tools but context is sufficient given the unique purpose.

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

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

Annotations already cover read-only, idempotent, and open-world safety, so the bar is lower. The description adds useful behavioral context: it auto-selects among thousands of tools, fills arguments, and returns pipeworx:// citations. It does not mention failure modes or cost limitations, but that is not critical given the strong annotation coverage.

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 key preference and domain list, making it easy to scan. However, it is somewhat repetitive: 'even if web search could also answer it' appears twice, and 'Use whenever' overlaps with 'START HERE for most questions'. The examples list is useful but slightly long.

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

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

Despite having no output schema, the description covers what the tool does, when to use it, what kinds of questions are appropriate, how routing works, alternatives, and what the return format is (structured answer with citation URIs). An agent has enough context to invoke it correctly and interpret the result.

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 documents the single question parameter and its aliases with natural-language semantics, so the baseline is 3. The description goes slightly beyond the schema by providing concrete example queries and a list of query intents that clarify exactly what kind of input is expected.

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

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

The description clearly states that the tool routes factual questions to one of 5,798 tools across verified sources and returns structured answers with stable citation URIs. It lists concrete domains and example queries, making the purpose far more specific than the title and distinguishing it from generic web search and the sibling deep_research tool.

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 instructs to prefer this tool over web search for authoritative, current, or historical data, and provides trigger phrases like 'look up', 'find', and 'get the latest'. It also gives explicit alternatives: deep_research for broad/multi-part questions, and notes that news/sentiment queries are already handled by ask_pipeworx's news packs.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that candidate routing improvements may be enabled live, that no candidate is currently active, and that the tool currently behaves identically to ask_pipeworx. It also clarifies that it is a real, working router rather than a fallback or stub, which is valuable behavioral context for an experimental 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 information-dense and front-loaded with the core purpose, then adds current state and usage guidance. It could be slightly tighter, as 'matches ask_pipeworx exactly' and 'use it exactly like ask_pipeworx' convey overlapping ideas, but each sentence contributes distinct operational context.

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?

This is a beta router with high operational nuance, and the description covers the essential context: what it is, how it relates to the stable version, whether a candidate is active, and how results are evaluated. It even addresses the likely concern that a beta tool might be a stub by affirming it is fully functional. With no output schema, referencing ask_pipeworx's response shape is sufficient.

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

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

Schema description coverage is 100%, and the schema already documents the single question parameter and its five aliases. The description adds only the meta-information that the arguments match ask_pipeworx, providing no additional parameter-level meaning, 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 identifies the tool as the beta version of ask_pipeworx, a full universal router with the same 5,798 tools, arguments, and response shape. It explicitly differentiates it from the stable ask_pipeworx by its experimental routing improvements, so an agent can distinguish it from the primary 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 explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It names the stable alternative and provides a selection condition, though it stops short of explicitly stating when not to use it, such as when stable production behavior is required.

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 state readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context beyond that: hallucination resistance, refusal behavior with enumerated refusal_reason values, exact success return shape, and an extra LLM call cost. It also clarifies what happens when data doesn't directly answer—an explicit refusal instead of fabrication. 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 carries distinct value: primary behavior, routing mechanism, return shape, refusal reasons, usage guidance, and cost tradeoff. The key differentiator ('Hallucination-resistant') is front-loaded, and the rest is dense without padding. It is long but information-dense and appropriately structured.

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

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

Given there is no output schema, the description fully compensates by specifying the success return object and refusal object with all relevant fields and possible refusal_reason values. It also covers routing, cost, and usage boundaries. Nothing an agent needs to decide whether and how to call this tool 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 fully documents the single question parameter and its aliases. The description does not add parameter-level detail, but it does provide broader context about how the question is used (routing to tools and fetching data). This matches the baseline 3 for a fully schema-covered parameter.

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

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

Opens with 'Hallucination-resistant answer mode for high-stakes reads,' stating a specific verb (answer), resource (Pipeworx tool results), and a distinctive behavior (grounded extraction). It differentiates itself from ask_pipeworx by emphasizing it 'EXTRACTS the answer using ONLY what the tool result contains,' so an agent immediately understands what makes this variant unique.

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 it: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete high-stakes examples. It also gives an exclusion rule: 'prefer ask_pipeworx for casual lookups,' and notes the extra LLM call cost as a deciding factor. This fully covers when-to-use vs the sibling alternative.

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

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

The description extensively details behaviors beyond annotations: resolution confidence, parent event extraction, news fallback, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread warnings, and cancellation rules. No contradictions with annotations.

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

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

The description is lengthy but well-structured with labeled sections (RESOLVER CONTRACT, PARENT_EVENT, etc.). It is front-loaded with purpose and usage. While every sentence adds value, some details could be summarized to improve conciseness for quick reading.

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 response shapes (market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads), and provides detailed examples for fan-outs. It is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds meaningful context: clarifies the 'depth' enum's default and effect, explains 'include_raw' usage, and provides input examples for 'market'. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, listing input types (slug, URL, question text) and use cases. It implicitly distinguishes from siblings like polymarket_arbitrage but does not explicitly contrast 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?

The description explicitly says 'Use for "should I bet on X"...' and provides classifiers and fan-out examples. It lacks explicit exclusions (e.g., 'do not use for...'), but mentions closed markets and low-confidence scenarios as blocking paths.

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

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

Annotations already declare read-only, open-world, idempotent. Description adds data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and citation URIs, providing rich 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?

Description is somewhat long but every sentence adds value. Front-loaded with examples and key guidance. Slight opportunity to tighten, but still efficient.

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

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

For a 2-param tool with no output schema, description covers return format (paired data + citation URIs), sorting, entity-specific data, and usage constraints. Complete for an AI agent to use correctly.

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

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

Despite 100% schema coverage, description adds meaning: explains what each enum type pulls, how to format values (tickers/CIKs vs drug names), and reinforces min/max constraints.

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 does side-by-side comparison of 2-5 companies/drugs, providing example trigger phrases and distinguishing between entity types. This is specific and differentiates from siblings like entity_profile.

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 'ALWAYS PREFER over sequential single-pack lookups' and warns against sequential lookups, providing clear when-to-use guidance with examples.

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 the tool is read-only, idempotent, and non-destructive. The description adds the behavioral detail that it returns metadata including resources and resource_ids, which is sufficient for understanding the tool's effect. 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 sentence that front-loads the purpose and includes all necessary information without unnecessary words. Highly concise and efficient.

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

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

For a simple read operation with one parameter and no output schema, the description is complete. It explains what the output includes, and the annotations cover safety. 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 coverage is 100% and the description reiterates the parameter's purpose but adds the context 'from search_datasets', which provides additional semantic meaning about where the id comes from. This adds slight value beyond the schema.

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

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

The description clearly states the tool's function: showing full metadata for a Latvia Open Data dataset by id or name. It specifies the source (from search_datasets) and what is included (all resources and their resource_ids), effectively distinguishing it from sibling tools like search_datasets.

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

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

The description implies the tool is to be used after search_datasets by referencing 'from search_datasets'. It provides clear context for when to use, though it does not explicitly state when not to use or mention alternatives. Still, the guidance is adequate.

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

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

Despite readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral context: like not inventing findings, returning gaps[], contradictions[], hop fields, citation_uri availability, semantic excerpting, estimated latency ranges, account/depth requirements, and parallel routing mechanics. This goes well beyond the annotations and gives the agent a realistic model of what the tool does internally.

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 information-rich, but it is long and slightly meandering; the first sentence packs several concepts including a URL and plan details, followed by multiple parentheticals and em-dash clauses. It front-loads the most important facts well, but the sentence flow is somewhat convoluted (e.g., 'not head-truncated', 'so a citation you get back is always fetchable'). Every sentence earns its place, but structure could be tightened.

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

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

Given that there is no output schema, the description compensates thoroughly by describing what a findings packet includes (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field). It also covers failure behavior ('never invented', 'gaps[]'), latency expectations, authentication, tier limitations, and input format. This is a complete picture for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so both parameters are already documented; however, the description significantly enhances the depth parameter semantics by explaining the practical meaning of quick/standard/thorough: number of facets, single-hop vs gap-recovery vs iterative chasing, contradiction scanning, and paid status. This adds real decision-making value beyond the enum descriptions. The question parameter is contextually explained as supporting broad/multi-part decomposition, which is the tool's core purpose.

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

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

The description clearly states the tool's specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call'. It explicitly distinguishes from open-web search and names a sibling alternative, ask_pipeworx, making it easy for an agent to understand when to select this tool. The examples of broad questions further clarify intended use.

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 sign-in requirements and alternative guidance: 'ACCOUNT REQUIRED... If you are not signed in, use ask_pipeworx instead'. It also contrasts with open-web search and suggests the best use case: 'Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx.' This gives clear when-to-use and when-not-to-use framing.

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=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: returns top-N tools with full schemas and curated examples, and each result is ready to call directly. No contradiction exists.

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

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

The description is a single paragraph with a clear front-loaded purpose. It includes a list of domains and details about the output. It is slightly long but all sentences earn their place, and the most critical information appears first.

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

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

Given the absence of an output schema, the description fully explains the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also notes that no second lookup is needed. This is complete and appropriate for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema for parameters; it repeats the alias list but provides no additional semantics. However, it does reinforce that 'query' accepts natural language, which is already in the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples (SEC filings, FDA drugs, etc.) and contrasts with siblings by advising to call this first when exploring many tools. This enables an agent to quickly understand and select it.

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 when you need to browse, search, look up, or discover what tools exist for: [list of domains]' and 'Call this FIRST when you have many tools available and want to see the option set.' While it doesn't explicitly state when not to use or compare to alternatives like search_datasets, the guidance is clear and actionable.

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

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

Annotations already mark it readOnly/idempotent/non-destructive, and the description goes well beyond that: it discloses parallel fan-out across sources, the sources_used/sources_failed semantics, USPTO API sunset soft-fail behavior, expected-empty FDA sections for small-molecule companies, and the resolved:false response for private companies. 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 and front-loaded with the core behavior and usage directive before enumerating sources and return fields. There is minor redundancy with the schema and some repeated examples, but every section contributes useful operational detail for a complex tool.

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

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

Given no output schema, the description thoroughly enumerates the returned fields, source coverage, failure semantics, edge cases, and accepted input shapes. An agent has enough context to invoke it correctly and interpret results even for unusual cases like private companies or empty FDA sections.

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 concrete examples (AAPL, zero-padded CIK, Moderna), clarifies that type and value are interchangeable, and explains name resolution via SEC EDGAR. This goes beyond the schema's bare parameter descriptions.

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

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

The description states a specific verb and resource: it profiles a US public company across many sources in one parallel call. It differentiates itself from chained single-pack lookups and explicitly frames itself as the preferred holistic option, so an agent can distinguish it from narrower 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?

It gives explicit when-to-use signals with concrete user phrasings like 'Tell me about X' / 'research Acme' and instructs to ALWAYS PREFER it over chaining single-pack lookups when a holistic view is requested. It also covers the private-company edge case and what happens then, which is effectively a when-not caveat.

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 the description aligns, adding context about clearing stale/sensitive data. No contradictions, but could mention if deletion is reversible. Overall clear.

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

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

Two sentences with no fluff. The first sentence immediately states the action, followed by usage guidance. Perfectly sized and 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?

Given the simple tool with one parameter, comprehensive annotations, and no output schema, the description covers usage, purpose, and relationships to siblings completely.

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

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

Schema coverage is 100% with a description for 'key' as 'Memory key to delete.' The description adds no further semantics beyond what schema provides, 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 'Delete a previously stored memory by key,' which is a specific verb-resource pair. It clearly distinguishes from sibling tools 'remember' (store) and 'recall' (retrieve).

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember' and 'recall,' providing clear context and 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral detail beyond annotations: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', aligning with the safe, idempotent nature.

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

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

Two sentences plus a bullet line of use cases. Front-loaded with action, no redundant words. Every sentence serves a purpose.

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

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

Tool has 2 parameters (1 required), no output schema. Description covers what the tool does, what it outputs ('single text blob ready to drop at site-root/llms.txt'), and use cases. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'Fetches the page, extracts title/description/key links' and 'maximum of link entries' implicitly refers to max_links, but does not add significant meaning beyond the schema descriptions. Adequate, not exceptional.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' for any URL, specifying the verb, resource, and context. It uniquely identifies the tool's purpose among siblings (e.g., scan_competitor_ai_presence) without confusion.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It does not include when-not-to-use or alternatives, but context is clear enough given sibling differences.

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, destructiveHint. Description adds context by listing the return fields, which is useful 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 concise sentences, no wasted words, front-loaded with 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 low parameter count, the description adequately lists return fields and provides usage context, making it complete for this simple tool.

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

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

Schema coverage is 100% with a clear description for the only parameter (include_inactive). Description does not add meaning beyond what's 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 clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when and why to use the tool.

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

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

Annotations are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), providing minimal behavioral signal. The description compensates richly: filing returns a claim_token, you can pass it back later to read resolution status, rate-limited to 5 per identifier per day, free and does not count against quota, and the team reads digests daily. This adds substantial behavioral context beyond the structured fields, with no contradiction.

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

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

The description is longer than average but every sentence contributes: purpose, usage triggers, exclusion, filing guidance, claim_token mechanics, rate limit, and cost. It is front-loaded with the core purpose and structured logically. While a bit dense, it earns its length given the tool's complexity and lack of output schema.

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

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

Despite having no output schema, the description fully covers the return value behavior (claim_token) and how to consume it later. It addresses rate limits, quota, scope boundaries, and response semantics. For a feedback tool with nested context objects and four parameters, the description leaves no critical ambiguity about when or how to use it.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the claim_token round-trip pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and giving message field guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). It doesn't redundantly repeat schema descriptions but enriches usage semantics, justifying a 4.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this from sibling query tools (ask_pipeworx, query_resource) by focusing on feedback submission. The title and description align, and the purpose 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?

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This is textbook usage differentiation with a named alternative.

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

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

Annotations already indicate safe read operation. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching policy (5min-1h depending on window). This goes beyond annotations to build trust.

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

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

Three well-structured sentences with bullet points for use cases. Every sentence adds value; no wasted words. The description is front-loaded with the core function.

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 (1 optional param, no output schema), the description fully covers purpose, usage context, and behavior. It answers what, when, and how to use, leaving no significant 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% for the single parameter 'window', including enum values and description. The description reinforces usage nuance: shorter windows for hot topics, longer for steady-state demand, adding semantic value.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window. It distinguishes from sibling tools by focusing on aggregated call volume from AI agents, not generic search or entity profiles.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. While it lacks explicit when-not-to-use guidance, the use cases are clear and helpful.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details behavioral traits: the scan logic (monotonicity, partition checks, semantic anchor, partition filter), the fill check against live CLOB depth, and the conditions under which signals should not be acted upon. No contradictions with annotations.

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

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

While the description is lengthy, every section is justified by the tool's complexity. It is well-structured with clear separation of modes, filters, and fill checks. Minor redundancy could be trimmed, but overall it is informative 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 the lack of output schema, the description compensates by detailing the response structure (opportunities array, partition_check fields). It covers all modes, edge cases (semantic anchor, placeholder filter, fill check), and provides enough detail for correct invocation and interpretation.

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 tool description adds significant value by explaining that `event` selects single-event mode with slug/URL examples, `topic` enables cross-event scanning with seed question examples, and elaborates on their respective behaviors.

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 tool's purpose is explicitly stated: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges or polymarket_fill_risk by specifying its unique methodology and modes of operation.

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 comprehensive usage guidance: when to call with no arguments (trending scan), with `event` (single-event mode with specific slug examples), and with `topic` (cross-event scanning). It explains why cross-event mode is beneficial and warns when not to trade (realizable_edge_pp ≤ 0). It also references a sibling tool for custom sizing.

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 extensive behavioral details: caching strategy (1h KV), response structure (by_segment, diagnostics), edge calculation (slippage, Kelly fractions), tradeable-edge knobs, and Fed bets disclaimer. No contradictions with annotations.

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

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

The description is lengthy but every sentence adds value. It is front-loaded with the core purpose. Technical details like model formulas and Kelly caps are included but could be slightly more concise; however, they are relevant for correct tool usage.

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 thoroughly explains the response structure (by_segment with three segments, diagnostics, fed_candidates) and the fields in each opportunity. The tool has 9 parameters with detailed guidance, making it complete for complex usage.

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 detailed descriptions. The description adds extra context for several parameters, e.g., slippage_pp explains Polymarket's zero fees and bid/ask spread, and min_partition_leg_kelly clarifies why min_kelly does not apply to partition arbs. This adds value beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes three segments (model_driven, structural_arbitrage, concentrated_longshot) with detailed explanations, clearly differentiating from siblings like polymarket_arbitrage.

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

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

The description is built for 'what should I bet on today' and guides agents to discover opportunities without paging through hundreds of markets. It explains when to use filters (e.g., min_liquidity, max_spread_pp) but does not explicitly compare to 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 already mark it as read-only, open-world, idempotent, non-destructive. The description adds behavioral details: reads snapshots, returns time-series, trend, decay, expired opportunities, and snapshot dates. No contradiction.

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

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

The description is front-loaded with the core purpose and is well-structured. It is somewhat lengthy but every sentence provides value; minor tightening could improve conciseness without losing detail.

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

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

Despite no output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) and covers limitations (TTL, start date, daily closes). No gaps 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% with descriptions for both parameters. The description adds default values and clamping for 'days', and explains the 'window' parameter's meaning. This adds meaning beyond schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge age and trend. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on time-series and decay 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?

The description explains when to use the tool (to assess if an edge is fresh vs. old) and implies when not to use it (intraday not supported). It does not explicitly list alternatives but context makes the complementary nature 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context beyond these: it reveals that the tool 'walks the ladder' and returns verdicts (clean|degraded|cannot_fill), explains that partial basket fills convert arb into unhedged directional positions, and mentions forced_directional_risk. There is 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 fairly long but well-structured with clear mode separators (SINGLE-MARKET, BASKET) and bullet-like formatting. It is front-loaded with the core purpose and each section adds unique information. While dense, it avoids redundancy and earns its length. It could be slightly more concise, but it remains readable.

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

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

Despite lacking an output schema, the description exhaustively lists the return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc. for single-market; theoretical_sum, capture_ratio, thin_legs, etc. for basket). It also includes warnings about risk and edge cases. Given the complexity of dual modes and the absence of an output schema, this is a fully complete description.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant extra context: it clarifies that `size_usd` has different interpretations for single-market (max spend vs target proceeds) versus basket (settlement notional), and explains the default `side` logic for basket mode. This goes beyond the schema descriptions and meaningfully aids correct 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 begins with a clear verb+resource pairing: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to clarify its unique role. This meets the highest standard of differentiation.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also specifies that one of `market` or `event` is required, and explains the consequences of not using it (partial fills leading to directional risk). However, it does not explicitly state when not to use the tool, 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?

The description goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations: it discloses compatibility warnings, machine-readable codes, unclassified-leg exclusion, temporal alignment semantics, fee treatment, and gross vs net spread. This is exemplary behavioral transparency for a read-only but semantically complex 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 long but structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, fees_note), and the most important purpose statement is front-loaded. Every section conveys non-redundant information required for correct use. It is not concise, but the complexity of the tool justifies the density.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: leg-by-leg prices, top_spreads_pp, compatibility_codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and fees_note. For a tool with this many conditional behaviors and edge cases, the description is remarkably complete.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds genuine meaning by explaining that explicit parameters override topic-mapped sides, that both modes run the same matcher, and how the topic shortcuts map to events. It could be slightly clearer about whether both explicit parameters must be supplied together, but overall it adds value beyond the schema.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with explicit modes for pre-mapped topics and custom pairings. It distinguishes itself from related tools by naming the venue pair and the matching mechanism. The verb is implied ('returns', 'runs'), but the resource and scope are unambiguous.

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

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

The description gives clear usage context: use 'topic' for 10 pre-mapped macro shortcuts and explicit ticker/slug for custom pairings. It also warns that pre-mapped topics are not necessarily tradeable. It does not explicitly compare against sibling tools like polymarket_arbitrage, but the mode selection guidance is strong and actionable.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the data source (Latvia Open Data CKAN DataStore) and the queryability condition, enhancing the agent's understanding of behavior beyond annotations.

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

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

The description is two sentences, front-loaded with the primary action and conditions. Every sentence provides essential information 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?

While the input and condition are clear, the description does not hint at the output format (e.g., JSON rows). Given no output schema, the agent may need to infer the result structure. The annotations (readOnlyHint) partially cover safety, but completeness is adequate for a simple query 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 each parameter already described. The description reiterates these but adds minimal new context (e.g., 'from a dataset's resources' for resource_id). It does not significantly augment the schema's meaning.

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

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

The description clearly states the tool pulls rows from a tabular CKAN DataStore resource by resource_id, with optional filters. This specific verb+resource pair distinguishes it from sibling tools like search_datasets which return datasets, not rows.

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 notes that only resources with DataStore enabled are queryable, providing a clear precondition. While it doesn't explicitly contrast with alternatives, the sibling list includes search_datasets (for dataset lookup) and others, so context is implied.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. Description adds scoping to user identifier and the key omission behavior, which is useful 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?

Description is two sentences, front-loading the main action and usage. Every sentence provides necessary information 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?

For a simple retrieval tool with one optional parameter and no output schema, the description covers usage, scoping, and pairing with siblings. Annotations handle safety. 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 single parameter 'key' is well-described. Description clarifies that omitting key lists all keys, adding semantic value beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if omitted. It distinguishes itself from sibling tools (remember, forget) by specifying the exact operation and 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 states when to use (look up stored context, avoid re-deriving) and how to list all keys. Mentions scoping but could be more explicit about when not to use or alternatives beyond 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?

The description indicates that setting mark_read:true modifies state by flagging events as read, contradicting the readOnlyHint=true annotation. This is a serious inconsistency that undermines transparency.

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

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

The description is concise at four sentences, each serving a clear purpose: stating the tool's function, describing return fields, explaining parameters with examples, and noting alternative access. 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?

The description covers the return format, parameter usage, and alternative access method. It lacks details on pagination and ordering, but given the simple nature of a feed pull, it is reasonably 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?

With 100% schema coverage, the description adds value by providing examples (e.g., 'sec_8k' for type) and explaining the behavioral effect of mark_read. It also lists what each returned alert carries.

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 'Pull fired events from your subscription feed', clearly specifying the verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on event retrieval rather than subscription management.

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 mentions the alternative HTTP endpoint, providing context for when to use the tool vs. direct access. However, it does not explicitly state when to use this tool over other query tools like query_resource.

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, non-destructive, and open-world hints. The description adds valuable context: fan-out to multiple sources, fallback from GDELT to GNews, USPTO soft-fail, and structured return format with citation URIs.

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

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

Every sentence serves a purpose. First line captures intent with examples, then explains sources, parameters, fallback, and sibling comparison. 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: sources, fallback mechanism, parameter formats, return structure, and sibling differentiation. Despite no output schema, the description compensates by mentioning the return format.

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 significant value beyond schema: explains since format with examples, clarifies value as ticker or CIK, and notes type is only company.

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

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

The description starts with concrete example queries and explicitly states it provides a change feed for a company within a time window, calling multiple sources in parallel. It clearly distinguishes itself from the sibling tool entity_profile.

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 this tool versus entity_profile, provides example queries, and gives detailed guidance on the since parameter (ISO date or relative shorthand).

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 important behavioral traits beyond annotations: key-value pairs are scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. This adds significant context not in the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). 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 concise and well-structured: it first states purpose, then usage, then technical details. Every sentence adds value without redundancy. It is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description fully covers the tool's functionality, usage context, and behavior. It explains what the tool does, how data is stored, scoping, persistence, and how it relates to sibling tools (recall, forget). 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 coverage is 100% with descriptions for both key and value. The description adds value by providing examples of keys (e.g., 'subject_property') and explaining the scoping mechanism, giving the agent a clearer understanding of parameter usage beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the verb (save), resource (data as key-value pairs), and distinguishes from siblings by mentioning paired tools recall and forget.

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

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

The description provides explicit guidance on when to use the tool: 'when you discover something worth carrying forward.' It lists concrete examples (resolved ticker, target address, user preference, research subject) and mentions alternatives (recall, forget), though it does not explicitly 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 already mark it read-only and idempotent, and the description adds substantial behavioral detail beyond that: graceful degradation of LEI/FIGI enrichment, cascade through multiple lookup endpoints, explicit `unresolved` reporting rather than omission, and ambiguity handling via `figi_candidates`. This gives the agent a strong model of tool 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?

The description is dense and every clause carries information, but it is structured as one long paragraph with many nested parentheticals. It is front-loaded with the core intent and 'Use FIRST' guidance, and the length is justified by the tool's complexity.

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

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

With no output schema, the description must explain return semantics, and it does: named identifiers per source, `figi_candidates` for ambiguity, `unresolved` for failures, and the RxNorm citation path. It also covers degradation behavior and supported lookup routes, leaving no critical call-time unknown 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?

Even with 100% schema coverage, the description enriches both parameters considerably. It explains what each supported type resolves to, lists accepted value forms for `value`, and gives concrete examples plus an anti-example for bond issuer names, teaching correct invocation syntax 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 states a precise operation: resolving a user-spoken NAME to canonical/official identifiers, with concrete examples of user queries. It explicitly differentiates from sibling tools by noting these are identifiers 'other tools require as input' and names entity_profile-style follow-ups as downstream uses.

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 direction: 'Use FIRST whenever you have a name but need an ID.' It also specifies input formats and cautions against including trailing security-class words. However, it does not name alternatives to avoid or describe when not to use it beyond the general 'when you need an ID' rule.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds process details: probes each entity, ranks by score, returns confidence and signal density. Does not mention potential rate limits or API key dependency for anthropic model, but schema covers that.

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, each adding unique information: action, process, use case, and output. No fluff.

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

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

For a composite tool with 4 params (1 required) and no output schema, description adequately explains input semantics, process (calls ai_visibility_check), and output structure (ranked list with metrics). No missing critical information.

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. Description adds value by clarifying that first entity is treated as 'subject' for narrative and that context disambiguates names, going beyond schema descriptions.

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

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

Clearly states verb 'Compare' and resource 'AI visibility across multiple entities side-by-side'. Distinguishes from sibling 'compare_entities' by specifying it uses AI visibility checks and scoring.

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

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

Provides explicit use case ('competitive AI-marketing audits') and example question. Implicitly suggests when to use over sibling ai_visibility_check, but no explicit exclusions or alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description details partial failures, timeouts for bundlephobia, and sources_failed list. No contradiction with annotations.

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

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

Well-structured, front-loaded with purpose, then usage, then behavioral details. Slightly verbose but each sentence adds value.

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

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

Despite no output schema, description explains return shape (summary block, advisories, links, alternatives). Covers parameters, behavior, limitations, and usage comprehensively.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about scoped packages and version defaulting, which enhances understanding beyond the schema.

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

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

The description clearly states it as a composite check for npm packages, combining deps.dev and bundlephobia. It uses a specific verb ('scan dependency') and distinguishes from sibling tools like scan_competitor_ai_presence.

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

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

Explicitly tells when to use (when asked about safety, popularity, size) and when not to use (NPM only; other ecosystems should use deps.dev:version directly). Provides clear alternatives.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavioral context by specifying the exact return structure (dataset id/name, title, organization, resources with resource_id), which helps the agent understand what the tool provides.

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

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

The description is two sentences: the first defines purpose, the second details return fields. Every sentence adds value with no redundancy, and key information is front-loaded.

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

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

Given the tool has 3 parameters with full schema coverage, no output schema, and comprehensive annotations, the description provides complete context: it names the data source (Latvia Open Data), specifies what is returned, and links to a sibling tool (query_resource). 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 coverage is 100%, with clear descriptions for all parameters (limit, query, offset). The description does not add any additional parameter semantics beyond what is already in the schema, so 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 'search' and the resource 'Latvia Open Data datasets.' It lists specific return fields (id/name, title, organization, resources with resource_id), which distinguishes it from sibling tools like query_resource or search_within.

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

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

The description implies usage for searching datasets and mentions query_resource for next steps, but it does not explicitly state when to use this tool over alternatives, nor does it provide exclusion criteria.

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 specific behavioral details beyond annotations: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K), and truncation behavior. 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?

Compact single paragraph with front-loaded purpose, every sentence adds value. 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?

Explains return format (passages with offsets and scores) and mentions model details. No output schema; missing error handling details but sufficient for the tool's complexity.

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

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

Schema coverage is 100%, so baseline 3. The description adds examples for the query parameter and restates schema info. Some added value but limited beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verbs like 'semantic search' and 'get back top-N passages'. It implies differentiation by specifying the use case (large record) but does not explicitly distinguish from all sibling tools.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Lacks explicit 'when not to use' but provides clear 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?

Discloses behavioral traits beyond annotations: requires OAuth account, details delivery channels (feed always on, optional email/sms/webhook), SMS 10/day cap, webhook auto-disabled after 10 failures, and webhook signing. Annotations indicate idempotent and non-destructive, but description adds rich 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?

Moderately long but every sentence adds value. Front-loaded with main purpose. Could be more structured (bullets), but still efficient and clear.

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 aspects: purpose, prerequisites, supported types, parameter formats, delivery options, limitations (caps, verification, auto-disable). No output schema, but description states it returns the subscription id. Complete for a complex subscription creation 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?

Despite 100% schema coverage, the description adds significant meaning: examples for each params type (e.g., sec_8k items, polymarket_edge topic), delivery constraints (phone verification, webhook signing), and details on always-on feed. Goes far beyond schema descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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 when to use (proactive monitoring), prerequisites (Pipeworx OAuth account), and mentions that anonymous/BYO cannot persist subscriptions. Covers supported types and delivery channels, though does not explicitly list alternative tools.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating safe read behavior. The description adds that the tool returns example questions with exact tool+argument shapes from a live catalog, and explains calling with no arguments for a full spread or passing a topic to focus. No contradictions with annotations.

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

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

The description is fairly long but front-loaded with key information. It uses examples and lists, which aids understanding, but some sentences could be combined for conciseness. Still, it is not overly verbose and remains clear.

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 large set of sibling tools, the description adequately positions this tool as an onboarding entry point. It explains the return format (category-bucketed example questions with tool+argument shapes) and mentions meta-tools, providing sufficient context. No output schema, but the description compensates.

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

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

Schema coverage is 100% with one optional parameter 'topic' described as an optional focus area. The description adds concrete examples of valid topics (finance, pharma, etc.) and clarifies that omitting the topic returns a cross-category spread, exceeding what the schema alone 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 defines the tool's purpose: returning category-bucketed example questions for Pipeworx, serving as an onboarding entry point. It distinguishes from siblings by stating 'Use this FIRST' and explicitly listing the categories and what it returns (tool + argument shapes).

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

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

The description explicitly states when to use this tool ('when you do not yet know what Pipeworx can do') and mentions how it can teach the use of meta-tools (ask_pipeworx, entity_profile, etc.). It does not explicitly list when not to use it, but provides clear context for its role.

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

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

Adds behavioral detail beyond annotations: explains that the row is deactivated (not deleted) and historical events stay available via recent_alerts. No contradictions with annotations.

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

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

Three sentences, each serving a distinct purpose: action, ownership constraint, and behavioral effect. No unnecessary words.

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

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

For a simple one-parameter mutation tool without output schema, the description covers action, ownership, and deactivation behavior. Lacks error handling details but is sufficient for a basic 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 has 100% coverage with a clear description of the id parameter. Description does not add further meaning beyond what the schema already provides.

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

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

The description uses specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing it from siblings like subscribe and list_subscriptions. It also adds ownership and deactivation context.

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

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

States ownership enforcement ('you can only cancel your own subscriptions'), providing clear context on when the tool is applicable. Missing explicit when-not or alternatives, but the intent is clear.

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

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

The description goes well beyond the readOnly/idempotent annotations by clarifying the meaning of each verdict, especially the crucial distinction between could_not_verify (check did not happen, includes verification_error{stage,detail}) and unsupported (no source exists). It also warns callers not to treat could_not_verify as evidence. This is exactly the kind of behavioral context agents need.

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

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

The description is long but densely informative. It is front-loaded with examples and a clear usage statement, then covers the two paths, return values, and an IMPORTANT caller note. Every sentence adds value; however, the length and multiple clauses make it slightly less scannable than ideal. Given the tool's complexity, this is well-justified.

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

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

With no output schema, the description fully covers the return contract: verdict options, the actual value with citation, reasoning, and the error semantics for could_not_verify. It also explains the internal routing logic, which is essential for an agent to set expectations. The tool has only two parameters, both documented, and the description fairly explains all relevant 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?

Schema coverage is 100% for both parameters, but the description adds meaningful detail: tolerance_pct overrides the wording-implied tolerance, suggests 1–2 for hallucination detection, and documents the default as implied by wording capped at 5. This goes beyond the raw schema and helps the agent choose appropriate values.

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 explicit trigger phrases ("Is it true that…"/"fact check") and states the core action: natural-language claim verification against authoritative sources. It clearly distinguishes itself from siblings by describing a consolidated single-call tool that replaces 4–6 sequential steps, and the two processing paths (SEC EDGAR for company financials, grounded pipeline for other claims) make its scope 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 says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides decision-relevant nuance: company-financial claims take the structured fast path, while any other factual claim automatically falls through to the grounded pipeline. This is strong when-to-use guidance, though it does not name specific alternative tools.

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