Nyt

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

The description adds behavioral details beyond annotations: default model, BYO key for Anthropic, pass-through of apiKey, return structure. 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 well-structured sentences, front-loading purpose and default, with 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 4 parameters, 100% schema coverage, and no output schema, the description sufficiently covers tool behavior, optional key usage, and return structure.

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 some value by explaining defaults and optionality, but the schema already covers 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 clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model, with default model and optional Anthropic. This distinguishes it from siblings like entity_profile or compare_entities.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly exclude alternatives or state when not to use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds context beyond that: it routes to a large toolset, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes a single fast call. These behavioral traits are not present in the annotations or schema, significantly enhancing transparency.

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

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

The description is long but every sentence serves a purpose: it front-loads the key directive ('PREFER OVER WEB SEARCH'), lists categories and examples, explains the mechanism, and provides sibling differentiation. The structure is logically organized from usage imperative, to examples, to step-up guidance, making it easy to scan and act on. No fluff.

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

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

Given the tool's simplicity (one real parameter, no output schema), the description covers all necessary context: return format (structured answer with citation URIs), the fact it works across tiers, and when to use alternatives. It also addresses the common need to compare against web search, making the description complete for an agent to select and invoke this tool correctly.

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

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

The input schema lists six parameter aliases (q, text, input, query, prompt, question) all pointing to the same concept, with a description for the question property. Since schema coverage is 100%, baseline is 3. The description adds extra meaning by specifying the expected type of content (factual questions about real-world entities/events/numbers) and provides concrete examples, which helps the agent craft a suitable query beyond the schema's generic 'natural language' instruction.

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 phrase ('routes the question to the right one of 5,521 tools across 1452 verified sources') and clearly states the scope (factual questions about real-world data with citations). It distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research, making its unique role as the default entry point explicit.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions') and when-not-to-use instructions (step up to ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It also clarifies that breaking-news queries are already covered by this tool, preventing unnecessary escalation.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond annotations: it explains the beta status, that candidate routing improvements are enabled live when under test, that no candidate is currently active (retired on 2026-07-26), and that it currently matches ask_pipeworx exactly. This gives the agent a clear picture of the tool's experimental edge 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?

The description is somewhat long for a single paragraph, but every sentence earns its place: it establishes the beta relationship, current state, usage instruction, and reassurances. It is front-loaded with the most important information ('Beta version of ask_pipeworx') and flows logically, so it is concise enough for its content.

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

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

Given the tool's complexity as a universal router with 5,521 tools, the description covers the key aspects: what it is (beta of ask_pipeworx), how to use it (exactly like ask_pipeworx), when to prefer it (newest routing), and its current equivalence to the stable version. No output schema is provided, but the description explains the response shape is identical to ask_pipeworx, so it does not need to enumerate return values. It lacks a basic explanation of what 'routing' does, but that is inherited from ask_pipeworx.

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

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

The input schema has 100% coverage, with all 6 parameters described as aliases for 'question' and full descriptions for each. The description does not add any parameter-specific information beyond noting 'same arguments,' so the baseline of 3 is appropriate—the schema already carries the weight.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router, and explicitly says it has the same 5,521 tools, same arguments, and same response shape. This distinguishes it from the sibling ask_pipeworx by its experimental nature, but it does not fully define what 'universal router' does for an agent unfamiliar with ask_pipeworx, so it's not a perfect 5.

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

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

The description gives explicit usage instructions: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router, explains that results are compared to decide merges, and reassures that it falls back to nothing—it's a full working router. This is strong when-to-use guidance with alternatives mentioned.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses rich behavioral details: it returns a structured object with answer, evidence, confidence, source, and refusal_reason; it explicitly defines refusal reasons like 'not_in_source' and 'tool_error'; and it explains that it uses only the tool result to prevent hallucination. This is substantial added context beyond the safe-read 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 compact yet information-dense. Each sentence contributes value: core purpose, routing mechanism, return format, refusal reasons, use cases, and cost comparison. It is well-structured and does not waste words, with the most critical info front-loaded.

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

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

Given no output schema, the description fully explains the return values and failure modes. It covers tool selection context, cost implications, and usage scope, making it complete for an agent to decide invocation and interpret results. References to sibling ask_pipeworx provide additional context.

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

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

The schema covers 100% of parameters with clear descriptions, including aliases, so the description doesn't need to repeat parameter info. The description adds no new parameter-level semantics, so the baseline 3 is appropriate.

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

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

The description explicitly states this is a 'Hallucination-resistant answer mode for high-stakes reads' that routes to tools, fetches data, and extracts answers only from tool results. It clearly distinguishes itself from the sibling 'ask_pipeworx' by describing the additional extraction step and return format, making its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and contrasts with 'prefer ask_pipeworx for casual lookups.' It also notes the cost tradeoff of 'one extra LLM call,' providing clear criteria for tool selection versus the sibling.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing internal behavior: market resolution, classification, fan-out to data packs, response structure, safety mechanisms (low-confidence short-circuit, closed market handling), and cancellation rule parsing. No contradiction with annotations; the tool is read-only as described.

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 comprehensive but verbose, containing extensive details such as classifiers, fan-out examples, and response shapes. While every sentence adds value, the length might overwhelm some agents. The structure is logical with clear sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.), and critical information is front-loaded.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It covers input formats, output structure (result.market, result.analysis, result.evidence), behavior for various bet types, edge cases (illiquid markets, closed markets), and safety instructions. The details on resolver contracts and cancellation rules ensure agents can handle results appropriately.

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

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

Although the input schema has 100% description coverage, the tool description adds significant meaning by explaining how each parameter affects behavior. For example, it clarifies that 'market' accepts slug, URL, or question text, it describes the 'depth' parameter with 'quick' vs 'thorough' definitions, and it explains the 'include_raw' parameter's impact on response size. This context greatly aids correct parameter usage.

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

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

The description clearly states the tool's primary function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It uses specific verbs ('research', 'pull') and identifies the resource ('Polymarket bet', 'Pipeworx data'). The description also distinguishes the tool from siblings by its comprehensive, all-in-one research scope, as opposed to specialized tools like polymarket_arbitrage or polymarket_edges.

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

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

The description explicitly lists use cases: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It provides guidance on when to trust the analysis by instructing users to inspect the 'market_match_confidence' field. While it doesn't explicitly state when not to use the tool, the use cases are clear and cover the intended scenarios.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint, so the description does not need to cover those. It adds value by specifying the return fields (rank, title, author, description, publisher, weeks on list) and the default list name, which goes beyond what annotations provide.

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

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

Two sentences, front-loaded with the core purpose, followed immediately by a concrete example. No unnecessary words; every sentence earns its place.

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

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

Even without an output schema, the description lists all key return fields. The tool is a simple read operation, so the description provides sufficient completeness for an agent to understand what it returns.

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

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

Schema coverage is 100% for both parameters. The description adds context by providing an example call and listing the default value for the 'list' parameter, and it clarifies that '_apiKey' is optional. This goes beyond the schema's basic descriptions.

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

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

The description clearly states it retrieves a current New York Times bestselling books list, using specific verb 'Get' and resource 'bestselling books list'. It provides examples of list names, which distinguishes it from sibling tools that cover movies (movie_reviews) or other topics (top_stories).

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 what the tool does and gives list name options, but it does not explicitly state when to use this tool versus alternatives or provide when-not-to-use guidance. The context is clear enough for the intended use, but no exclusions or comparisons are offered.

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

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

Adds context beyond annotations: parallel call, specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), off-calendar fiscal year handling, sorting by primary metric, and citation URIs. 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?

Packed with information in one efficient paragraph, but could be slightly more structured. Front-loaded with purpose and usage guidance.

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 two entity types and no output schema, description covers data fetched, sorting, citation URIs, and performance benefit. Very complete.

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

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

Schema coverage is 100%. Description adds meaning by providing examples and constraints for 'values' (tickers/CIKs vs drug names, 2-5 items) and explaining data pulled per 'type'.

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 side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific data sources and trigger phrases. It distinguishes from sequential 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 states 'ALWAYS PREFER over sequential single-pack lookups' and explains it replaces 8-15 lookups. Provides clear context for when to use.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description discloses account/auth gating, paid depth tiers, latency expectations, the exact structure of returned findings (verbatim evidence, confidence, source, fetched_at, citations), gap handling, contradiction scanning, and semantic excerpting. It also states citations are always fetchable, which is a key operational guarantee.

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

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

The description is long but front-loaded and dense, with each sentence contributing necessary context (auth, alternatives, behavior, output format, latency). It could be slightly tightened to reduce length, but it avoids fluff and is well-organized with early placement of critical caveats.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: findings packet structure, gaps[], contradictions[], hop field, citation_uri, and time expectations. It also covers auth, alternatives, and edge cases like breaking news. For a tool of this complexity, the description is nearly complete.

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

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

The input schema already describes both parameters in detail (100% coverage), so baseline is 3. The description adds value by flagging that depth:"thorough" requires a paid plan and by illustrating the kinds of questions the 'question' parameter should contain. The depth behavior (hops, gap recovery) is already in the schema, so this is a modest increment.

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 grounded multi-source research over Pipeworx's structured data sources, decomposing questions into facets and returning a findings packet. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making the purpose unmistakable.

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

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

The description gives concrete when-to-use and when-not-to-use guidance: use it for broad/multi-part structured-data questions, use ask_pipeworx for single lookups or breaking/current-news topics, and use ask_pipeworx if not signed in. It also mentions account requirements and depth tier constraints.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that each result includes full input schemas and curated examples, which reinforces readiness. 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?

One well-structured paragraph, front-loaded with purpose. Lists many domains which adds length but provides concrete examples. Efficient overall.

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 rich annotations and 100% schema coverage, the description adds needed context about when to use (first) and output format (ready-to-call tools). 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 description coverage is 100%. The description only notes aliases for the query parameter, but schema already documents these. No additional parameter meaning beyond schema.

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

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

The description clearly states that the tool finds tools by describing a data or task, with specific examples (SEC filings, financials, FDA drugs). It distinguishes itself from sibling tools by being the discovery/search entry point.

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 'Call this FIRST when you have many tools available and want to see the option set'. Provides clear context for when to use it, including that results are ready to call directly.

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

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

Description adds transparency beyond annotations: explains it fans out across multiple sources in one parallel call, lists what data is returned (CIK, filings, fundamentals, patents, news, LEI), and discloses the patent sunset soft-fail. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint all consistent).

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 relatively long but well-structured: front-loads examples and key usage guidance, then details data sources and limitations. Every sentence adds value. Slight verbosity in examples could be trimmed, but given complexity it's appropriate. Score 4.

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 is returned (CIK, filings with URIs, fundamentals with specific fields, patents news LEI). It also covers limitations (patents soft-fail, name unsupported). Given tool complexity, this is complete enough 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% coverage with descriptions, baseline at 3. Description adds meaningful detail: clarifies that 'value' accepts ticker or zero-padded CIK and explicitly states that names are not supported (redirecting to resolve_entity). For 'type', it confirms only 'company' is supported. Extra context justifies a 4.

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

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

Description clearly states the tool's purpose: produces a full cross-source profile of a US public company. Uses specific verbs like 'profile' and resource 'company'. Differentiates from siblings like 'compare_entities' and 'resolve_entity' by explicitly stating when to prefer this tool over chaining separate 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?

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns against using with names only (directing to 'resolve_entity'). Also notes the patent sunset limitation, giving clear when-to-use and when-not-to-use contexts.

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 destructiveHint=true and readOnlyHint=false, so the bar for additional disclosure is lower. The description adds context about clearing sensitive data but does not elaborate on irreversibility or permissions. It is consistent and sufficient for the tool's simplicity.

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 and usage conditions. Every word earns its place; no unnecessary information 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?

The tool is simple (one parameter, no output schema) with annotations present. The description fully covers what the tool does, when to use it, and how it relates to siblings. No gaps remain.

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

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

The input schema covers 100% of parameters with a clear description for 'key' (Memory key to delete). The description's mention of 'by key' reinforces but does not add new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description uses the clear verb 'Delete' and specifies the resource as 'previously stored memory by key.' It distinguishes from siblings 'remember' and 'recall' by explicitly pairing with them, making the tool's role in the memory lifecycle 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 usage contexts: when context is stale, task is done, or to clear sensitive data. It also advises pairing with 'remember' and 'recall', offering clear guidance on alternatives and workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral details: fetches page, extracts title/description/key links, emits standard llms.txt format. No contradictions.

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

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

The description is a single, front-loaded paragraph with no wasted words. Every sentence adds value: purpose, process, and use cases.

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

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

For a tool with 2 parameters, full schema coverage, no output schema, and rich annotations, the description adequately explains the output format and use cases. No gaps.

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

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

Input schema covers 100% of parameters with descriptions. The description supplements by giving an example URL format and default/max values for max_links, adding meaningful context beyond the schema.

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

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

The description uses a specific verb 'generate' and resource 'llms.txt file', and clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by specifying the unique output format and use case.

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 three use cases (getting a client's site indexed, drafting for own project, auditing competitor), providing clear context for when to use the tool. It does not state when not to use, but the guidance is strong.

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 signal read-only and idempotent behavior. The description adds concrete return fields and the default 'active' filter, which is useful context beyond annotations.

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

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

Two sentences that are direct and front-loaded with the action. Every word adds value with no extraneous content.

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

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

For a simple list tool with one optional parameter, the description covers purpose, return fields, usage advice, and is backed by strong annotations. No gaps.

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

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

Schema coverage is 100% with a clear description for 'include_inactive'. The tool description does not add any additional semantics beyond the schema, meeting 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 action (list), resource (caller's subscriptions), and scope (active). It distinguishes itself from siblings like 'subscribe' and 'unsubscribe' by focusing on reviewing existing subscriptions.

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

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

Explicitly advises when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This implies when not to use (e.g., when creating or canceling) by directing to alternatives.

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

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

Annotations already indicate safe read-only behavior. The description adds value by listing return fields (title, summary, byline, publication date, URL) and includes an example, providing useful context beyond the annotations.

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

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

The description is two sentences plus an example, front-loaded with the action. Every word serves a purpose, and the example illustrates usage efficiently.

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

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

Given the absence of an output schema, the description explicitly lists return fields. The input schema is fully documented, and the description provides a complete overview of what the tool does, its optional parameters, and a usage example.

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

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

While the schema already covers all three parameters (100% coverage), the description provides a concise summary of their purpose and an example usage, which aids understanding without repeating schema 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 verb 'Search' and the resource 'New York Times movie reviews'. It specifies optional filters (query or critics picks) and provides an example, making the tool's purpose unambiguous and distinct from broader search tools like 'search_articles'.

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

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

The description clearly conveys the tool's scope (movie reviews) with optional filters, but does not explicitly state when to avoid this tool or mention alternative tools. The context is clear enough for appropriate selection.

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

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

The annotations only provide generic false hints; the description adds substantial behavioral context: rate-limited to 5 per identifier per day, free/no quota, claim_token workflow, daily digest/roadmap impact, and the instruction not to paste end-user prompts. This goes well beyond the structured fields.

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

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

The description is fairly long but well-structured: purpose first, then use cases, exclusions, mechanics, and constraints. Most sentences earn their place; the 'daily digests/signal' sentence is motivational rather than necessary, but overall it is clear and front-loaded.

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

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

With no output schema, the description explains the response mechanism well: filing without an account returns a claim_token that can later be used to read resolution status. It also covers rate limiting, scope exclusions, and formatting guidance, leaving only minor ambiguity about behavior when filing with an account.

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 covers all four parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful extra semantics: the exact claim_token format and behavior, 'with no other arguments' when checking a claim, and guidance to describe issues in terms of Pipeworx tools/packs rather than pasting 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 phrase ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates distinct use cases: bug, feature/data_gap, and praise. It also clearly scopes the tool to this Pipeworx connection, separating it from sibling query/information tools like 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?

Provides explicit when-to-use guidance for each feedback category and an explicit exclusion for tools from other MCP servers, directing the agent to file those elsewhere. It also offers a disambiguation rule: 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: data derived from CF analytics-engine, no PII, and caching (5min-1h). This goes beyond the annotations to inform the agent about data freshness and privacy.

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

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

The description is concise with 5 sentences, each adding value. It is front-loaded with the core functionality, followed by use cases and caveats. 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 the tool's simplicity (one optional param, no output schema), the description is complete. It explains what is returned, the available window options, use cases, caching, and data privacy. An agent has everything needed to decide when and how to use this 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?

The single parameter 'window' is fully covered by the schema (100% coverage) with an enum and description. The description adds meaningful context by explaining that shorter windows surface current hotness and longer windows show steady-state demand, enhancing the schema's explanation.

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

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

The description clearly states what the tool does: returns top tools, packs, and call volume over a recent window. It uses specific verbs ('Returns') and resources ('top tools, top packs, and total call volume'), and the window parameter is explicitly defined. This differentiates it well from sibling tools that focus on asking questions or searching.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, seeing alignment) and explains the caching behavior. However, it does not explicitly state when not to use this tool or mention alternatives, which would elevate the score to 5.

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

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

The description discloses numerous behavioral traits: semantic anchor with Jaccard similarity threshold, partition filter dropping placeholder slugs, fill check against live CLOB depth. These go well beyond the annotations (readOnlyHint, idempotentHint) and provide crucial context for safe usage.

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 verbose, but every sentence adds value. It is front-loaded with the core purpose and structured by function call variants. Slightly lengthy but justified by the tool's complexity; could be tightened without losing clarity.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill_check) and covers edge cases (low similarity, placeholders). It provides enough context for an agent to understand inputs, outputs, and failure modes.

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

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

With 100% schema coverage, the baseline is 3, but the description adds rich semantics: explains each parameter's purpose, provides examples of valid values (slugs, URLs, seed questions), and contrasts the two modes. This far exceeds the schema's brief descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three operational modes (trending_scan, event, topic) and distinguishes itself by referencing a sibling tool (polymarket_fill_risk) for custom sizing.

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

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

Explicit guidance on when to use no args, event, or topic. It recommends event for specific markets and explains cross-event mode catches patterns missed by single-event. It also advises against trading when fill check shows realizable_edge_pp <= 0 and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false, all consistent with the description. The description adds rich behavioral context: caching at KV level keyed on all knobs, edge computation net of slippage, Kelly fraction caps at 0.25, 24h-move warnings, and filtering logic (e.g., placeholder-slug filtering). No contradictions and 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 lengthy and dense, packing details on model families, statistics, and knobs into a single paragraph. While structured with numbered segments and bullet-like items, it would benefit from clearer grouping or shorter sentences. Some technical jargon (e.g., 'lognormal barrier from 90d FRED log-returns') could be slimmed for general agent use.

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

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

Given the tool's complexity (9 parameters, three model families, diagnostics, caching, no output schema), the description explains the response top-level structure (`by_segment`, `fed_candidates`, `_diagnostics`), caching behavior, and key edge statistics. It is largely complete for an agent to understand what the tool returns and how to tune it, though the sheer volume of information might be overwhelming.

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 covers all 9 parameters with descriptions (100% coverage). The tool description adds further nuance, e.g., for `min_partition_leg_kelly` it clarifies that `min_kelly` does not filter partitions, and for `slippage_pp` it explains Polymarket's fee structure and rationale. This goes beyond the schema, though some parameter descriptions (like `limit`) are simply restated.

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

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

The description begins with a clear verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinctly positions the tool for identifying mispriced bets, separating it from sibling tools like `polymarket_arbitrage` (arbitrage) and `polymarket_edge_tracker` (tracking). The three model families and response segments are explicitly enumerated.

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 opens with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' giving clear use context. It outlines when to use each segment (e.g., concentrated longshots are 'rare-by-design') and describes the filtering knobs (min_liquidity, max_spread_pp). However, it does not explicitly state when not to use this tool or name alternatives for specific scenarios, which would strengthen the guidance.

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

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

The description provides extensive behavioral context beyond annotations: snapshots are written on cache-miss, gaps are possible, decay numbers come from daily closes of edge_pp_net (net of default slippage), not intraday. Annotations already indicate readOnlyHint and idempotentHint, but the description adds nuance about data freshness and computation, with no contradictions.

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

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

The description is somewhat verbose but well-structured: it starts with a clear purpose, then the question, then arguments, then a detailed response format. Each sentence adds value, but there is minor redundancy (e.g., 'days' explained twice). Front-loading is effective.

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

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

Despite having no output schema, the description thoroughly explains the return format (tracked, expired, snapshot_dates) and their contents, including edge_pp_net time-series, first_seen, trend, decay_pp_per_day, lifespan_days, and snapshot_dates. It also covers limits (60-day TTL). This is complete for the tool's complexity.

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

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

Schema coverage is 100%, and the input schema already documents both parameters (days, window) with descriptions. The tool description repeats this information with slight variation (max 30 vs clamp 2-30) but does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description explicitly states it provides 'Edge persistence and decay telemetry' and answers a specific question about how long an edge has existed and whether it is shrinking. It distinguishes from sibling tools by focusing on longitudinal analysis, while 'polymarket_edges' likely provides current snapshots.

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

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

The description clearly implies when to use the tool (to understand edge persistence and decay) by describing its output (tracked, expired, snapshot_dates). However, it does not explicitly state when not to use it or name alternatives, though the context and output structure make the use case evident.

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 rich behavioral context beyond the annotations: it explains the ladder-walking algorithm, return fields (top_of_book, vwap_fill_price, slippage, etc.), and warns about unhedged directional risk from partial basket fills. It is consistent with annotations (readOnlyHint, idempotentHint, openWorldHint) and adds valuable detail.

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

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

The description is well-structured with sections (SINGLE-MARKET, BASKET) and bullet-point-like lists, front-loading the purpose. While lengthy, every sentence is informative and justified by the tool's complexity. Minor deduction for density, but overall 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 absence of an output schema, the description thoroughly covers return values for both modes (e.g., top_of_book, vwap_fill_price, thin_legs). It also includes usage constraints, behavioral warnings, and parameter defaults. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains the default side logic in basket mode ('auto'), interprets size_usd for baskets as settlement notional per leg, and clarifies market/event usage. This justifies a 4.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It specifies distinct modes (single-market and basket), lists return fields, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk assessment.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable, partial fills create directional risk) and provides parameter requirements (one of market or event).

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 behaviors beyond annotations: compatibility scenarios, temporal alignment, skipped cross types, and when spreads are meaningless. No contradiction with readOnlyHint/openWorldHint.

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

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

Well-structured with sections for modes, response, and safety fields. Though lengthy, every sentence adds value. Could be slightly more concise, but front-loaded with core purpose.

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

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

Despite no output schema, the description thoroughly explains response fields (prices, spreads, compatibility warnings, temporal alignment). Covers edge cases and conditions for meaningful spreads.

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, but the description adds value by listing all topic shortcuts, providing examples, and explaining parameter overrides. Slight redundancy with schema, but still additive.

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

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

The description clearly states it is a cross-venue spread tool between Kalshi and Polymarket for the same resolving question, with two modes (topic shortcuts and explicit tickers). It distinguishes itself from siblings like polymarket_arbitrage by focusing on matched question spreads.

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 guidance: topic mode for pre-mapped macro shortcuts, explicit mode for custom pairings. Warns that most pre-mapped topics return compatibility warnings and that real spreads are rarer than the list suggests.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral details about scoping (by anon IP, key hash, or account ID) and the effect of omitting the key parameter, providing extra context beyond annotations.

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

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

Three concise sentences with no redundancy: first defines the core action, second provides usage motivation, third adds scoping and mentions companion tools. Front-loaded and efficient.

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

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

For a 1-parameter tool with rich annotations, the description adequately covers usage, scope, and pairing. While an explicit mention of return format (value or list) would be nice, the overall context is sufficient.

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

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

The schema already covers 100% of parameter descriptions, but the tool description reinforces the meaning with real-world usage examples and storage context, adding value beyond the schema.

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

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

The description clearly states the tool's action: retrieve a value by key or list all keys, and explicitly names the related tools 'remember' and 'forget', distinguishing it from siblings.

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

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

The text explains when to use the tool (look up previously stored context to avoid re-derivation) and mentions scoping to the user's identifier. It could be more explicit about when not to use it, but the context is clear.

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

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

The description discusses a 'mark_read' parameter that flags events as read, implying state mutation. However, annotations declare 'readOnlyHint: true', indicating no side effects. This is a direct contradiction, reducing transparency and potentially misleading the AI agent.

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, consisting of three clear sentences. It front-loads the purpose, then details key parameters and behavior, and ends with an alternative access method. No superfluous information; every sentence adds value.

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

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

Given the tool has 5 optional parameters and no output schema, the description covers the main functionality, returned fields, filtering, and mark_read behavior. It also mentions polling suitability and a REST alternative. However, it omits details on 'limit' and 'unread_only' parameters, which are only in the schema. Still largely complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to use 'type' with an example ('sec_8k'), describing 'since' as an ISO timestamp, and clarifying the behavior of 'mark_read' (flags events read, affects future calls). 'limit' and 'unread_only' are not elaborated, but overall parameter understanding is enhanced.

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 pulls fired events from a subscription feed, specifying the resource (subscription feed) and action (pull/return). It mentions returning specific fields and filtering options. However, it does not explicitly distinguish from sibling tools like 'list_subscriptions', which list subscriptions themselves, but the context of 'alerts' and 'events' provides adequate differentiation.

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

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

The description implies usage for retrieving recent alerts from a persisted feed, with filtering and mark-read functionality. It mentions polling and an alternative REST endpoint, but does not explicitly state when to use this tool versus siblings or when not to use it. Guidance is present but not comprehensive.

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, openWorldHint, and destructiveHint. The description adds substantial behavioral context: internal fan-out logic, GDELT→GNews fallback, patent API sunset handling, and return structure. No contradictions with annotations.

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

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

The description is fairly long but well-structured, front-loading usage examples and then explaining behavior. Every sentence adds value, though minor tightening could improve conciseness.

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

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

No output schema exists, but the description explains the return format (changes grouped by source, total_changes count, citation URIs). It covers edge cases (patent API sunset) and all 3 required parameters. For a complex multi-source tool, this is very complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds guidance for 'since' (prefer '30d' or '1m') and explains 'value' accepts ticker or CIK. This extra context justifies a 4 despite high schema coverage.

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

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

The description clearly states it provides a change feed for a company (SEC filings, news, patents) within a time window. It explicitly distinguishes itself from the sibling tool entity_profile by noting when to use that instead.

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

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

The description gives explicit usage scenarios (e.g., 'What's new with X'), explains the tool fans out to multiple sources, and suggests using entity_profile for static profiles. It also covers optional fallback behavior and parameters.

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

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

Adds significant context beyond annotations: key-value pair scoped by identifier, persistence differences for authenticated vs. anonymous users (persistent vs. 24-hour). Annotations already indicate idempotent and non-destructive, so description complements well.

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

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

Four sentences, each serving a purpose: purpose, usage guidance, examples, behavioral details. No wasted words, front-loaded with core function.

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

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

For a simple key-value memory tool with no output schema, description covers purpose, usage, behavior, persistence, and sibling pairing. No gaps given tool complexity.

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

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

Schema coverage is 100% with descriptions for both key and value. Description provides usage examples (e.g., 'subject_property') adding minor value, but does not go beyond schema detail. Baseline 3 is appropriate.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions. Verb 'save' and resource 'data' are specific. Distinguishes from siblings by naming recall and forget, making 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?

Explicitly says when to use: when discovering something worth carrying forward (resolved ticker, target address, etc.). Pairs with recall and forget, but does not specify when not to use it.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses that the call 'cascades through several lookup endpoints internally' and returns specific fields like CIK, RxCUI, and citation URIs. It also notes auto-disambiguation for company names. 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 somewhat long but front-loaded with a clear purpose and uses formatting (examples, bullet-like list) to structure supporting details. Every sentence contributes value, though it could be tightened.

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

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

Given only 2 params and no output schema, the description thoroughly covers inputs, outputs, citations, and the tool's internal behavior. It is sufficient for an agent to select and invoke the tool correctly in most scenarios.

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?

Both parameters are already described in the schema, but the description enriches this with concrete input formats (ticker, CIK, name; brand/generic) and output expectations per type. It adds meaning beyond the bare schema, especially for the 'type' enum which lacks per-value 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 opens with concrete example queries and states 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It clearly distinguishes from siblings by naming the niche (name-to-ID resolution) and notes 'Use FIRST whenever you have a name but need an ID.'

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 directs when to use: 'Use FIRST whenever you have a name but need an ID.' It also provides alternative context by listing supported types and mentioning that it replaces 2-3 manual lookups, implying it's more efficient than manual searches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it describes the process (probes each entity with ai_visibility_check, ranks, surfaces results) and hints at dependencies (requires _apiKey for anthropic model). It does not contradict annotations and provides useful process details beyond structured data.

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 with no wasted words. The first sentence states the core action, the second details the process, and the third provides a use case and return format. It is front-loaded and efficiently covers all necessary information.

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

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

Given there is no output schema, the description explains the return format: 'ranked list with score, confidence, signal density per entity.' It also covers all inputs, including the role of the first entity and the optional context parameter. The description is complete for a tool with 4 parameters and no 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 description coverage is 100%, so the description does not need to compensate for missing schema details. However, the description adds extra semantics: it explains that the first entity in 'entities' is treated as the 'subject' for narrative, and that 'context' disambiguates common names. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It differentiates itself from sibling tools like ai_visibility_check and compare_entities by being specifically for multi-entity competitive AI presence audits.

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

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

The description explicitly states it is useful for competitive AI-marketing audits and provides an example question. It implies when to use (comparing multiple entities' AI visibility) and implicitly differentiates from single-entity checks. However, it does not explicitly state when not to use or list alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral details: partial failures, bundlephobia timing (5-30s), graceful degradation with sources_failed. 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 lengthy but each sentence serves a purpose. It front-loads the core purpose and then details behaviors. Could be slightly tightened, but no superfluous content.

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

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

Despite no output schema, the description enumerates return fields (summary block, advisories, links, alternatives) and covers edge cases (partial failures, timeouts). Adequately complete for a composite 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 description coverage is 100%, so the schema already documents both parameters. The description adds minor context (version defaults to latest, scoped packages accepted), but does not significantly augment understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's composite purpose ('should I add this npm package') and distinguishes it from sibling tools by specifying it combines deps.dev and bundlephobia for npm packages. It is specific and avoids tautology.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small"' and clarifies NPM-only scope, with alternatives for other ecosystems (deps.dev:version directly). No ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds value by specifying what fields are returned (headlines, abstracts, etc.) and providing an example call, but does not disclose rate limits or pagination limits beyond what the schema provides.

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

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

Description is extremely concise with one sentence and one example. It is front-loaded with the core purpose, and every element is informative. 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 tool has comprehensive annotations and a fully described schema, the description is complete enough for a search tool. It covers what the tool does and what it returns, though it does not explain pagination or result limits beyond what is in the schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning to parameters beyond what is in the schema; the example merely illustrates usage but does not clarify semantics further.

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 'Full-text search of New York Times news articles', providing a specific verb and resource. It distinguishes from siblings like top_stories and movie_reviews by focusing on full-text search rather than curated lists or reviews.

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

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

The description clearly implies when to use: when a full-text search across NYT articles is needed. An example is provided, but no explicit when-not-to-use or alternatives are stated, though the tool's purpose is sufficiently clear for an AI agent.

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 algorithm (BGE-base-en embeddings + cosine), chunking (500-char overlapping windows), character cap (200K chars) with truncation behavior, and that passages include offsets for verification. Annotations already indicate safety; description adds rich behavioral detail.

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 dense sentences followed by a technical detail. No wasted words. Front-loaded with purpose and use case. Every sentence adds critical 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 input constraints, algorithm, output format (offsets, similarity scores), truncation, and pairing with sibling tool. No output schema but description sufficiently explains return values. Complete for a complex 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. The description adds value with examples for query ('supply-chain risk', etc.) and explicit char limit for text, and clarifies that limit is max passages (1-20). Enhances understanding beyond schema alone.

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 clearly: 'Semantic search INSIDE a fetched record.' Explains the resource (text inside a record), the action (search), and the output (top-N passages with offsets). Differentiates from sibling tools like 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 says 'Use when the record is too big to cram into the prompt.' Provides context on when to use and not use, and pairs with ask_pipeworx_grounded as an alternative for grounding.

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 idempotentHint=true and readOnlyHint=false. The description adds behavioral details beyond annotations: requires OAuth, phone verification, 10/day SMS cap, webhook auto-disable after 10 failures, and that the webhook secret is returned only once. No contradictions with annotations.

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

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

The description is lengthy but front-loaded with the core purpose. Each sentence adds necessary detail; however, it could be slightly more structured (e.g., bullet points for types). Overall, it is well-organized and not overly verbose.

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

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

Despite no output schema, the description states it returns the subscription ID and covers all critical aspects: types, params, delivery options, limitations, and side effects (e.g., webhook secret returned once). The tool is fully specified 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 significant value with concrete examples for each type (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}'), explains nested params, and clarifies delivery constraints (phone verification, webhook signing). This goes well beyond the schema alone.

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 the specific verb 'create' and resource 'proactive monitoring subscription to a live-data event stream', clearly distinguishing it from siblings like 'unsubscribe' and 'list_subscriptions'. It also details types and delivery channels, making 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 gives explicit guidance on when to use (proactive monitoring) and requirements (Pipeworx OAuth account, cannot use anonymous/BYO). It also covers delivery options, limitations (10/day SMS cap, phone verification), and type-specific details. It does not explicitly state when not to use, but the context and constraints are well-covered.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description's role is to add context. It clarifies that the tool draws from a live catalog of thousands of tools and returns exact tool + argument shape, which adds value. No contradictions.

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

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

The description is a single paragraph that front-loads the key question phrases. However, it is somewhat verbose with a long list of categories, which could be trimmed. Still, it earns its content without being excessively long.

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

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

Given no output schema, the description explains what is returned (category-bucketed example questions with tool + argument shape) and covers the input parameter. It also mentions meta-tools. It lacks details on error handling or output format but is sufficient for this onboarding 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?

The schema has 1 parameter with 100% coverage. The description expands on the schema by listing the optional focus areas (finance, pharma, etc.) and explaining the effect of omitting or providing the topic, going beyond the schema's minimal 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 the tool is the onboarding entry point that returns category-bucketed example questions. It specifies the verb 'returns' and the resource 'example questions', and distinguishes it from siblings like 'discover_tools' and 'ask_pipeworx' by being the first-use tool.

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

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

Explicitly states when to use: '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 names alternatives such as 'ask_pipeworx, entity_profile, compare_entities, etc.' providing clear guidance on context.

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

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

Annotations already provide comprehensive behavioral hints (readOnly, openWorld, idempotent, non-destructive). The description adds the fact that an API key can be optionally overridden, but does not disclose further behaviors like rate limits or pagination. With strong annotation coverage, the description adds modest value.

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 with an inline example, front-loading the purpose and key parameters. Every sentence adds value with no filler. The structure is efficient and easy to parse.

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

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

Even without an output schema, the description specifies the return fields (titles, abstracts, bylines, URLs), covering essential context. Parameters are fully documented and the example clarifies usage. The tool is simple and the description is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it provides a usage example, notes the default section, and explains the optional API key parameter. This extra semantic depth earns a 4.

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

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

The description clearly states the verb 'Get', the resource 'New York Times top stories', and the scope 'for a section'. It lists the return fields and provides an example, making the purpose unmistakable. It also implicitly distinguishes from sibling tools like 'search_articles' or 'movie_reviews'.

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 fetching top stories by section but does not explicitly state when to use this tool versus alternatives. It lacks guidance on excluded cases or comparisons to siblings, leaving the agent to infer context from the description alone.

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 nondestructive behavior ('deactivated, not deleted') and retention of historical data, adding significant context beyond annotations. 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?

Three efficient sentences with front-loaded purpose, no redundancy, every sentence contributes 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 one-parameter tool without output schema, the description fully covers usage, behavior, and side effects.

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?

Description adds value by specifying the origin of the id ('returned by subscribe'), complementing the schema which already has 100% 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 the action ('Cancel a subscription by id') with specific verb and resource. Distinguishes from 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 explicit ownership constraint ('you can only cancel your own subscriptions'), guiding appropriate use. Does not explicitly mention alternatives, 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 indicate readOnly and idempotent. The description adds details about two different pipelines (SEC EDGAR for financial claims, grounded pipeline for others), the return format (verdict, evidence, reasoning), and that it replaces multiple calls. No contradiction with annotations.

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

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

The description is front-loaded with trigger phrases and is well-structured. It is slightly long (5 sentences) but each sentence adds value without redundancy.

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

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

Despite no output schema, the description clearly explains the return values (verdict types, actual value with citation, reasoning) and the two processing paths, making it complete for a complex tool.

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

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

Schema coverage is 100%, baseline 3. The description adds examples for 'claim' and explains that 'tolerance_pct' overrides implied tolerance, 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 uses trigger phrases like 'Is it true that...' and clearly states it is for natural-language claim verification against authoritative sources. It differentiates from sibling tools by noting it replaces 4-6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check factual correctness,' and provides specific guidance on handling company-financial claims vs. other claims. It does not mention when NOT to use, 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.