Oecd

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: default model (Workers AI Llama-3.3-70b free), optional Anthropic probe with BYO key, and return structure (per-model score, confidence, signals, raw_response plus combined view). 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 plus a list of use cases and return structure. Core functionality is front-loaded in the first sentence. Every sentence adds value with no waste.

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

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

Despite no output schema and 4 parameters, the description covers input behavior, output format, and variants. It is sufficient for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%. The description adds meaningful examples for 'entity' (e.g., 'Pipeworx', 'Acme Corp pricing'), explains 'models' options, clarifies '_apiKey' is optional for Anthropic, and 'context' disambiguates common names. This goes beyond the schema's own 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 verb 'probe', the resource 'LLMs for what they know about a business/brand/product/topic', and the output 'score visibility (0-100) per model'. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on visibility 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?

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains default model and optional BYO key for Anthropic. However, it does not explicitly state when not to use the tool or exclude alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the tool routes to a verified source, fills arguments, returns structured results with stable pipeworx citation URIs, is fast, and works on every tier, while also flagging that breaking-news questions are handled internally. It does not disclose failure modes or rate limits, but these are not essential for a read-only facade 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 longer than average but earns its length: it front-loads the key directive in capital letters, then supplies scope, examples, and step-up alternatives in a scannable order. Some redundancy exists ('PREFER OVER WEB SEARCH' and 'even if web search could also answer it' restate the same idea), but this is minor given the amount of useful routing guidance packed in.

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

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

For a tool with no output schema, the description provides a remarkably complete picture: domain scope, input style, routing behavior, output format with citations, tier availability, speed, and explicit sibling pathways for more specialized or broader research. An agent could confidently invoke this tool and set correct expectations about what will be returned.

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

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

The schema already describes all six parameters as aliases for 'question' with 100% coverage, which earns a baseline of 3. The description goes beyond the schema by clarifying the accepted input style (natural-language factual questions), giving concrete examples such as 'current US unemployment rate' and 'patents Tesla was granted last month', and listing trigger phrases that indicate the question is appropriate for this tool.

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 clear verb-resource pair: it routes natural-language questions to the appropriate one of 5,708 tools across 1,494 verified sources and returns structured answers with citation URIs. It also explicitly differentiates from sibling tools like ask_pipeworx_grounded and deep_research by naming them as step-up alternatives, removing ambiguity about what this tool is for.

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

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

The description gives explicit when-to-use directives: prefer it over web search, use it whenever the user asks specific phrases like 'what is', 'look up', 'find', 'get the latest', and use it as the default entry point. It also states when not to use it and which alternatives to choose (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions), so the agent can make the call selection confidently.

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

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

Annotations already establish readOnly, idempotent, open-world, non-destructive traits, so the bar is lower and the description adds genuine context beyond them: that this is a full working router that 'falls back to nothing,' that no candidate is active right now and it currently matches ask_pipeworx exactly, and that results feed into merge decisions. This gives the agent a precise mental model of the tool's live behavior without contradicting any annotation.

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

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

Front-loaded with the core purpose, then the current-state clarification, then usage guidance, then the 'full working router, not a fallback' caveat. Every sentence adds meaning, though the final 'Falls back to nothing — this IS a full working router' partially restates the earlier 'identical universal router' point; mildly repetitive but not wasteful.

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

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

For a one-question-param tool with no output schema, the description covers what it is, its current behavior, when to use it, and how it differs from the stable sibling. The only notable gap is that it doesn't clarify selection between the beta, stable, and grounded routers beyond a brief nod to 'newest routing' — a minor omission given the simple call surface.

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 all six parameters (question plus five aliases) are fully documented in the input schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies — acceptable but no extra value from the description here.

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

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

States a specific verb+resource ('universal router' dispatching to 5,708 tools, same arguments and response shape as ask_pipeworx) and explicitly differentiates itself from the sibling ask_pipeworx by its current experimental state. An agent can tell what this does and how it relates to the stable variant without opening schemas.

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

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

Gives explicit use context: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router to decide merges. However, it never states a condition under which an agent should prefer the stable or grounded siblings instead, leaving the beta-vs-stable choice somewhat implicit rather than an explicit exclusion.

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

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

Beyond the read-only, open-world, idempotent annotations, the description discloses refusal reasons, the success response shape with evidence quote, and the extra LLM call cost. It transparently conveys when the tool will refuse rather than guess, which is critical for high-stakes use.

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 slightly long, but every section earns its place: core behavior, routing relationship, output/refusal contract, use cases, and cost tradeoff. It is front-loaded with the key differentiator and only then provides structured details.

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

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

With no output schema, the description fully specifies the success response fields and all refusal reasons, making the tool's behavior predictable. Combined with the sibling comparison and cost guidance, an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for a natural-language question. The description itself adds no parameter-level detail, but the schema fully handles parameter semantics, so the baseline score of 3 applies.

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

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

The description states a specific purpose: a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers only from tool results. It clearly distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior.

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

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

The description explicitly says to use this mode when answers will be quoted, cited, or acted on, and to prefer ask_pipeworx for casual lookups because this costs an extra LLM call. This is direct when-to-use and when-not-to-use guidance 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?

Beyond annotations (readOnlyHint, idempotentHint), the description details numerous behaviors: low-confidence resolution short-circuit, closed market handling, wide-spread warnings, resolution-rule risk parsing, parent event extraction, and news fallback fields. It fully discloses what happens under various conditions, adding significant value 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 very detailed and well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), but it is lengthy. While every sentence adds information, it could be more concise for quick agent parsing. The front-loading of purpose and usage helps, but overall verbosity reduces conciseness.

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

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

Given the tool's complexity (3 params, no output schema, many behavioral nuances), the description covers all aspects: response shapes, resolver contract, parent event extraction, news error fields, safety checks, and cancellation rules. It is fully complete for an agent to understand tool behavior and output.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by explaining the 'depth' parameter with quick vs thorough semantics, 'include_raw' with usage guidance, and clarifying acceptable inputs for 'market' (slug, URL, question text). This exceeds schema-only documentation.

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

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

The description uses a specific verb-resource pair ('Research a Polymarket bet') and clearly states the action (pulling Pipeworx data). It distinguishes from sibling tools by focusing on holistic bet research rather than specific aspects like edges or arbitrage.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides examples of classifiers and fan-out. It does not explicitly mention when not to use or compare with alternatives, but the examples give 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?

Annotations declare readOnly, openWorld, and idempotent hints. The description adds that results are sorted by primary metric so 'largest' / 'most' reads off the top, returns paired data with citation URIs, and handles off-calendar fiscal years for companies. 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 front-loaded with user-facing example queries and is densely informative. Every sentence adds value, though it is somewhat lengthy. Still, it is well-structured.

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

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

Despite no output schema, the description covers return format ('paired data + pipeworx:// citation URIs per entity'). Both parameters are fully explained, and the complexity of comparing multiple entities is addressed with clear data-source distinctions. No gaps.

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

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

Schema coverage is 100%, and the description enriches both parameters: explains type enum values ('company' pulls latest 10-K data, 'drug' pulls FAERS data) and values array (tickers/CIKs for company, names for drug, with min/max of 2–5). Adds example inputs.

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

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

The description opens with concrete example queries ('Compare X and Y', 'X vs Y', 'which is bigger') and clearly states it performs side-by-side comparison of 2–5 companies or drugs. It specifies data sources (SEC EDGAR for companies, FAERS for drugs) and distinguishes from sequential single-pack lookups.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use this tool instead of alternatives like entity_profile. This covers both when and when-not implicitly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is carried. The description adds substantial context beyond annotations: account/tier requirements, latency expectations (15-60s, up to ~90s), the findings-packet return shape (verbatim evidence, gaps[], contradictions[], hop field, citation_uri), and the semantic-excerpting 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?

The description is long, but every sentence earns its place for a tool of this complexity. It is front-loaded with the most critical constraints (account requirement, fallback tool) and follows a logical arc: prerequisites → capability → ideal use → exclusions → depth semantics → output format/pagination → timing. Dense is not the same as verbose; there is no filler.

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

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

With no output schema and 35 siblings in a complex research domain, the description carries a heavy burden — and it meets it fully: return-packet structure, gap/contradiction behavior, citation resolvability, depth-level differences, latency, and account tiers are all covered. An agent can call this tool correctly without needing anything else.

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

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

Schema coverage is 100%, so the schema already documents both parameters, giving a baseline of 3. The description adds meaningful extra semantics for 'depth' — explaining the facet counts (quick=3, standard=3 with gap-recovery + contradictions scan, thorough=6 paid with iterative hop) and that 'question' should be broad/multi-part because decomposition is the point. This enriches the schema meaning rather than repeating it.

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 verb-and-resource ('Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources') and explicitly distinguishes itself from open-web search and from ask_pipeworx. The 'is NOT open-web search' clarification plus the enumeration of source types (SEC, FRED, FDA, USPTO) make the purpose unambiguous.

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

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

Provides explicit when-to-use ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance, naming the alternative tool and the exact condition that selects it ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', 'If you are not signed in, use ask_pipeworx instead'). Nothing is left to inference.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds that it returns top-N relevant tools with schemas and curated examples, ready to call directly. 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?

Three well-structured sentences: purpose with examples, return format, usage guidance. No fluff, front-loaded, 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?

Without output schema, description adequately explains return format (names, descriptions, schemas) and that results are directly callable. Covers essential aspects for a search tool.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds context about query purpose, aliases, and return format (schemas included), providing extra value beyond schema.

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

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

The description clearly states it finds tools by describing data or task, lists specific domains, and distinguishes from sibling tools by advising to call it first to see the option set.

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 you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Provides clear context, though no explicit when-not 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?

Annotations already convey read-only, idempotent, open-world, and non-destructive traits. Description adds detail about fanning out across multiple sources and soft-failing for patents. No contradictions, and the description adds value 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 front-loaded with examples and key guidance. It is moderately verbose but each sentence adds value. Could be slightly more concise, 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?

No output schema, but description thoroughly lists all returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). For a holistic profile tool with no output schema, this is complete and actionable.

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%. Description adds context by explaining that type is limited to 'company' and value accepts ticker or CIK, with explicit note that names are not supported—adding meaning beyond the schema.

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

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

The description clearly states it provides a full cross-source profile of a US public company, with example queries that illustrate common usage. It distinguishes from siblings like resolve_entity by specifying when to use that tool first.

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 chaining single-pack lookups for holistic views. Also advises using resolve_entity first if only have a name, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context that OECD enforces a result-size limit and may truncate broad queries, which is valuable beyond annotations. It also states that the tool returns labeled rows. 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 two sentences plus an example, front-loaded with the main purpose. Every sentence adds value: the first states the purpose, the second explains parameters and limitations. No wasted words. The structure is 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?

Given the presence of an output schema, the description does not need to explain return values. It covers the essential aspects: what it fetches, how to specify parameters, and potential truncation behavior. The description is fully adequate for a fetch tool with good annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining the key string format with an example and providing guidance on period formatting. It reinforces the schema descriptions and adds examples, improving clarity beyond what 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 states 'Fetch tidy rows from any OECD dataflow', specifying the verb 'fetch' and the resource 'tidy rows from OECD dataflows'. The inclusion of examples for flow_ref and key string further clarifies the tool's purpose. It is easily distinguishable from siblings like 'search_dataflows' which searches for dataflows.

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 guidance on usage by explaining the key string format and period parameters. It also warns about OECD's result-size limit and advises narrowing broad queries. While it does not explicitly compare to alternatives, the context is clear for fetching data vs searching for dataflows.

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 deletion behavior beyond annotations by explaining it clears sensitive data. Annotations already indicate destructiveHint=true, so description adds value with usage 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?

Two sentences, front-loaded with action, efficient and 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?

Comprehensive for a simple tool: explains action, when to use, related tools. Lacks mention of error handling for missing keys, but annotations cover idempotency.

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 parameter 'key' is described in schema. Description does not add new semantic information beyond 'by key', so baseline 3 applies.

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

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

Description explicitly states 'Delete a previously stored memory by key', clearly identifying the action and resource. It distinguishes itself from siblings by mentioning 'remember' and 'recall'.

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 specific when-to-use scenarios: context stale, task done, clear sensitive data. Also explicitly pairs with 'remember' and 'recall', offering alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's disclosure that it 'fetches the page, extracts title/description/key links' adds useful behavioral context without contradiction. It explains the process without over-committing.

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

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

The description is three efficient sentences plus a use-case list. Every sentence adds value, with no redundancy or wasted words. The main action 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?

The description covers the input (URL), the process (fetch, extract, emit), the output format (standard llms.txt markdown), and the outcome (single text blob for site-root). No output schema exists, so the description fully explains what the agent will receive.

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

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

Schema description coverage is 100% for both parameters (url, max_links). The description does not add new semantic information beyond what is already in the schema, so a 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 it generates a production-ready llms.txt file for any URL, specifies the output format, and lists specific use cases. The verb 'generate' combined with 'llms.txt' and the resource 'URL' makes the purpose unambiguous.

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

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

The description provides explicit use cases ('getting a client's site indexed...', 'auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. It does not mention when not to use it or reference sibling tools, but the guidance is sufficient for a simple tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context that the data is pre-vetted and grouped by topic, which is useful behavioral info beyond what annotations provide. 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 concise sentences that front-load purpose and include guidance. 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?

Given the presence of an output schema and rich annotations, the description sufficiently explains what the tool returns (grouped refs), how to use the output (with fetch_dataset), and when to use alternatives. No gaps.

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

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

The schema covers the single parameter 'topic' with a description, but the description enriches it by listing example values (gdp, labour, etc.), which are not in the schema (no enums). This helps the agent understand valid inputs.

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

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

The description clearly states the action ('List'), the resource ('OECD dataflow refs we have pre-vetted'), and the organization ('grouped by topic'). It also distinguishes from sibling tools like search_dataflows and fetch_dataset.

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 this tool (for pre-vetted flows) and when to use alternatives ('For everything else use search_dataflows or browse...'). Also provides next steps: 'Pass the flow_ref to fetch_dataset.'

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns specified fields and focuses on active subscriptions (with optional inactive via param). Lacks pagination details, but sufficient for a simple list.

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: first states purpose and outputs, second provides actionable usage guidance. Front-loaded and no extraneous information.

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

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

Covers purpose, return fields, usage guidance. Missing details like pagination or ordering, but given the tool's simplicity and annotation coverage, it is complete enough.

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 of include_inactive. The tool description does not add extra meaning beyond the schema, meeting the baseline for high coverage.

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

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

Clearly states 'List the caller's active subscriptions' with specific return fields. Distinguishes from sibling tools subscribe/unsubscribe by mentioning use cases.

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

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

Explicitly says to use it 'before adding more' (i.e., before subscribing) or 'to find an id to cancel' (i.e., before unsubscribing). Provides clear when-to-use guidance.

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

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

Beyond the all-false annotations, the description discloses meaningful behaviors: filing without an account returns a claim_token, passing it back later reads resolution status, rate limiting is 5 per identifier per day, and it is free with no quota impact. These go well beyond the structured annotation hints.

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

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

The description is long but every sentence earns its place: it defines purpose, use cases, boundaries, token mechanics, team responsiveness, rate limits, and cost. It is front-loaded with the core purpose and then provides layered operational detail 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 feedback tool with no output schema, the description is remarkably complete: it covers when to use, what to include, what to avoid, how token-based follow-up works, rate limits, and roadmap impact. No significant gaps remain for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so parameters already have descriptions. The description adds valuable usage semantics, especially for claim_token (returned on anonymous filing, used later to check status) and for the message/context guidance to describe issues in terms of Pipeworx tools/packs rather than end-user prompts.

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

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

The description opens with a specific verb and object: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete use cases (bug, feature/data_gap, praise), clearly distinguishing this tool from siblings like ask_pipeworx or discover_tools.

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

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

The description gives explicit 'Use when' conditions and an explicit exclusion: only report tools served by this Pipeworx connection, not tools from other MCP servers. It even advises where to file issues for other servers, which is strong usage guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds beyond: self-aggregating signal, derived from CF analytics-engine, no PII, caching details (5min-1h).

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?

Concise, uses bullet-like enumeration of use cases. Each sentence adds value; no fluff. Could be slightly more compact but 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?

Given simple parameter (one enum), no output schema, and no required params, description sufficiently covers usage, data source, and caching. No major gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining window semantics: 'shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Description clearly states the tool returns 'top tools, top packs, and total call volume' over specified windows. Uses specific verb 'returns' and resource 'trending data', distinguishing it from siblings like entity_profile or ask_pipeworx.

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

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

Explicitly lists three use cases (discovering hot data, confirming canonical tools, checking alignment). Provides context for when to use but does not explicitly mention when not to use or 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?

Disclosures beyond annotations: fill check for realizable edge, semantic anchor, partition filter, and when not to trade. 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?

Moderately long but every sentence adds value. Front-loaded with purpose and mode usage. Well-structured with clear sections for each mode and special checks.

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

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

Despite no output schema, the description fully explains the response structure (opportunities, partition_check, fill check) and edge cases, making the tool complete and usable.

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 descriptions. The tool description adds valuable context: event slug vs URL acceptance, topic as seed question, and default behavior with no args.

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 it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) with specific verbs and resources.

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 explains when to use each mode: no args for trending scan, event for a specific market slug, topic for cross-event scan. Also includes fill check guidance and points to alternative 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?

The description discloses extensive behavioral traits beyond annotations: caching at KV level for 1 hour, response structure with segments and diagnostics, edge calculation details, and tradeable-edge knobs. It does not contradict any annotations; in fact, it confirms read-only and idempotent 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 long but well-structured, with a clear front-loaded purpose and logical sections for models, output fields, and parameters. Every sentence adds value, though it could be slightly more concise. Overall, it is efficient for the complexity.

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

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

Given the complexity (9 parameters, no output schema, multiple segments, diagnostics), the description is highly complete. It explains output fields, model details, parameter interactions, and caching. It leaves little ambiguity for an AI agent to understand the tool's behavior and outputs.

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

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

All 9 parameters have 100% schema coverage with descriptions that add significant context beyond basic types. For example, min_kelly explains skipping small opportunities, slippage_pp explains default and adjustment, and min_partition_leg_kelly explains why min_kelly does not apply to partitions. The description provides rationale and usage guidance.

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

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

The description clearly states the tool's purpose: scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and distinguishes itself from siblings by providing a broad scan without paging hundreds of markets.

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 discovering betting opportunities but does not explicitly specify when to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker. It provides no when-not or direct comparisons, so guidance is implied but not explicit.

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

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

The description adds substantial behavioral context beyond annotations: it explains data source (daily snapshots), response structure (tracked, expired, snapshot_dates), limits (60-day TTL, daily closes vs intraday), and edge_pp_net signing. 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 a single well-structured paragraph with clear sections (RESPONSE, LIMITS). It front-loads the main purpose. However, it is relatively long (150 words) and could be slightly more concise, but for a tool with no output schema, the detail is 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?

Given no output schema, the description thoroughly explains return values (tracked, expired, snapshot_dates with field meanings), limits, and edge_pp_net signing. It covers all necessary aspects for an agent to understand usage and output.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context: clarifies days lookback (default 14, max 30) and window meaning (snapshot family). This adds moderate 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 purpose: providing edge persistence and decay telemetry. It answers the specific question 'how long has this edge existed and is it shrinking?' and explains the significance of distinguishing fresh vs. old edges. The title and name are descriptive.

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

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

The description implies when to use the tool (e.g., to differentiate between fresh and old edges) but does not explicitly state when to use it versus alternatives. No comparisons to sibling tools like polymarket_edges are provided, and no exclusions or when-not-to-use guidance is given.

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, idempotent, and non-destructive. The description adds behavioral details beyond this: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict.' It also warns about forced directional risk naming specific legs. 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 longer but well-structured: a one-line core purpose, then REQUIRES, then separate paragraphs for each mode. Every sentence adds value—explaining behavior, return fields, and usage context. It is not overly concise but efficiently uses length to convey complex, mode-specific details.

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

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

Given the complexity (two modes, 4 parameters, no output schema), the description thoroughly covers what is returned: field names like top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. This gives the agent a complete mental model of the tool's output without needing an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond schema: it explains the distinct interpretation of size_usd for single-market (max spend or target proceeds) vs basket (settlement notional), and the auto-default logic for basket side based on partition sum. This enriches the agent's understanding of parameter semantics.

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

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

The description begins with a specific verb-resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools like polymarket_arbitrage by stating this is a prerequisite check. The two modes (single-market and basket) are explicitly defined, leaving no ambiguity about what the tool does.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why partial basket fills convert an arb into an unhedged directional position, giving clear context for when not to rely on theoretical values.

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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds substantial behavioral context beyond annotations: the full compatibility_codes[] catalog, that 'unknown' metric_type/match_subtype legs are never paired, the skipped_cross_type/cross_subtype counters, temporal_alignment semantics, and the caveat that most pre-mapped topics return warnings today. This is rich, decision-relevant disclosure.

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

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

Carries genuinely valuable content and front-loads purpose well, but is delivered as a dense wall of text with ALL-CAPS pseudo-headers (TWO MODES, RESPONSE, SAFETY FIELDS) instead of structured markup. The length is partly justified by the tool's complexity and absence of an output schema, but scannability suffers; a bulleted or sectioned layout would earn a higher score.

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

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

Given the tool's complexity (two modes, safety fields, multiple compatibility codes, skip counters, temporal alignment) and the absence of an output schema, the description is remarkably complete — it explains the response structure (leg-by-leg prices, top_spreads_pp), the safety fields that must be read, all relevant codes, and the meaning of skipped/unclassified data. Little an agent needs to invoke it correctly 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% with each of the 3 optional params documented, so baseline is 3. The description adds meaningful linkage beyond individual descriptions by framing the two modes and explaining how topic selects the shortcut while kalshi_event_ticker/polymarket_event_slug override each side — decision context the schema's isolated descriptions don't provide.

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

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

States a precise verb-resource pair — 'Cross-venue spread between Kalshi and Polymarket' — and scopes it to 'the same resolving question.' It clearly differentiates from Polymarket-only siblings (polymarket_arbitrage, polymarket_edges) by being explicitly cross-venue, and explains the two modes of operation (topic shortcuts vs explicit pairings).

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 describes when to use each of the two modes ('TWO MODES... auto-fetch' vs 'explicit... for custom pairings') and gives strong practical guidance that 'pre-mapped ≠ tradeable' and most topics return compatibility warnings. It does not name an alternative sibling tool to route to, which keeps it from a 5, but the use context is clearly conveyed.

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 and destructiveHint=false. The description adds context about scoping and key omission behavior but does not significantly expand on behavioral details 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 three sentences, front-loaded with the primary action, and every sentence adds value. No redundancy or 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?

Given the tool's simplicity (1 parameter, no output schema, annotations present), the description fully explains purpose, usage, and pairing, leaving no gaps for an AI agent.

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

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

100% schema coverage means the schema already documents the 'key' parameter and its omission behavior. The description adds no new parameter information beyond what is in the schema, so baseline score of 3 applies.

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

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

The description clearly states the tool retrieves values saved via 'remember' or lists all keys when omitted, with specific verb and resource, and distinguishes from sibling tools like 'remember' and 'forget'.

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

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

The description provides explicit use cases (e.g., retrieving user's target ticker, address, research notes) and explains scoping and pairing with 'remember' and 'forget', offering clear when-to-use guidance.

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

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

Annotations declare readOnlyHint=true, but the description states that setting mark_read:true flags events as read, modifying state. This contradicts the read-only annotation. The description does add useful behavioral context (e.g., payload fields, polling appropriateness), but the contradiction significantly undermines trustworthiness.

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, front-loaded with the main action, and every sentence adds essential information (e.g., return fields, filtering, mark_read behavior, alternative access). No unnecessary words or repetition.

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

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

Given no output schema, the description adequately explains what events contain (source, citation_uri, payload). It mentions polling suitability and an alternative endpoint. It could clarify ordering (most recent) and pagination, but overall it is sufficiently complete for a simple retrieval 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 adds value by providing an example for the 'type' parameter (e.g., 'sec_8k') and explaining the 'mark_read' behavior beyond the schema's brief description. This slightly exceeds the baseline.

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

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

The description clearly states the tool pulls fired events from a subscription feed, using the specific verb 'Pull' and resource 'fired events'. It distinguishes itself from siblings like 'list_subscriptions' by focusing on alert events rather than subscription metadata.

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 this tool (to retrieve recent alerts) and provides an alternative HTTP endpoint for scripts and dashboards. However, it does not explicitly contrast with sibling tools like 'search_within' or 'recent_changes', though the context makes usage clear.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description details multidatabase fan-out, GDELT→GNews fallback, USPTO soft-fail, and return structure (changes grouped by source + count + citation URIs). 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 somewhat long but well-structured, with front-loaded examples and a clear alternative. Every sentence adds value, though some redundancy could be trimmed.

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

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

Given the complexity (multiple sources, fallbacks, soft-fails, multiple parameter formats) and no output schema, the description is remarkably complete. It explains the tool's behavior 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. The description adds value by explaining `since` format with examples (ISO, relative, typical suggestion) and clarifying `value` (ticker or CIK). This goes beyond the schema's description.

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

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

The description clearly states it provides a change feed for a company in the last N days/weeks/months, with specific query examples. It distinguishes from the sibling tool `entity_profile`, which is for static profiles.

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

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

Explicitly provides when to use this tool vs. `entity_profile`. Also gives context on supported entity types and parameter usage, including a recommendation for typical monitoring ('30d' or '1m').

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

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

Discloses key-value scoping, persistence duration (24h for anonymous, permanent for authenticated), and idempotency beyond annotations. 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?

Concise paragraph with no filler; front-loaded with purpose, then usage, then behavior, then sibling pairing. Every sentence adds value.

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

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

Covers purpose, usage, behavior, and lifecycle. No output schema but references retrieval with recall. Missing explicit mention of overwrite behavior, but idempotent hint implies 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 already covers both parameters thoroughly. Description adds examples of key naming conventions and clarifies value as free text, reinforcing 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?

Clearly states the tool saves data for reuse, with specific examples (resolved ticker, target address, etc.). Distinguishes from siblings like 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?

Explicitly says when to use ('discover something worth carrying forward') and references companion tools (recall, forget). Could add what not to use it for, but 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?

Annotations already convey readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail beyond these: it explains graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), internal cascading lookups, and that unresolved identifiers are explicitly listed under 'unresolved'. 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 dense but not verbose. It front-loads the core purpose via examples, then systematically covers supported types, output behavior, and fallback logic. Every sentence contributes unique information. Given the tool's complexity (two types, multiple identifier sources, graceful degradation), the length is justified and well-structured.

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

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

Despite lacking an output schema, the description thoroughly explains what the tool returns: identifiers labelled with source, unresolved items explicitly listed, and graceful degradation behavior. Combined with the comprehensive annotations, the agent has enough context to use the tool correctly and interpret its results. No gaps are apparent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by specifying that the 'company' type accepts ISIN (not mentioned in the schema description) and explains the resolution process for each type. It also hints at the output structure (identifiers labelled with source, unresolved list). This additional context raises the score above baseline, though the schema already covers the basic parameter meanings.

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

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

The description opens with concrete user queries (e.g., 'What's the ticker for…') and clearly states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly distinguishes this tool from siblings by saying 'Use FIRST whenever you have a name but need an ID.' No other sibling tool fulfills this exact role, making the differentiation strong.

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

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

The description provides a direct usage directive: 'Use FIRST whenever you have a name but need an ID.' It also enumerates the supported entity types ('company', 'drug') and explains what each resolves, so the agent knows exactly when to invoke this tool. It does not explicitly list when not to use it, but the specificity is sufficient to infer exclusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral context: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density per entity. No contradictions.

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

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

Three sentences that efficiently convey purpose, process, output, and usage example. No redundant or wasted words.

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

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

Given 4 parameters, no output schema, and reliance on another tool, the description is complete: covers input, process, output fields (score, confidence, signal density), and use case. No gaps.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: explains that first entity is treated as 'subject' for narrative, that models default to workers-ai, and that _apiKey is only needed if anthropic is in models.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from sibling tools like ai_visibility_check which handles a single entity.

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

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

The description explains it is useful for competitive AI-marketing audits and provides an example question. It implies usage when comparing multiple entities, but does not explicitly state when to avoid or mention alternatives beyond referencing ai_visibility_check.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds important behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. 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 relatively long but well-structured, with a clear opening summary followed by details. Every sentence adds value, though it could be slightly more concise. No wasted words.

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

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

Given the complexity (multiple APIs, partial failures) and no output schema, the description is quite complete. It explains the return structure (summary block, per-advisory detail, links, alternative versions) and edge cases like timeouts. Missing only a note on rate limits or authentication, but overall 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 covers 100% of parameters, but the description adds context beyond the schema: package accepts scoped packages, version defaults to latest. This helps the agent understand validation rules and defaults.

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

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

The description clearly states the tool performs a composite check on npm packages across deps.dev and bundlephobia, answering questions about safety, popularity, and size. It distinguishes from sibling tools by specifying NPM-only scope and mentioning alternative tools for other ecosystems.

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

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

The description explicitly provides when to use the tool ('whenever an agent asks is X safe / popular / small') and what not to use it for (other ecosystems like PyPI, Maven, etc.). It also covers partial failure behavior and timeout expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by stating output nature (dataflow refs) and next-step usage, without contradicting annotations.

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

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

Two concise sentences: first defines purpose and outcome, second provides refinement advice. 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?

Simple tool with clear purpose, good annotations, and output schema. Description covers purpose, usage, and output relation completely for its complexity.

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

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

Schema description coverage is 100% with clear explanations for each parameter. The description does not add significant new meaning beyond 'restrict by agency' which is implied in 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?

Clearly states verb 'Search', resource 'OECD SDMX dataflow registry', and outcome 'Returns matching dataflow refs ready to pass to fetch_dataset'. Distinguishes from sibling fetch_dataset by indicating workflow relationship.

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: 'If results are noisy, refine with a more specific keyword or restrict by agency.' Also implies usage before fetch_dataset. No explicit when-not, but context is clear.

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

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

Annotations already provide safety hints (readOnly, idempotent, not destructive). Description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap, truncation flag. 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?

Single paragraph, front-loaded with purpose, then usage, then technical details. No redundant sentences.

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

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

No output schema, but description explains return values: top-N passages, character offsets, similarity scores. Also mentions pairing with ask_pipeworx_grounded. Complete for an agent to use correctly.

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

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

Schema has 100% description coverage. Description adds value by providing examples for 'query' and specifying the character limit for 'text'. 'limit' is not elaborated but schema already explains default and range.

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, returning relevant passages with offsets and similarity scores. It distinguishes from siblings by specifying it is for large records and pairs with ask_pipeworx_grounded.

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

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

Explicitly states when to use: when the record is too large for the prompt, and pairs with ask_pipeworx_grounded. Implies not to use for small records that fit in the prompt.

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

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

Annotations already indicate non-readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context such as OAuth requirement, persistence, delivery channel specifics, and subscription creation. 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 efficiently structured: first sentence states purpose and return, then prerequisites, then types, then delivery channels. Every sentence adds value, no redundancy. It is front-loaded and well-organized.

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

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

For a tool with 3 parameters (including nested object), no output schema, and medium complexity, the description covers all key aspects: purpose, auth requirements, type options, delivery channels, and constraints. It lacks explicit response format beyond 'id', but remains sufficient for correct invocation.

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

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

Schema coverage is 100%, but the description adds substantial value beyond the schema: type-specific filter examples, delivery channel details including webhook signing secret. This extra information helps the agent understand exactly how to fill parameters.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It identifies the verb (create) and resource (subscription), and distinguishes from siblings like list_subscriptions 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?

It provides prerequisites (Pipeworx OAuth account), lists supported types with examples, and details delivery channel constraints (phone verification, daily cap). However, it does not explicitly mention when not to use it or suggest alternatives like list_subscriptions for listing.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: it is the onboarding entry point, returns categorized examples with exact tool/argument shapes, and is drawn from a live catalog. 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 thorough but includes many example queries that could be considered verbose. However, it is front-loaded with the main purpose and well-structured with examples in parentheses. It earns its length by being immediately useful.

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

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

No output schema exists, so the description must explain return values. It does so clearly: 'Returns category-bucketed example questions... each with the exact tool + argument shape'. Also mentions it is drawn from a live catalog, giving adequate completeness.

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

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

Schema coverage is 100% with a detailed description for 'topic'. The description adds value by showing example values and explaining that omitting gives a full spread, while passing a topic focuses the results. This goes beyond the schema's description.

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

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

The description uses a specific verb 'Returns' and resource 'category-bucketed example questions', clearly distinguishes itself as the onboarding entry point. It explicitly states what the tool does: helps users discover what they can ask and how to ask 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?

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains when to pass a topic vs. omit it, providing clear context for usage.

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

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

Discloses ownership enforcement and deactivation behavior, adding value beyond annotations which already indicate idempotentHint and destructiveHint.

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

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

Two sentences with no fluff, front-loaded with action, each sentence contributes distinct and essential information.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, constraint, and effect adequately.

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

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

Schema already fully describes the id parameter; description does not add extra semantic details.

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

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

The description clearly states the action 'Cancel a subscription by id' and explicitly distinguishes from deletion by noting deactivation. It contrasts with sibling tools like subscribe and list_subscriptions.

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

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

Provides ownership constraint and effect (deactivation, history retained via recent_alerts), but does not explicitly state when to use versus alternatives beyond implication.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral details: the automatic routing between structured and grounded pipelines, the meaning of each verdict, and the crucial warning that 'could_not_verify' means the check did not happen and must not be treated as evidence. This is valuable context that annotations alone do not provide. 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?

Although the description is long, every sentence adds necessary information. It is front-loaded with the query forms and core purpose, then systematically covers pipelines, return values, and error semantics. The structure is logical with distinct paragraphs for purpose, behavior, and warnings — nothing is redundant or extraneous.

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

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

With only 2 parameters and no output schema, the description compensates by fully explaining the return values (verdict types, citation, reasoning), the meaning of 'could_not_verify' vs. 'unsupported', and the two execution paths. It also ties into the broader workflow by noting it replaces multiple sequential calls. The tool is fully specified.

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

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

The input schema already provides 100% coverage with clear descriptions for both parameters. The description adds extra value by explaining the purpose of 'tolerance_pct' (overrides implied tolerance, set 1–2 for hallucination detection) and gives representative claim examples. This goes beyond the schema's basic 'max percent deviation' definition.

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 a specific verb+resource: 'natural-language claim verification against authoritative sources.' It also provides concrete natural-language triggers ("Is it true that…" / "fact check") and distinguishes itself from siblings by focusing on verifying factual claims rather than searching or researching broadly. The two-path explanation (SEC/XBRL fast path vs. grounded pipeline) adds further precision.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear. It also differentiates between company-financial claims and any other claims, giving specific guidance on what to expect in each case. However, it doesn't name sibling alternatives for when to *not* use this tool, though the 'Replaces 4–6 sequential calls' comment implies it's a consolidated replacement.

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