Tax Regulations

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: the cost implication of using Anthropic ('you pay Anthropic directly'), the default model choice, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This is useful, though it doesn't cover failure modes or rate limits.

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

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

The description is compact and front-loaded with the primary purpose. Every sentence adds value: purpose, default behavior/cost, return format, and use cases. There is no redundancy or filler.

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

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

Despite having no output schema, the description explains the return format precisely. It covers default behavior, API key usage, cost implications, and typical use cases. With 4 parameters (1 required) and no output schema, this description is fully adequate for an agent to understand the tool's behavior and expected outputs.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying the default model ('Workers AI Llama-3.3-70b (free)') and clarifying the relationship between `_apiKey` and `models` (passing `_apiKey` enables Anthropic probing). It also explains the score scale (0-100), which is not fully captured in the schema properties.

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 ('Probe one or more LLMs'), the resource (LLMs), and the specific output (visibility score 0-100 per model). It distinguishes itself from sibling tools by emphasizing scoring and per-model analysis, and it mentions concrete use cases like AI-marketing audits and competitive monitoring.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic probing. It does not explicitly mention alternatives or exclusions, but the guidance is clear enough for an agent to select this tool for relevant tasks.

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

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

Annotations already establish read-only, idempotent, open-world behavior. The description adds valuable behavioral context: it routes to one of 5,529 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is one fast call. This goes well beyond the structured annotations.

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

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

The description is long but information-dense and well-structured: preference, mechanism, usage triggers, examples, default status, alternatives, and special cases. Every sentence earns its place; no filler or redundancy.

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

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

For a router with this complexity, the description covers purpose, behavior, output format, usage conditions, and differentiation from alternatives. Even without an output schema, it mentions the return format (structured answer with citations). It is comprehensive and leaves little ambiguity for an agent.

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

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

Schema description coverage is 100% with all parameters (question and five aliases) described in detail. The description itself doesn't add parameter syntax but provides illustrative examples of valid questions (e.g., 'current US unemployment rate'), which is helpful. Baseline 3 is appropriate since the schema already does the heavy lifting.

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 answers factual questions about current or historical data across many domains, routes to relevant sources, and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, giving it a specific role as the default 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?

Provides explicit when-to-use triggers ('what is', 'look up', 'find', 'get the latest', etc.), says 'START HERE for most questions', and names alternatives with conditions: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded' and 'for a broad/multi-part question... use deep_research'. It also clarifies that breaking-news is already 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 read-only, open-world, idempotent, non-destructive, but the description adds significant behavioral context: it may have candidate routing improvements, currently none active, falls back to nothing, and is a full working router. This transparently discloses the experimental edge and comparison behavior, exceeding annotation coverage.

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

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

The description is compact but covers essential information: beta status, relationship to ask_pipeworx, current state, usage direction, and comparison behavior. Each sentence earns its place, though some redundancy exists between 'identical universal router' and 'matches ask_pipeworx exactly.'

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 existence of a sibling stable version, the description fully orients the agent: what it is, what it does, how to use it, and what to expect. It also addresses return shape by referencing the same response shape as ask_pipeworx, compensating for the lack of an output schema.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question.' The description does not add parameter details, which is acceptable given the schema already documents them. Baseline 3 applies.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router, and explicitly differentiates it from the stable ask_pipeworx by noting candidate routing improvements. It states the exact scope (same 5,529 tools, same arguments, same response shape) and current behavior (no candidate active, matches ask_pipeworx exactly). This distinguishes it from sibling tools like ask_pipeworx and 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?

Provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the experimental context and that results are compared against the stable router. This implies when not to use it (when you want stable production behavior) and names the alternative (ask_pipeworx).

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?

Goes well beyond the annotations by detailing the exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and listing specific refusal_reason values. It also states the tool uses 'ONLY what the tool result contains' to prevent hallucination. Annotations are consistent (readOnly, openWorld, idempotent) and the description adds substantial behavioral context.

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

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

The description is front-loaded with the core purpose and provides dense, well-organized information: behavior, return structure, refusal modes, usage examples, and cost comparison. Every sentence is informative with no filler or repetition.

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

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

Given the tool's complexity (routing across thousands of tools), no output schema, and the need for trust in high-stakes answers, the description is remarkably complete. It explains success and refusal outputs, use cases, and cost implications, leaving no critical 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 clear descriptions for the question parameter and aliases. The description adds extra meaning by explaining that the question drives routing across 5,529 tools and fills arguments automatically, which clarifies how the parameter is processed beyond its literal schema.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb ('EXTRACTS the answer') and resource (Pipeworx routing across 5,529 tools). It distinguishes itself from sibling ask_pipeworx by emphasizing evidence-backed answers and explicit refusal behavior.

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

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

Explicit when-to-use guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost tradeoff (one extra LLM call), making the alternative 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?

Discloses far more than annotations: resolver match confidence levels, low-confidence short-circuit, closed/dead market handling, wide-spread market warnings, and resolution-rule risk parsing. It even warns agents to inspect resolver fields 'before trusting the analysis block.' No contradiction with the readOnly/idempotent/destructive annotations.

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

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

Description is long but extremely well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) that make it scannable. While every sentence carries value, a few redundancies exist (e.g., market closed status repeated). For its complexity, the length is justified.

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

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

No output schema exists, so the description must fully document return shapes and edge cases. It covers result.market, result.analysis, result.evidence, parent_event, news fields, and status blockers. It also explains safety mechanisms and resolution-risk parsing. This is complete for an agent to invoke and interpret results without ambiguity.

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 explains the difference between quick ('2-3 evidence sources') and thorough ('full fan-out'), implications of include_raw (payload size and use cases), and shows acceptable market formats with examples. This elevates the score to 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?

States its purpose explicitly and specifically: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly distinguishes it from sibling tools that track edges, arbs, or scan competitors, making it easy to select for bet-specific research.

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

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

Provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives fan-out examples by category, giving agents a concrete sense of when and how to invoke the tool.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses substantial behavioral details: it pulls from SEC EDGAR/XBRL and FAERS, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This far exceeds the baseline set by annotations.

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

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

The description is dense but well-structured, front-loading the core use case with trigger phrases, then efficiently covering data sources, sorting behavior, and return format. Every sentence adds value, with no fluff or redundancy.

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

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

Given two parameters, high schema coverage, and a rich annotation set, the description is fully complete. It explains the source data, fiscal-year handling, sort order, and return format (paired data + URI citations), which is crucial since no output schema exists. It even quantifies the efficiency gain over sequential lookups.

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

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

Schema coverage is 100%, but the description adds meaning by explaining what each type pulls (company financials vs. drug adverse-event counts), sources, and edge-case handling. It enriches the schema's basic descriptions with concrete examples and data provenance, though the schema already defines the parameter structure.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It provides specific trigger phrases and explicitly distinguishes itself from sequential single-entity lookups, making its 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 explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists concrete user phrasings that should trigger this tool, clearly indicating when to use it over alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond by adding account requirements, latency, gaps[] never invented, citation semantics (only when resolvable), contradiction scans, and excerpting behavior. 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 long but every sentence adds necessary context. It is front-loaded with account/alternative guidance and structured logically, though it could be more scannable with paragraph breaks. Still, it is dense with value, not padding.

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 fully explains the return format: findings packet with evidence, confidence, source, fetched_at, citations, gaps[], and contradictions. It covers latency, account tiers, depth semantics, and alternative tools—complete for the tool's complexity.

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

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

Schema has 100% coverage, but the description adds depth: explains depth levels with facet counts, hop behavior, and what 'standard' vs 'thorough' do beyond the enum. It also clarifies the 'question' parameter accepts broad/multi-part natural language.

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

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

The description clearly states a specific verb + resource + scope: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, and explicitly distinguishes itself from open-web search. It also names siblings like ask_pipeworx and states what it is best for.

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

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

Provides explicit when-to-use: broad/multi-part questions over structured data. Gives explicit when-not-to-use: 'For a single lookup use ask_pipeworx' and for breaking news prefer ask_pipeworx. Also adds account/tier conditions with a fallback tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds behavioral context by explaining the return format (top-N tools with names, descriptions, and full input schemas) and the 'ready to call directly, no second schema lookup needed' benefit. It does not contradict annotations.

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

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

The description is front-loaded with the core purpose and includes a domain list that, while lengthy, is useful for understanding coverage. Each sentence contributes: use case, return format, and usage advice. It is slightly verbose but not wasteful.

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

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

Despite having no output schema, the description explains the return format (top-N tools with schemas) and the behavior (ready to call directly). It covers the tool's purpose, usage context, and output well. The tool is simple enough that this description is complete for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (query, q, task, search, description, limit) with descriptions. The description adds no parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It uses a specific verb (find) and resource (tools), and differentiates from sibling tools by positioning itself as a meta-tool for discovering other tools. The extensive domain list further clarifies scope.

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

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

Explicit guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it versus going directly to a specific tool.

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

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

Annotations already declare this read-only, idempotent, and non-destructive. The description adds valuable behavioral detail: it fans out across multiple sources in parallel, returns specific data structures, soft-fails on the USPTO API sunset, and uses a GDELT→GNews fallback. This goes beyond the annotations without contradicting them.

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 clause adds functional information: trigger examples, return structure, source list, fallback behavior, and parameter restrictions. It is front-loaded with the most important usage signal ('ALWAYS PREFER'). It loses a point for being a dense run-on paragraph rather than a more scannable list, but no sentence is wasted.

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 carry the full burden of explaining return values, and it does: it lists cik, company_name, recent_filings with URIs, fundamentals fields, patents status, news source fallback, and LEI. It also covers limitations and preconditions, making the tool fully actionable for an agent.

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

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

The input schema already covers both parameters with detailed descriptions, including format examples ('AAPL', '0000320193') and the restriction on names. The description largely reiterates this, though it adds the 'zero-padded CIK' example and resolves the 'use resolve_entity first' guidance. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description uses specific verbs like 'profile', 'brief me', and 'rundown' to clearly indicate a holistic entity lookup. It explicitly names the resource (US public company) and differentiates itself from sibling tools by stressing 'one parallel call' and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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?

The description explicitly states when to use this tool ('Tell me about X' / 'research Acme' / holistic view) and when not to ('names not supported — use resolve_entity first'). It even provides an explicit alternative chain, making the usage decision unambiguous.

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 destructive nature is covered. The description adds minimal context about the data being previously stored and sensitive data clearing, but doesn't go beyond what annotations and the verb 'delete' already imply. 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?

Two sentences, no wasted words. The purpose statement is front-loaded and the usage guidance follows naturally. Every word earns its place.

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

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

For a single-parameter delete tool with strong annotations (destructive, idempotent) and no output schema, the description covers purpose, usage conditions, and relationship to sibling tools. It is fully adequate for the tool's simplicity.

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

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

Schema description coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description adds no further parameter details, so it doesn't improve upon the schema. Baseline 3 applies.

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

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

The description opens with a specific verb+resource: "Delete a previously stored memory by key." This clearly distinguishes it from siblings like remember and recall, which are explicitly named as paired tools.

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

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

Provides explicit when-to-use scenarios: "context is stale, the task is done, or you want to clear sensitive data." While it doesn't explicitly state when not to use it, the pairing with remember and recall implies the alternatives and the guidance is sufficient for the tool's simplicity.

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 destructiveHint, so safety is covered. The description adds valuable behavioral context: it fetches the page, extracts specific elements, and outputs a 'standard llms.txt markdown format' ready for deployment. This goes beyond the annotations without contradicting them.

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, efficiently front-loaded with the main purpose and followed by process, output, and use cases. Every sentence adds value with no fluff. It earns a perfect score for conciseness and structure.

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 (2 params, no output schema), the description is complete: it explains what it does, how it works, what output to expect, and when to use it. The annotations cover safety and idempotency, so the description covers all gaps and is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, with the schema already describing 'url' and 'max_links' in detail. The description adds only general context (e.g., 'for any URL') but doesn't provide additional parameter semantics beyond what the schema offers. Baseline 3 is appropriate given the 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 what the tool does: 'Generate a production-ready llms.txt file for any URL' and explains the process (fetches page, extracts title/description/key links, emits standard markdown). It distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing specifically on generating llms.txt, and it lists explicit use cases.

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

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

The description provides clear context for when to use the tool: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly state when not to use it or mention alternative tools, but the use cases are specific enough to guide an 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?

Annotations already establish the read-only, non-destructive, idempotent nature. The description adds value by specifying the return fields and noting that only active subscriptions are listed by default, which is not in 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?

Two sentences deliver the purpose, return fields, and usage guidance without redundancy. Every sentence contributes meaningful information.

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

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

For a simple list tool with full schema coverage and strong annotations, the description is complete enough. It covers what is returned and when to use it. Minor gaps like pagination or field details are not critical given the tool's simplicity.

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 documents the only parameter (include_inactive) with full coverage. The description does not add much parameter-specific detail beyond using 'active' in the summary, which aligns with the schema's default behavior.

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

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

The description states 'List the caller's active subscriptions' with a specific verb and resource, and clarifies scope. It distinctly contrasts with sibling tools like subscribe and unsubscribe by focusing on listing, and even enumerates the return fields.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel.' This implies when to use the tool and hints at alternatives (subscribe/unsubscribe), but does not explicitly name them.

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 (which only set readOnlyHint, openWorldHint, idempotentHint, and destructiveHint to false), the description discloses crucial behavioral details: rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and the claim_token return behavior for anonymous use. This significantly exceeds what the annotations convey.

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 contributes essential information: purpose, use cases, exclusions, claim_token mechanics, rate limits, and guidance. It is front-loaded with the primary purpose and maintains a logical flow 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?

With no output schema, the description fully compensates by explaining what to expect (claim_token on initial filing, status/change on later lookup). It also covers operational constraints (rate limits, quota exemption, scope boundaries), making it complete for the tool's complexity.

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

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

While the schema already provides 100% parameter coverage with detailed descriptions, the tool description adds extra context for the claim_token parameter (how to pass it back later) and warns against pasting end-user prompts. This adds value, though the schema already handles most of the semantic load, so 4 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 purpose: to send feedback to the Pipeworx team about broken, missing, or needed functionality. The specific verb 'Tell' combined with the resource 'Pipeworx team' makes it distinct from siblings like ask_pipeworx, and the inclusion of concrete use cases (bug, feature, data_gap, praise) leaves no ambiguity.

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 specifies when to use the tool (for bugs, feature requests, data gaps, praise) and when not to use it (for tools from other MCP servers), even providing a rule of thumb for identification. It also explains the claim_token workflow for follow-up, making the usage scenario fully transparent.

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

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

Annotations already cover safety (read-only, idempotent). The description adds valuable behavioral context: data source (CF analytics-engine), no PII, result structure (pack, tool, count), and caching behavior (5min-1h depending on window). This goes 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 concise yet comprehensive, with a front-loaded main statement. The 'Useful for' list is structured and every sentence contributes unique information. No filler or redundancy.

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

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

The tool is simple (one optional parameter, read-only) and the description covers what it returns, why it matters, how it's derived, privacy implications, and caching. With no output schema, this level of detail is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the parameter is already fully documented. The description does not add new semantic details about the 'window' parameter beyond the schema; it simply reuses the same values and adds a caching note, which does not enhance parameter understanding.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It distinguishes from siblings like discover_tools by emphasizing it shows what other AI agents are calling on Pipeworx, not a general discovery mechanism.

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

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

It provides three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent demand. It doesn't name alternatives or say when not to use, but the context is clear and actionable.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial non-obvious behavior: trending_scan defaults, partition placeholder filtering, Jaccard similarity threshold, fill_check against live CLOB depth, and the explicit do-not-trade condition when realizable_edge_pp ≤ 0. No contradiction with annotations.

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

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

The description is long but densely packed with unique information, and it uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize behavioral caveats. It is front-loaded with the core purpose and mode selection. Some minor redundancy (e.g., re-explaining partition_check) prevents a perfect score, but every section 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?

Without an output schema, the description compensates by spelling out the response shape (opportunities[], gap_pp, suggested_trade, reasoning, monotonicity violation context, partition_check fields). It covers edge cases (placeholder slugs, low similarity, thin_legs, trade viability) and directs users to polymarket_fill_risk for sizing, making the tool fully usable from the description alone.

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 both parameters already have clear descriptions. The description adds value beyond schema by providing concrete examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), noting that full Polymarket URLs are accepted for event, and explaining the behavioral consequences of choosing each parameter. This is a meaningful enhancement over the schema but not radically new.

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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names distinct modes (event, topic, trending_scan) and distinguishes itself from sibling tools like polymarket_fill_risk by defining its fill_check role and explicitly deferring custom sizing to that sibling.

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

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

Provides explicit when-to-use guidance: 'Call with NO args' for trending scan, 'event (recommended for a specific market)' with slug examples, and 'topic (for cross-event scanning)' with seed question examples. It also names an alternative ('For custom sizing use polymarket_fill_risk') and explains what cross-event mode catches that single-event misses.

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 provide readOnly/idempotent hints, and the description goes far beyond them by disclosing model-family logic, Kelly caps, net-of-slippage edge, a 24h-move warning, caching behavior, diagnostic fields, placeholder filters, and the reason Fed bets are excluded. It also explains why min_kelly does not apply to partition arbs, adding substantial behavioral context.

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

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

The description is information-dense and front-loaded with purpose, but it is extremely long (roughly 350 words) and packs many implementation details that could be deferred to output documentation. While every sentence carries some information, the density makes it harder to scan quickly, so it is not optimally concise.

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

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

Given the tool's complexity, lack of output schema, and nine parameters, the description is exceptionally complete: it explains response segments, per-opportunity fields, knob interactions, diagnostics for empty segments, and caching. An agent would have enough context to select and invoke the tool correctly.

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

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

Although the input schema already documents all 9 parameters, the description enriches them with operational meaning: min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable,' min_partition_leg_kelly applies to per-leg Kelly inside top_legs, and slippage_pp is explained in the context of zero fees but thin depth. This goes well beyond the schema's baseline.

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

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

The description states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' providing a specific verb, resource, and output scope. It also clarifies the intended use case ('what should I bet on today') and differentiates from sibling tools by describing proprietary model families and segments.

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?

Clear use context is given: it is built for discovering betting opportunities without paging hundreds of markets, and it explicitly notes when to be cautious (Fed candidates are excluded from ranking due to unreliable signal). However, it does not name alternative tools for cases like pure arbitrage or fill-risk analysis, so exclusion/alternative guidance is incomplete.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds substantial context: history depth bounded by a 60-day TTL, snapshots written on cache-miss, gaps mean no scan, decay computed from daily closes net of slippage (not intraday), and the response includes expired opportunities with lifespan. This goes far beyond annotation hints and fully explains behavioral quirks.

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

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

The description is long but well-structured: purpose, args, RESPONSE, LIMITS. It is front-loaded with the core purpose. While somewhat verbose, every sentence conveys necessary information, especially given the absence of an output schema. It earns its length but could be tightened slightly.

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

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

Without an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), field meanings, and interpretation (median lifespan as competition clock). It also covers historical limitations and data gap behavior. The tool is moderately complex and this description fully equips an agent to use it correctly.

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

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

The input schema descriptions cover both parameters 100% (days and window, with defaults and allowed values). The description repeats the defaults and adds minor framing ('snapshot family') but does not provide new meaning beyond the schema. Baseline of 3 is appropriate because the schema carries the full 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 states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a clear question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge values.

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 this tool: when you need to assess the age and trend of an edge, noting that 'a fresh wide edge and a 3-week-old wide edge are different trades.' It does not explicitly name alternatives, but the context differentiates it from current-edge tools. It lacks explicit exclusions but the intended use case is clear.

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

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

Beyond readOnly/idempotent annotations, the description discloses mode-specific walk-the-ladder behavior, return fields, defaults, and risk: partial basket fills 'convert an arb into an unhedged directional position' and it names forced_directional_risk. No contradiction with the provided 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 text is long but tightly organized with SINGLE-MARKET/BASKET sections and a USE THIS directive. Each sentence conveys necessary operational detail, and the most important purpose 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 two modes, no output schema, and safety-critical use case, the description is remarkably complete. It lists all return fields per mode, explains parameter interpretation, and covers edge cases like thin legs and forced directional risk, leaving little ambiguity 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?

Although schema coverage is 100%, the description adds essential meaning: size_usd means 'max spend on buys, target proceeds on sells' in single-market but 'settlement notional S' in basket; side has 'auto' behavior in basket; and market/event are explicitly mutually required. This materially supplements the schema.

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

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

The description opens with a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by naming polymarket_arbitrage and polymarket_edges as signals this tool preflights, and enumerates distinct single-market and basket behaviors.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why and warns about partial basket fills becoming unhedged positions, giving clear situational 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?

Even with annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral detail: compatibility_warning trigger conditions, temporal_alignment semantics (aligned:false makes spreads meaningless), and skipped_cross_type/subtype counters explaining what gets dropped and why. It also warns that the spread may be a false signal when bet shapes are non-equivalent. This far exceeds the annotations and provides crucial interpretation guidance.

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

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

The description is long but densely packed and well-organized with clear section markers: 'TWO MODES', 'RESPONSE', 'SAFETY FIELDS'. It is front-loaded with the core purpose and every sentence adds value—explaining modes, response format, edge cases, and limitations. The format uses bold and code to aid scanning, making the length acceptable.

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

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

For a complex tool with no output schema, the description fully explains the return structure (leg-by-leg prices, spread array, compatibility_warning, temporal_alignment, skipped counters) and the meaning of each field. It also covers failure modes and when to distrust results. The annotation richness and parameter schema reduce the burden, but the description goes beyond them to provide complete context for selecting and using the tool.

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

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

Although the input schema already describes all three parameters (100% coverage), the description adds meaningful semantic context: the exact list of 10 topic shortcuts, the override behavior (explicit ticker/slug replaces the topic-mapped side), and format examples. This goes beyond the schema's short descriptions, explaining how parameters interact and which combinations are valid.

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 an explicit, specific definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It goes beyond a simple verb to clarify the tool's unique value (comparing two venues) and differentiates it from siblings like polymarket_arbitrage by focusing on cross-venue spreads. The two operational modes (topic vs explicit) further solidify the purpose.

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

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

The description clearly explains when to use each mode ('TWO MODES') and provides a strong when-not warning: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly name alternative tools (e.g., 'use polymarket_arbitrage for within-venue opportunities'), so it misses the 'alternatives' component for a 5, but the context and exclusions are otherwise 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, idempotent, and non-destructive behavior. The description adds valuable context about scoping ('Scoped to your identifier') and the two modes (retrieve one or list all), going 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 three sentences, front-loaded with the primary action, and every sentence serves a purpose: behavior, usage context, and scoping/alternatives. No waste.

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

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

For a single-optional-parameter read-only tool with full schema coverage and no output schema, the description adequately covers behavior, usage, scoping, and return modes. It is complete without being verbose.

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

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

Schema covers the sole parameter fully ('Memory key to retrieve (omit to list all keys)'). The description reinforces this but does not add significant new parameter-level detail beyond examples of key content, so baseline 3 is appropriate.

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

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

The description clearly states the tool's dual purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs ('retrieve', 'list') and identifies the resource (saved memory), distinguishing it from sibling tools like remember and forget.

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

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

Provides explicit usage context: 'Use to look up context the agent stored earlier' with examples (target ticker, address, research notes) and pairs with 'remember to save, forget to delete.' This clearly communicates when to use recall versus alternatives.

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

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

The annotations mark the tool as readOnlyHint:true, but the description explicitly states that setting mark_read:true "flag[s] returned events read so the next call only shows newer ones." This is a state-changing operation that contradicts the readOnlyHint annotation. Per rubric, any contradiction forces a score of 1.

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

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

The description is four sentences, front-loaded with the core action, and each sentence adds value: return fields, filtering, mark_read side effect, and polling/alternative access. 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?

With no output schema, the description helpfully specifies return fields (source, citation_uri, raw event payload). It covers the main behaviors and parameter interactions. The mark_read contradiction slightly undermines completeness, but the description itself is thorough enough for this simple read 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 input schema has 100% description coverage for all five parameters. The description adds some reinforcement (e.g., filter by type with example "sec_8k", since as ISO timestamp, mark_read behavior) but does not meaningfully expand beyond the schema. Baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Pull fired events from your subscription feed." It clearly defines the tool's scope (alerts written by the evaluator) and distinguishes it from related tools like recent_changes or list_subscriptions by focusing on the subscription feed's event stream.

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

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

The description provides clear context on when to use the tool (pulling fired alerts) and even offers a polling pattern and an alternative HTTP endpoint for scripts/dashboards. It does not explicitly exclude sibling tools, but the context is sufficient to infer appropriate 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?

The description adds substantial behavioral context beyond the annotations: it details the data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains the fallback logic (GDELT preferred, GNews on rate-limit/5xx), and discloses the PatentsView API sunset and soft-fail behavior. It also describes the output structure, which enriches 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?

Although the description is long, it is densely packed with valuable information. Every sentence contributes: examples, data source fan-out, fallback behavior, parameter format, and output summary. The structure is front-loaded with use-case phrases, making it easy to scan for relevance.

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

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

Given the complexity of the tool (three data sources, fallback, output shape, parameter formats), the description is remarkably complete. It covers purpose, input formats, supported values, output structure (changes[], total_changes, citation URIs), failure modes, and a clear alternative. No output schema exists, but the description compensates by summarizing the output shape.

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 all three parameters with descriptions, so the baseline is 3. The description adds value by clarifying 'since' accepts ISO dates or relative shorthand, and recommends '30d' or '1m' for typical monitoring. It also indirectly clarifies 'value' can be a ticker or CIK via examples, though the schema already covers this.

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

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

The description clearly identifies the tool as a change feed for a company, with a specific verb ('what's new', 'latest') and resource (company change feed across SEC, news, patents). It explicitly distinguishes itself from entity_profile, which provides a static profile, making the purpose and scope unambiguous.

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

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

The description gives explicit guidance on when to use this tool versus the alternative: 'Use entity_profile instead when you want the static profile regardless of window.' It also provides typical usage suggestions ('Use "30d" or "1m" for typical monitoring') and explains the fallback behavior between data sources, giving clear context.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds persistence semantics: scoped by identifier, persistent for authenticated users, 24h for anonymous sessions. It also implies the key-value structure and reuse across sessions. No contradiction with annotations.

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

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

Three sentences: main purpose, when-to-use, and persistence/companion pairing. No redundant phrases; information is front-loaded and each sentence adds value.

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

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

For a simple key-value store, this is complete: it states what it does, when to use it, persistence behavior, and related tools. No output schema is needed since the action is a save; annotations cover the safety profile.

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

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

Schema covers both parameters with descriptions and examples; description adds the general rule that value is any text and reinforces key naming patterns. Since schema coverage is 100%, the baseline is 3 and the description adds marginal but not essential detail.

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 ('Save data') and defines the resource (agent memory) plus cross-session scope. It distinguishes itself from sibling tools recall and forget by explicitly naming them, and clarifies the key-value structure. This is more than a tautology and clearly states what the tool does.

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

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

It provides an explicit 'Use when' clause with concrete examples (ticker, address, preference, research subject) and explains the benefit ('so you don't have to look it up again'). It also names the companion tools (recall, forget) for retrieval and deletion, effectively covering alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavioral traits: it cascades through multiple lookup endpoints, degradation behavior when GLEIF/OpenFIGI are unavailable, and that unresolved identifiers are explicitly listed under `unresolved` rather than omitted. This adds significant context without contradicting 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 longer than typical (about 200 words) but every sentence serves a purpose: examples, usage rule, type-specific details, and edge-case behavior. It is front-loaded with user-facing query examples that immediately signal applicability. Slightly verbose, but appropriate for the tool's complexity.

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

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

Despite lacking an output schema, the description explains what the caller receives: canonical identifiers with source labels, unresolved identifiers explicitly stated, and graceful fallback. It covers input formats, supported types, and behavioral edge cases. This makes the tool usable without additional documentation.

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 descriptions, so baseline is 3. However, the description enriches the semantics by giving concrete examples for the value parameter (ticker, CIK, name for company; brand/generic for drug) and clarifying the return behavior per type. This adds value beyond the schema's basic documentation.

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

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

The description clearly identifies the tool's purpose with specific verbs ('resolve') and resource ('user-spoken NAME to canonical identifiers'). It differentiates from likely siblings by emphasizing that it provides the IDs other tools require as input, and explicitly says 'Use FIRST whenever you have a name but need an ID.' The supported types and their outputs are described in detail, making the tool's function 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 a direct usage rule ('Use FIRST whenever you have a name but need an ID') and notes that it replaces 2-3 manual lookups, which clarifies when to invoke it. However, it does not mention alternatives or when not to use it, so it falls short of a perfect 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is covered. The description adds process and output details: it probes each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations, though it omits rate-limit/latency considerations.

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

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

The description is four sentences, each adding distinct value: core purpose, process, use case with an example quote, and return format. It is front-loaded with the purpose in the first sentence and contains no filler.

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

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

For a moderately complex tool with 4 parameters, no output schema, but strong schema descriptions and annotations, the description covers why to use it, how it works, and what it returns. It could mention that multiple probes may take time or that an API key is needed for certain models, but the schema already handles the API key detail, so the description is 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?

Because schema description coverage is 100%, the baseline is 3. The schema already provides detailed descriptions for all parameters, including entities ('first entry treated as the subject') and models ('workers-ai' default, 'anthropic' requires _apiKey). The description adds no new parameter meaning beyond what the schema already explains.

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 'Compare AI visibility across multiple entities side-by-side,' which is a specific verb+resource combination. It further distinguishes itself from the sibling ai_visibility_check by stating that it probes each entity with that tool and ranks the results, making it clear this is the multi-entity aggregation 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?

The description gives a clear use case: 'Useful for competitive AI-marketing audits' with an example query. It implicitly references ai_visibility_check for single-entity probes, but does not explicitly say 'use that instead for one entity.' Thus, there is clear context but no explicit exclusions.

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

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

While annotations already mark readOnlyHint=true, openWorldHint=true, and idempotentHint=true, the description adds genuine behavioral context: it discloses latency (bundlephobia's first measurement can take 5-30s), graceful degradation via 'sources_failed', and the fact that partial results still return. This goes beyond the structured 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 information-dense but well organized: purpose, use-cases, return fields, ecosystem scope, and failure handling are each covered in separate clauses. It is longer than minimal but every phrase contributes meaningful context, and the lead sentence immediately states the core value proposition.

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 (multiple external API integrations) and the lack of an output schema, the description compensates by enumerating return fields (summary block, per-advisory detail, links, alternative versions) and explaining source-specific behavior (bundlephobia timeout handling, NPM-only v1). It gives the agent enough to anticipate output structure and edge cases.

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

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

The input schema fully describes both parameters (package name with scoped package examples and version with default behavior), so schema coverage is 100%. The description adds no additional parameter-level meaning beyond what the schema already provides; it only restates the default version behavior. Baseline 3 is appropriate per the rubric.

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 composite check ('should I add this npm package to my project') and names both upstream services (deps.dev and bundlephobia) with concrete data points (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support). This clearly distinguishes it from sibling research tools and immediately conveys the tool's scope.

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

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

It explicitly states when to use the tool ('Use whenever an agent asks...') and provides negative guidance: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells the agent both appropriate use cases and a fallback alternative, which is exactly what usage guidelines should do.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses the search mechanism (BGE-base-en embeddings + cosine over 500-char overlapping windows), the output structure (passages with character offsets and similarity scores), and a critical truncation behavior (200K char cap, flagged when truncated). This enriches the agent's understanding beyond the structured annotations.

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

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

Three sentences deliver purpose, usage guidance, and technical specifics without redundancy. The first sentence front-loads the core function, the second explains when and why to use it, and the third gives essential operational constraints. 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?

For a tool with no output schema, the description adequately explains the return value (top-N passages with offsets and similarity scores), key constraints (200K char limit, truncation flag), and a clear use case. It also connects to a sibling tool, providing the agent with a complete decision and invocation 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 input schema already fully describes all three parameters (text, limit, query) with 100% coverage, so the baseline is 3. The description adds minimal parameter-specific context beyond examples of text types and query phrasings, which the schema also includes. It does not substantially increase understanding of parameter semantics.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes from siblings by emphasizing the tool operates on text already pulled, not on external data sources, and explicitly contrasts with ask_pipeworx_grounded's workflow. This leaves no ambiguity about the tool's unique function.

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 the tool: 'Use when the record is too big to cram into the prompt.' It also names a complementary alternative, ask_pipeworx_grounded, and explains the pairing workflow ('fetch with the gateway, ground over the relevant passages'), giving the agent clear decision 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 states 'Create ... Returns the new subscription id,' implying each call creates a new subscription, which contradicts the annotation idempotentHint=true. This is a critical inconsistency that misleads the agent about idempotency. The rich behavioral detail (auth, delivery caps, verification) is overshadowed by this contradiction.

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

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

The description is a dense single paragraph, but it front-loads the core purpose and then efficiently enumerates types, channels, and constraints. It is long but every sentence adds necessary value; minor improvement would be breaking into bullets.

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

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

Given the tool's complexity (3 params, nested objects, 5 enum types) and lack of output schema, the description covers essential context: authentication, type-specific params, delivery options, and important limitations. It does not mention error cases or cancellation behavior, but it is sufficiently complete for typical use.

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

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

While the schema already has 100% coverage with descriptions, the description adds concrete examples and constraints: e.g., sec_8k items mapping, phone verification requirement, 10/day SMS cap, webhook auto-disable after 10 failures. This goes well beyond the schema's generic property descriptions.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream.' It names specific resource types (sec_8k, polymarket_edge, fred_series) and delivery channels, making it distinct from sibling tools like list_subscriptions or unsubscribe.

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

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

Provides clear context on prerequisites (OAuth account required, anonymous/BYO cannot persist) and how to consume alerts (via feed, email, SMS). While it doesn't explicitly contrast with alternatives, the usage constraints and delivery options give sufficient guidance for when to use this tool.

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

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

The description fully discloses the tool's behavior: it returns example questions (not actual data), drawn from a live catalog, and can be focused by topic. It complements the annotations by detailing the output format and scope, making the tool's behavior clear beyond what readOnlyHint and idempotentHint convey.

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 well-organized, front-loading the tool's purpose and then detailing usage. Although the leading list of example questions is slightly verbose, each sentence serves a purpose and the structure is logical.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains what is returned, how to invoke it, and when to use it. It goes beyond the schema and annotations to give a full picture, so the agent can use it without ambiguity.

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

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

The schema already documents the single param `topic` with a description of valid values. The description adds examples ('finance', 'pharma', 'betting') but does not introduce new semantics beyond the schema's coverage, so a 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 is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings by positioning itself as the first stop for discovering what Pipeworx can do, unlike ask_pipeworx or discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides direction to learn about specific meta-tools. It also explains when to call with no arguments versus passing a topic, and implies it's for initial discovery rather than direct querying.

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, non-destructive), the description discloses substantial behavior: it returns current in-force wording, strips trailing paragraphs from citations, covers the entire Title 26 scope, and notes 'Keyless' access. These details meaningfully inform an agent about expectations and limitations, going well 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?

The description is long but every sentence delivers unique value: core purpose, example queries, citation forgiveness, part-identification rule, coverage scope, and a concrete example call. It is front-loaded with the action and logically organized, with no fluff. The length is justified by the tool's complexity.

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

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

With no output schema, the description appropriately explains return behavior ('Returns the exact regulatory wording', 'Pass a whole part ... to get a (large) section list'). It also covers scope, input flexibility, and usage examples. The tool's complexity is fully handled; an agent would know exactly what to expect and how to invoke it.

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

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

Even though the schema already describes 'citation' with 100% coverage, the description adds crucial semantics: it explains the dotted format, the rule for identifying the part ('the number BEFORE the first dot'), gives multiple examples, and clarifies that a bare part returns a list. This is far more than the schema provides and directly helps the agent construct valid inputs.

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

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

The description opens with a specific verb and resource: 'Get the full text of one Treasury Regulation / IRS regulation ... by its citation. Returns the exact regulatory wording currently in force.' It provides multiple example natural-language queries ('what does Treas. Reg. 1.170A say') that make the purpose unmistakable. Though it doesn't explicitly distinguish from sibling tax_search, the scope and behavior are so clearly defined that there's no ambiguity.

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

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

The description gives clear context for when to use the tool by listing query phrasings it answers and by explaining that a bare part returns a section list. However, it never mentions when NOT to use it or points to an alternative like tax_search for searching by keyword or topic. This is a clear context with no exclusions, matching a 4.

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?

With annotations already indicating read-only and idempotent behavior, the description adds value by disclosing return format (citation, heading, excerpt, URL) and that it is keyless. It provides useful behavioral context beyond the annotations without contradicting them.

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

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

The description is moderately long but front-loaded with the core purpose. The topic list and examples earn their place by showing scope and usage, though it could be trimmed slightly without losing value.

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

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

Despite having no output schema, the description covers return fields, use cases, and authentication needs, making it complete for a simple search tool. It effectively compensates for the lack of structured output information.

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

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

Schema coverage is 100%, so the description's examples (e.g., query phrases, limit usage) are helpful but mostly reiterate what the schema already documents. It adds minimal extra meaning beyond demonstrating call syntax, so a baseline of 3 is appropriate.

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

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

The description clearly states it performs keyword search across federal tax regulations in 26 CFR, with a specific verb and resource. It distinguishes itself by emphasizing search on topics, implicitly contrasting with sibling tax_regulation which likely handles lookups by citation.

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 example questions it answers ('what tax regulations cover X', etc.) and lists suitable topics. It gives clear context for when to use but does not explicitly mention alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already indicate non-read-only, idempotent, and non-destructive behavior. The description adds meaningful context: the row is deactivated not deleted, historical events remain via recent_alerts, and ownership is enforced. These details go beyond the structured annotations.

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

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

Two concise sentences fully convey the action and key caveats with no redundant wording. The main verb and target are front-loaded immediately.

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

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

For a simple one-parameter mutation tool, the description covers purpose, ownership, deactivation, and historical availability. It lacks error-case behavior or return value expectations, but those are not strictly needed given the tool's simplicity and annotations.

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

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

Schema description coverage is 100% and the only parameter 'id' is already described as the subscription UUID from subscribe. The description merely says 'by id' without adding additional semantics, so it does not elevate beyond the schema baseline.

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

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

The description precisely states 'Cancel a subscription by id' with a specific verb and resource, and distinguishes itself from related siblings like subscribe and list_subscriptions by clarifying the cancellation action and ownership constraint.

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

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

It provides clear usage context by explaining ownership enforcement and the deactivation behavior, but does not explicitly name alternatives or state when not to use the tool. The mention of recent_alerts hints at related workflows, though exclusions are absent.

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

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

The description goes well beyond annotations by clarifying the meaning of nuanced verdicts like could_not_verify and unsupported, and warns that could_not_verify is not evidence and must not be shown as one. It also explains the tool consolidates multiple calls, adding valuable behavioral context not captured in readOnlyHint or idempotentHint.

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

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

The description is long but dense with useful detail; every section serves a purpose (examples, behavior, special cases, consolidation benefit). It is not perfectly front-loaded, and some phrases could be tightened, but overall it is well-organized for a tool with this complexity.

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

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

The description covers return values (verdict list, citation, reasoning), explains special verdict states and their handling, and mentions the tool's ability to replace multiple calls. Given there is no output schema, this level of detail fully equips an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already thoroughly documents both `claim` and `tolerance_pct`. The description adds minor context (e.g., default tolerance capped at 5, use 1-2 for hallucination detection) but largely restates the schema, so baseline 3 is appropriate.

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

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

The description opens with example query phrases and clearly states the tool's function: natural-language claim verification against authoritative sources. It explicitly distinguishes the tool's scope (financial vs. non-financial claims) and notes it replaces multiple sequential steps, setting it apart from sibling research and search tools.

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

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

Provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two distinct paths (SEC EDGAR fast path vs. grounded pipeline) and warns about could_not_verify semantics. However, it does not explicitly name alternative sibling tools or state when not to use this tool, leaving some ambiguity.

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