Epa Regulations

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining that Anthropic calls require a BYO API key and incur direct costs, and it details the return structure. 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 well-structured, with a clear first sentence stating the core purpose, followed by details on models and return format. It is efficient but could be slightly shortened without losing clarity.

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

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

Despite no output schema, the description thoroughly explains the return structure (per-model score, confidence, signals, raw_response plus combined view). It covers use cases, default behavior, and optional configurations. The sibling context is broad, but the tool is distinct enough.

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

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

Schema description coverage is 100% for all 4 parameters. The description adds extra meaning: it explains the action of 'probing', the optionality of models, the need for _apiKey only with Anthropic, and the disambiguation role of context. This is beyond what the schema provides.

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

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

The description clearly states the tool 'probes one or more LLMs' for visibility scoring (0-100), which is a specific verb and resource. It succinctly distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on per-model scoring.

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

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

The description outlines appropriate use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default behavior. However, it does not explicitly mention when not to use the tool or how it differs from similar siblings like 'scan_competitor_ai_presence', which could cause confusion.

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 claim readOnlyHint, openWorldHint, idempotentHint, non-destructive. The description adds valuable routing behavior: it fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and covers live news routing. It doesn't mention rate limits, latency, or failure behavior, but with strong annotation coverage and explicit routing semantics, the added context is meaningful.

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

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

The description is front-loaded with the key routing instruction and compressed list of domains, then gives trigger phrases and examples, then sibling differentiation. It is long but packed with useful routing detail; each sentence earns its place. Slight redundancy between 'SEC filings, ... weather' and the later example list, but no wasted 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 tool with a single natural-language parameter, no output schema, and rich annotations, the description fully equips an agent: when to prefer it, what to expect back (structured answer with citations), and how it differs from grounded and deep research siblings. There is no missing information that would block correct invocation.

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

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

Schema coverage is 100% and the `question` property is described as natural language with aliases. The description's examples ('What was Apple's revenue in 2024?', 'Any recent SEC filings for $NVDA?', 'Current price of bitcoin') add flavor but don't deeply extend schema semantics. Baseline 3 is appropriate because the schema already fully documents the single meaningful parameter.

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

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

The description states a specific verb ('ask', 'routes', 'returns') and a clear resource (Pipeworx, a gateway to 5,743 tools across 1500 verified sources). It distinguishes itself from web search and from sibling tools ask_pipeworx_grounded and deep_research by name and use case. The scope is concrete: factual questions about real-world entities, events, numbers, or data requiring citations.

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 'PREFER OVER WEB SEARCH' for a wide category of factual questions, gives trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), concrete examples, and names alternatives: ask_pipeworx_grounded for hallucination-resistant grounded answers, deep_research for multi-source broad questions, and live-news packs for breaking news. This is strong routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so less safety disclosure is needed. The description adds meaningful behavioral context: experimental candidate routing may be under test, results are compared for merge decisions, there is no fallback, and it is a full working router. This goes beyond annotation data without contradicting it.

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 and mostly efficient, front-loading the core purpose as a beta version of ask_pipeworx. The date and retired-candidate detail are slightly specific but relevant to current behavior, and the final sentence reinforces that it is a real working router, which is useful though slightly emphatic.

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 read-only question-routing tool with one required string parameter, the definition is complete: it specifies equivalence to ask_pipeworx, same response shape, experimental status, and no fallback. It does not define the response shape inline, but explicitly states it matches the stable sibling, which is sufficient context.

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

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

Schema description coverage is 100%, and the schema documents the required question parameter plus aliases, so the description does not need to repeat parameter details. The phrase 'same arguments' adds only cross-reference value and no new semantic information about how to phrase the question.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, states it is an identical universal router with the same 5,743 tools, arguments, and response shape, and distinguishes it from the stable sibling by the experimental routing improvements. This is specific and actionable, not a tautology.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is wanted, and explains that results are compared with the stable router to decide what merges. It also notes that no candidate is currently active, so behavior currently matches ask_pipeworx, giving an agent a clear selection rule.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals critical behavior: it routes across thousands of sources, extracts only from tool results, returns an explicit refusal with specific refusal_reason values, and costs one extra LLM call. This is rich, actionable behavioral disclosure.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return contract, refusal reasons, use cases, and cost tradeoff. The key differentiator is front-loaded in the first sentence.

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

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

With no output schema, the description fully specifies both the success return shape and the refusal return shape, including refusal_reason enum values. An agent has enough context to invoke the tool and interpret the result 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?

Schema coverage is 100%, and all parameters are effectively aliases for the natural-language question. The description does not add parameter-level guidance beyond the schema, but the schema fully documents the accepted aliases. This meets the baseline for 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' which is a specific verb-plus-scope statement. It then distinguishes itself from ask_pipeworx by describing the grounded extraction behavior and the exact success/refusal contract.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and the condition for choosing it: 'prefer ask_pipeworx for casual lookups.'

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

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

Annotations already convey read-only, idempotent, open-world, non-destructive behavior. The description goes far beyond: it details market resolution, classifier fan-out, response field semantics (e.g., market_match_confidence, parent_event, news fallbacks), safety on low-confidence matches, closed market handling, wide-spread warnings, and cancellation rule parsing. This is exemplary transparency.

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

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

The description is lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded purpose. Every sentence adds value for an agent, covering many edge cases without redundancy. Given the tool's complexity, the length is justified and efficient.

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

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

Given the tool's multifaceted nature (resolving markets, fanning out to data sources, returning evidence packets), the description is remarkably complete. It covers match confidence, parent events, news fallbacks, safety mechanisms, closed markets, wide spreads, and cancellation rules. No output schema exists, but the response shapes are well-documented.

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 enriches each parameter: explains market accepts slug/URL/text and gives examples; clarifies depth defaults and trade-offs; describes include_raw with size implications. This adds practical guidance beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and unique capability (one-call comprehensive data pull). The examples and classifier list distinguish it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly advises use for questions like 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It includes warnings to inspect match confidence and mentions illiquid markets. However, it does not compare directly to sibling tools or state when not to use it, which would be helpful.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds contextual details: results sorted by primary metric, returns paired data with citation URIs, handles off-calendar fiscal years for companies, and replaces multiple sequential lookups. No contradictions.

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

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

The description is concise yet comprehensive. It front-loads the purpose with example phrases, then efficiently covers data sources, sorting, output format, and edge cases. Every sentence adds value, and it avoids redundancy with the schema.

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

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

Given no output schema, the description adequately explains what is returned (paired data + citation URIs). It covers entity types, parameter constraints, data sources, sorting behavior, and special handling (off-calendar fiscal years). The tool is complex but thoroughly described.

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

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

Schema coverage is 100% with both parameters described. The description adds significant meaning: for type='company' it specifies data from SEC EDGAR/XBRL including revenue, net income, cash, debt; for type='drug' it specifies FAERS, FDA, trial counts. It also clarifies that values are tickers/CIKs for companies and names for drugs, and the min/max constraints.

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

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

The description clearly states it performs side-by-side comparison of 2-5 entities (companies or drugs) with specific data sources. It provides example natural language phrases and explicitly distinguishes from single-entity lookups by stating 'ALWAYS PREFER over sequential single-pack lookups', effectively differentiating from siblings like entity_profile.

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

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

The description explicitly says when to use the tool (comparison queries like 'compare X and Y', 'rank these companies') and what to prefer it over ('sequential single-pack lookups'). It also explains the behavior for each entity type and the constraints on the values parameter.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the 15-60s latency (up to ~90s for thorough), the explicit gaps[] for unanswered facets, the semantic excerpting behavior, the fetchable citation_uri guarantee, and the contradictions[] scan. It also discloses that open-web topics are not covered. This is strong behavioral disclosure, though it doesn't mention rate limits or concurrency 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 information-dense and front-loaded with the account requirement and the key alternative, but it is quite long and somewhat stream-of-consciousness, mixing multiple topics (account tiers, gap recovery, citations, latency) without clear paragraph or bullet structure. Every sentence carries information, but the wall-of-text format makes it harder for an agent to parse. It earns a 3 for being thorough yet structurally dense.

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 research tool with two parameters and no output schema, the description is remarkably complete. It explains return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), failure behavior (gaps[] never invented), depth semantics, latency expectations, and auth prerequisites. It even explains how large records are excerpted. The only missing piece is explicit statement about what the output JSON looks like, but there's no output schema and the detailed description compensates.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description enriches the depth parameter by explaining the behavioral difference between quick/standard/thorough in terms of hops, gap recovery, and contradiction scanning, which goes beyond the schema's enum descriptions. It also clarifies what 'question' should look like via the broad/multi-part guidance and examples. This adds meaningful value above 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 precisely states the tool's function: grounded multi-source research across Pipeworx's 1500 structured data sources in one call, with decomposition into facets and parallel routing. It clearly differentiates from open-web search and names sibling alternatives like ask_pipeworx for single lookups. The examples of broad/multi-part questions further anchor what the tool is for.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and directly says 'For a single lookup use ask_pipeworx instead.' It also provides an exclusion for live/news topics, recommending ask_pipeworx for those. The account-required condition and depth-tier differences are clearly stated, leaving no ambiguity about when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N tools with full schemas and curated examples, and that each result is ready to call directly. This fully characterizes the tool's behavior.

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

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

The description is well-structured, starting with a clear one-liner and then expanding. It is slightly lengthy but every sentence adds value (lists domains, explains return format, provides usage guidance). Could be marginally tighter but remains efficient.

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

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

Given the complexity (many siblings, no output schema), the description fully describes the return value (top-N tools with names, descriptions, schemas, examples) and how to use it. It is complete for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds clarifying context: explains aliases (task, q, search, description) and provides concrete examples of natural language queries (e.g., 'look up FDA drug approvals'). This adds meaning beyond the schema.

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

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

The description clearly states the purpose as 'Find tools by describing the data or task' and lists many specific domains (SEC filings, FDA drugs, etc.). It distinguishes from sibling tools by framing itself as a discovery tool, not for answering a single query.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies alternatives for direct answers. Also provides example task descriptions.

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 is read-only, idempotent, and non-destructive, and the description adds substantial behavioral context beyond that: it fans out in parallel across multiple sources, reports sources_used/sources_failed, treats empty sections as genuine 'no data' rather than bugs, resolves names via SEC EDGAR, and explains the FDA product nuance. This is rich, non-redundant disclosure that materially changes how an agent interprets results.

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

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

The description is thorough but dense and unstructured, packed into a single run-on flow of examples, return fields, source notes, and edge cases. It is neither concise nor well-sectioned, though nearly every sentence provides useful information. A structured layout with bullets or short paragraphs would significantly improve scanability.

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

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

With no output schema, the description carries the full burden of describing return values, and it delivers: it lists all major response sections (cik, company_name, recent_filings, fundamentals, sec, xbrl, patents, etc.), explains fallback behavior (GDELT→GNews), and clarifies expected empty results. The input handling and failure modes are also fully covered, so an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by giving concrete examples ('AAPL', '0000320193', 'Moderna'), explaining that 'company' and 'ticker' are interchangeable, and detailing name-resolution behavior including the private-company return shape. This adds real semantic value beyond the schema's own parameter descriptions.

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

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

The description opens with concrete user phrasings ('Tell me about X', 'research Acme') and immediately defines the action as 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the exact inputs (ticker, CIK, company name) and the returned sections, making the tool's scope unmistakable and clearly distinct from 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 the tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies the private-company edge case (returns resolved:false rather than failing). It does not name sibling alternatives like compare_entities or deep_research and when to prefer them, so it stops short of full exclusionary guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral details: returns currently in-force wording, forgiving citation input, and behavior for part vs. section queries. 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 somewhat long but every sentence adds value: core purpose, examples, coverage, and disambiguation from sibling tools. It is front-loaded with the essential verb-resource pair. Could be slightly trimmed without loss, but remains efficient.

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

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

For a simple tool with one parameter and no output schema, the description fully explains what is returned (full text or section list) and provides concrete examples. It covers the entire scope of Title 40 regulations, making it complete for any agent.

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

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

Schema coverage is 100% for the single required parameter 'citation'. The description enriches it with examples of valid formats, including paragraph stripping, and clarifies that passing a whole part yields a section list. This adds significant meaning beyond the schema.

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

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

The description states it retrieves the full text of one EPA regulation by citation, listing examples like '40 CFR 261' and '§60.1'. It clearly distinguishes this regulation tool from data tools (epa-echo/epa-emissions), making its purpose unambiguous.

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

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

Explicitly tells when to use (for regulation text) and when not to (for EPA data, pointing to alternative tools). Also clarifies input flexibility and that passing a whole part returns a section list, leaving no ambiguity about appropriate usage.

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

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

Annotations already indicate read-only and idempotent. Description adds return format details (citation, heading, excerpt, source URL) and notes 'Keyless', providing useful context beyond annotations.

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

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

Well-structured with front-loaded purpose, use cases, and examples. Slightly verbose but each sentence adds value.

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

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

Given no output schema, description thoroughly covers return fields, domain (40 CFR), and keyless access. Includes examples and differentiates from data retrieval tools.

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 (100% coverage). Description adds examples and context but does not significantly enhance meaning beyond schema.

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

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

Description clearly states verb ('search'), resource ('EPA regulations'), and scope ('40 CFR'). Provides specific examples and distinguishes from sibling tools (epa-echo/epa-emissions).

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

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

Explicitly states when to use ('what EPA regulations cover X') and when not to ('for EPA DATA use...'). Lists relevant topics and provides alternative tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' aligns but adds no new behavioral context beyond 'clear sensitive data,' which is more about usage context than behavior. 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, front-loaded with action and purpose. No wasted words. Very concise and structured.

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

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

For a simple destructive tool with one well-documented parameter and clear annotations, the description is fully adequate. No output schema needed.

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

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

Schema covers 100% of parameters with 'key' described as 'Memory key to delete.' Description only says 'by key,' adding no extra meaning beyond the schema. Baseline 3 for high coverage.

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

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

Description clearly states 'Delete a previously stored memory by key.' It identifies the verb (delete), resource (memory), and the identifier (key). It distinguishes from siblings 'remember' and 'recall' by mentioning them.

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' No explicit when-not-to-use or alternatives, but the context is clear and helpful.

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

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

Annotations already provide safety and idempotence hints. The description adds valuable workflow details (fetch, extract, emit) and output format, which are not evident from annotations alone. No contradiction.

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

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

The description is front-loaded with the core action, followed by a brief workflow and bullet-pointed use cases. Every sentence contributes meaning, with no 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 the simple tool (2 params, safe, no output schema), the description covers purpose, workflow, output format, and use cases fully. It compensates for lack of output schema by describing the output as a text blob.

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 both parameters already described. The description adds no new semantic information beyond reinforcing the URL parameter, so score is at baseline for high coverage.

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

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

The description uses a clear verb 'Generate' and specific resource 'production-ready llms.txt file for any URL', distinguishing it from sibling tools. It also lists concrete use cases, leaving no ambiguity about the tool's 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 provides clear use cases such as indexing a client's site or auditing a competitor, but does not explicitly state when not to use or compare to alternatives. The context is clear but lacks 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?

Annotations already provide safety and idempotence cues. Description adds return field details and usage context. No contradictions.

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

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

Two sentences: first states purpose and return, second gives usage guidance. No fluff, 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?

Sufficient for a simple list tool with one optional param. Return fields are enumerated. No missing critical context.

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

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

Schema covers 100% of parameters, so description adds minimal value. The mention of 'active' aligns with default false for include_inactive.

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

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

Description clearly states verb (list), resource (subscriptions), scope (caller's active), and lists returned fields. It distinguishes from sibling tools like subscribe/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?

Explicitly states when to use: to review monitoring before adding more or to find an id to cancel. Implicitly contrasts with subscribe/unsubscribe.

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

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

The description goes far beyond annotations, disclosing rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token flow ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'). It also explains the team's review process ('reads digests daily and signal directly affects roadmap'). 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 a single well-organized paragraph that front-loads the core purpose, then flows through usage conditions, exclusions, message guidance, token mechanics, and rate limits. Every sentence adds necessary information with no filler or repetition, making it dense but efficient.

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

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

Given the tool has 4 parameters, zero required, no output schema, and non-trivial behaviors, the description covers all critical aspects: return values (claim_token and status), rate limiting, scope restrictions, and message formatting. It leaves no major functional gap for an agent to make a correct call.

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 covers all parameters, the description enriches them with usage context: it advises 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and gives a concrete syntax example for claim_token usage. It also clarifies how the 'type' field maps to real scenarios, which is more than the schema's enum definitions alone.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which immediately identifies the verb and resource. It clearly differentiates from siblings like ask_pipeworx or discover_tools by focusing on feedback submission, not information retrieval or tool discovery.

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

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

Explicit when-to-use guidance is given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides clear exclusions: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead,' and suggests an alternative action for uncertain cases.

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), description provides caching details (5min-1h), data source (CF analytics-engine), and no PII. 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?

Four sentences, each earning its place: main purpose, three use cases, technical details. No fluff.

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

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

Single parameter, no output schema, but description fully covers usage, behavioral details, and parameter semantics. Complete 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 has 100% coverage with enum for window. Description adds practical advice: shorter windows surface what's hot, longer show steady-state demand.

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

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

Clearly states it returns top tools, packs, and total call volume over a window. Verb 'Returns' and specific resources differentiate it from siblings like '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 lists three use cases (hot sources, canonical choice, alignment). No exclusion criteria or direct alternatives mentioned, but context is clear.

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

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

Annotations declare readOnlyHint=true and non-destructive; description reinforces this and adds details: scans top ~200 markets, uses Jaccard similarity, filters placeholders, and includes fill check logic. No contradictions.

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

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

Description is fairly long but well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though some compression could be possible. Still, it remains clear and organized.

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

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

With no output schema, the description fully explains the response structure: opportunities[] fields, partition_check fields, and fill check details. It covers edge cases and practical usage, making it complete for agent decision-making.

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

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

Schema descriptions for both event and topic are clear, but description adds significant context: provides examples of slugs and seed questions, explains when to use each, and describes their effects in detail. Schema coverage is 100%, and description further enriches 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?

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes between modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Recommends event mode and warns against trading when fill check shows realizable_edge_pp ≤ 0. Mentions alternative polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond the annotations: details model families, edge calculation (edge_pp_net, Kelly fractions), 24h-move warning, caching at KV level, and why Fed bets are unreliable. Annotations are limited to readOnly, openWorld, idempotent, non-destructive — the description provides rich 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 dense but well-structured with clear segmentation (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and parenthetical clarifications. While lengthy for an agent, the detail is justified given the complexity of the models and parameters.

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 is provided, but the description fully explains the response structure (by_segment, fed_candidates, diagnostics) and how to interpret results. It covers edge cases like empty segments and caching, making it complete for agent use.

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

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

Schema coverage is 100% with good descriptions. The description adds practical usage guidance (e.g., on slippage_pp: 'Bump for very thin partitions; drop to 0 if you have a smarter fill model') and explains the role of min_partition_leg_kelly for partition arbs, adding value beyond the schema.

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

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

The description explicitly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It clearly distinguishes from siblings by its focus on edge discovery from multiple model families, contrasting with tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explains the 'tradeable-edge knobs' (min_liquidity, max_spread_pp) and how to use diagnostics when segments are empty. It also explains caching and the exclusion of Fed bets. However, it does not explicitly contrast with sibling tools or state when not 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds rich behavioral context: it explains the data source (daily snapshots), limits (60-day TTL, snapshot gaps mean no scan), that decay numbers are from daily closes not intraday, and the meaning of missing snapshot dates. This significantly adds value beyond annotations.

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

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

The description is long but front-loaded with purpose and response structure. Every sentence adds necessary information, especially since there is no output schema. Could be slightly tighter but appropriate for the complexity.

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

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

Given no output schema, the description comprehensively details the response: tracked[] with first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[]. It also explains limits and interpretation of gaps. Complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: 'lookback' and 'snapshot family' terms, defaults, and a max of 30 (schema says clamp 2-30, minor omission of lower bound). This enhances understanding.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools by noting it analyzes persistence over time, unlike raw snapshot tools like polymarket_edges.

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

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

The description explains when to use the tool with the example that a fresh wide edge differs from a 3-week-old one. It provides context for interpreting results but does not explicitly state when not to use or give alternative tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral detail: walking the ladder, returning verdicts (clean|degraded|cannot_fill), basket risks, forced directional risk, and the dominant loss mode. 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 well-structured paragraphs: first sentence states purpose, then separate sections for single-market and basket modes. Every sentence adds essential information; 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?

Although no output schema, description enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs) and covers input conditions, risks, and defaults. Fully adequate for effective tool invocation.

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

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

Schema coverage is 100%, but description adds value beyond schema: explains size_usd as settlement notional for basket, side auto-detection, clamp range (10–1,000,000), and per-leg fill details. Baseline 3, plus 1 for extra context.

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

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

Clearly states verb-phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises using this tool before acting on arbitrage or edge signals above ~$500, explains why (partial fills convert arb to directional risk), and specifies required modes (market or event) with defaults.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations: it discloses pairing verification limits, compatibility codes, skipped-unclassified behavior, non-equivalent bet shapes, temporal alignment semantics, and the fact that spreads are gross of Kalshi fees. This is exemplary behavioral disclosure for a data tool. 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 well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. While some redundancy exists, nearly every sentence carries safety-relevant detail that would be hard to omit for a tool with this many caveats.

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

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

With no output schema, the description fully carries the burden of explaining return values and edge cases: it covers top_spreads_pp, compatibility_warning/codes, flags, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, skipped counters, and the fees_note. For a tool this complex, the description is remarkably complete.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful mode-level framing: the topic parameter auto-fetches matched venues, the two explicit parameters create custom pairings, and both modes use the same matcher. It does not fully clarify whether a single explicit override can be mixed with a topic, but the added context is valuable.

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

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

The description clearly states that the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, and it details the two modes of operation. It does not explicitly distinguish itself from closely related sibling tools such as polymarket_arbitrage, so it stops short of full sibling differentiation.

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

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

The description provides clear context for choosing the topic mode versus the explicit kalshi_event_ticker + polymarket_event_slug mode, and it warns that pre-mapped topics are not automatically tradeable. It does not explicitly say when to prefer this tool over sibling alternatives, but the mode guidance is strong.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context on how the retrieval works (omit key to list all keys, scoping to identifier, and pairing with remember/forget). No contradictions.

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

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

Three sentences that front-load the action, follow with use cases and alternatives, and end with scoping. Every sentence adds value; no fluff.

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

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

Given a single parameter, high schema coverage, and clear annotations, the description covers purpose, usage, and behavior. It lacks return format details, but without an output schema, this is acceptable. It could mention pagination or limits for listing many keys.

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

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

Schema coverage is 100% with a clear parameter description. The description reinforces that omitting the key lists all keys, which is already in the schema. It adds minimal new meaning beyond the schema.

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

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

The description clearly states the verb (retrieve/list), resource (saved memories), and distinguishes from sibling tools (remember, forget). It provides concrete use cases (target ticker, address, notes) and explicitly contrasts with the alternative of re-deriving context.

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

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

The description explicitly says when to use the tool (look up stored context) and mentions sibling tools for complementary actions (save, delete). It also notes scoping to the agent's identifier, but does not explicitly state when not to use it, which would elevate the score to 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: explains state change with mark_read, polling suitability, and feed persistence. No contradictions with annotations.

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

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

Three concise, front-loaded sentences. Each sentence adds distinct value: purpose, return fields, filtering, state management, polling advice, and alternative access. No redundancy or fluff.

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

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

Describes return fields and filtering, but lacks explicit ordering (though 'most recent' implies recency). No output schema, but description covers key behavioral aspects. Slight gap in pagination or sorting, but adequate 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 covers 100% of parameters with descriptions. Description adds examples (e.g., 'sec_8k' for type, ISO timestamps) and explains the effect of mark_read, going beyond the schema's basic descriptions.

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

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

Clearly states it pulls fired events from the subscription feed, specifies returned fields (source, citation_uri, payload), and distinguishes from sibling tools like list_subscriptions and subscribe. The mention of an alternative endpoint for scripts/dashboards further clarifies its use case.

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

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

Provides explicit filtering options (type, since) and state management (mark_read). Mentions polling works and gives an alternative REST endpoint, indicating when to use the tool vs. other methods. Lacks explicit when-not-to-use, but the context is clear enough.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds significant context: it fans out to multiple sources (SEC EDGAR, GDELT/GNews with fallback, USPTO), explains rate-limiting behavior, and notes API sunset. 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 slightly long but well-structured. It starts with example queries, then explains behavior, parameter details, and ends with sibling comparison. Every sentence adds value; length is justified given 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 tool has 3 required params and no output schema, but the description explains return fields (changes[], total_changes count, citation URIs) and covers behavior across sources, fallbacks, and limitations. It provides a complete picture for agent usage.

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

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

Schema coverage is 100%, baseline 3. The description adds substantial meaning: explains `since` accepts ISO or relative shorthand with examples and suggests typical usage ('30d'). It clarifies `type` is limited to 'company' and `value` accepts ticker or zero-padded CIK.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call' with example queries like 'What's new with X'. It explicitly distinguishes itself from the sibling tool entity_profile.

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

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

The description gives explicit when-to-use guidance with natural language examples (e.g., 'latest on Y', 'updates on Acme') and explicitly directs users to entity_profile for static profiles. It also explains fallback behavior and soft-fail conditions.

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

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

The description adds behavioral context beyond the annotations, such as scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. However, it does not disclose potential limits like storage quotas or rate limits, which could be relevant.

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 concise at four sentences, with the purpose stated upfront. It could be slightly more condensed, but it avoids unnecessary detail. Every sentence adds value.

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

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

Given the tool's simplicity, the description adequately covers key aspects: purpose, usage, scoping, and persistence. However, it does not describe the return value or error handling, which would be helpful for an agent to interpret results.

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

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

The input schema has 100% coverage with descriptions for both parameters. The tool description does not add significant new semantic information beyond the schema's examples, 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 purpose: 'Save data the agent will need to reuse later.' It specifies the verb 'save' and the resource 'data,' with examples of use cases. It also distinguishes itself from siblings by mentioning 'recall' and 'forget' as complementary tools.

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

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

The description explicitly tells when to use the tool ('when you discover something worth carrying forward') and provides concrete examples. It also gives guidance on alternatives by stating 'Pair with recall to retrieve later, forget to delete,' which helps the agent choose between related tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial context beyond these: graceful degradation of LEI/FIGI enrichment, behavior on ambiguous name matches (asserts nothing, returns candidates), explicit listing of unresolved identifiers, and the ISIN-to-LEI mapping for non-US issuers. This is rich behavioral disclosure that exceeds the annotation baseline.

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 necessary context. It front-loads with usage examples and then structures the supported types and key behaviors. Every sentence contributes; there is no filler. The length is justified by the tool's complexity and the need to explain enrichment and edge cases. Slight deduction for not being shorter, but it's well-organized.

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

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

For a tool of this complexity (multiple entity types, multiple identifier sources, enrichment, fallback, ambiguous cases), the description covers all essential aspects. It explains what inputs are accepted, how each type resolves, what happens when resolution is incomplete, and even mentions the replacement of manual lookups. No critical missing information for 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful parameter guidance: for 'value' it clarifies accepted formats (ticker, CIK, ISIN for company; brand/generic for drug) and provides a critical warning about passing only the entity name for bonds, not the full noun phrase. This goes well beyond the schema's terse description.

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

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

The description states a concrete purpose: resolve a spoken name to canonical identifiers required by other tools. It lists specific example queries and supported entity types (company, drug), and explicitly differentiates from siblings by framing it as the lookup tool that feeds other tools. This is a specific verb+resource with clear 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 given: 'Use FIRST whenever you have a name but need an ID.' This establishes a clear triggering condition. It does not name alternative tools or provide exclusions, but the instruction is unambiguous and context-rich, noting that it replaces 2-3 manual lookups. Slight deduction for not explicitly contrasting with sibling tools like entity_profile.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, which is consistent with the description. The description adds behavioral context: it internally calls ai_visibility_check for each entity, treats the first entity as the subject, and returns a ranked list with score, confidence, and signal density. No contradictions.

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

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

The description is three sentences, each serving a clear role: purpose, mechanism, and use case/output. No filler words or redundancy. It is front-loaded with the main action and remains highly readable.

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

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

Given the tool's moderate complexity (4 params, no output schema, but strong annotations), the description explains the output format (ranked list with score, confidence, signal density) and the special treatment of the first entity. It lacks details on error handling or limits but is sufficient for typical usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema for the 'entities' parameter by specifying that the first entry is treated as the 'subject' for narrative. This semantic nuance helps agents correctly structure the input. Other parameters are briefly mentioned but not elaborated; still, the addition justifies a 4.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and actions (probes, ranks, surfaces). It differentiates from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison), making its unique value evident.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with an example question. It implies that for a single entity, one should use ai_visibility_check (since this tool probes multiple). However, it does not explicitly state when not to use this tool or list alternatives, which would have earned 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 read-only and idempotent behavior. The description adds critical behavioral details: composite fan-out to two services, graceful partial degradation, potential 5-30s delay on first bundlephobia measurement, and the sources_failed field. No contradictions.

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

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

The description is detailed but well-structured: purpose first, then return format and edge cases. Every sentence adds utility; however, minor trimming could improve conciseness without losing 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?

Despite no output schema, the description fully explains return values (summary block with fields, advisories, links, alternative versions) and error handling. Given the tool's moderate complexity, this provides complete contextual information for agent invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enhances understanding by noting scoped package syntax acceptance (@types/node) and version defaulting to latest. This adds value beyond the schema.

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

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

The description explicitly states the tool's purpose: a composite check for adding npm packages, covering license, advisories, version history, and bundle size analysis. It distinguishes from siblings by specifying NPM ecosystem only and referencing deps.dev directly for other ecosystems.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes exclusion of other ecosystems and directs to deps.dev:version directly for PyPI, Maven, etc., making sibling differentiation 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, openWorld, idempotent, non-destructive properties. The description adds significant behavioral details: embeddings model (BGE-base-en), windowing (500-char overlapping), cap (200K chars with truncation flag), and return format (offsets, similarity scores). 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 well-structured paragraphs: first explains purpose and usage, second provides technical details. Every sentence adds value, no fluff. Front-loaded with the core action.

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

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

Despite no output schema, the description describes return elements (passages, character offsets, similarity scores). Covers limitations (200K chars, truncation). Pairs with sibling tool. No gaps given the complexity.

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

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

Schema coverage is 100%, but the description adds context beyond definitions: explains that 'text' should be already fetched, gives examples for 'query', and clarifies default and range for 'limit'. Provides behavioral context like truncation.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verbs like 'search' and 'returns'. It distinguishes from siblings like ask_pipeworx_grounded by explaining the pairing. References to SEC 10-K and articles make the purpose concrete.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Provides context on saving context and returning only relevant passages. Mentions pairing with ask_pipeworx_grounded, guiding the AI on alternatives.

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

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

Annotations already indicate mutation (readOnlyHint false) and idempotency (idempotentHint true). The description adds substantial behavioral context: authentication requirements, supported event types with example parameters, delivery channel mechanics (email validation, SMS verification with rate cap, webhook HMAC signing and auto-disable on failures), which goes well 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 well-structured, front-loading the core purpose and then providing details on requirements, types, and delivery. At ~150 words, it is appropriately sized for the tool's complexity, with no wasted sentences. A slightly more concise treatment of delivery options could bump it to 5.

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 complex tool with multiple subscription types and delivery options, the description covers most behavioral aspects thoroughly. However, it omits details about the return value structure (beyond 'new subscription id') and does not mention error scenarios or rate limits beyond the SMS cap. The absence of an output schema makes this omission noticeable.

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

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

The input schema covers all 3 parameters with 100% coverage, but the description greatly enriches each parameter: 'type' gets context for each enum value (e.g., 'sec_8k: 8-K filings matching ticker + item codes'), 'params' gets type-specific examples and rules, and 'delivery' gets detailed behavioral descriptions including verification requirements and webhook signing. This adds significant value beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id,' with a specific verb (create) and resource (subscription). This distinguishes it from sibling tools like list_subscriptions (list) and unsubscribe (delete).

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 requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions, providing a clear prerequisite. While it does not explicitly contrast with alternatives, the purpose itself implies when to use this tool (to create a subscription) versus listing or deleting existing ones via siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: that the tool returns example questions drawn from a live catalog of thousands of tools, and that it can be called with or without a topic parameter. 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 well-structured with a list of acceptable variations at the start, followed by a clear explanation of output and usage. It is somewhat long but every sentence adds value; could be slightly more condensed by removing the full category list, but the list is informative.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description provides complete context: what the tool does, when to use it, what input to provide, and what output to expect. It also mentions meta-tools, fully covering the onboarding use case.

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

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

Schema coverage is 100% for the single 'topic' parameter. The description adds meaning by listing example values (finance, pharma, etc.) and clarifying that omitting the topic returns a cross-category spread, while providing one focuses on a specific area. This adds functional understanding beyond the schema.

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

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

The description clearly states that this tool is the onboarding entry point for an agent to learn what questions to ask Pipeworx. It specifies the output (category-bucketed example questions with exact tool+argument shape) and distinguishes itself from sibling tools like ask_pipeworx and entity_profile by its role as a discoverability aid.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains when to call with no arguments vs. with a specific topic, providing clear context for when to use this tool 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?

The description discloses that the row is deactivated (not deleted) and historical events remain available, adding crucial behavioral context beyond the annotations. 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?

Two sentences that are efficient and front-loaded: the first covers action and constraint, the second explains the behavioral effect. No unnecessary words.

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

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

With one parameter, no output schema, and comprehensive annotations, the description fully covers what the agent needs: ownership enforcement, soft-delete behavior, and parameter usage. No gaps.

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

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

The schema has 100% coverage, and the description adds meaning by stating that the id is a 'Subscription id (uuid) returned by subscribe', which helps the agent understand the parameter's origin.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'), which distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description specifies ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use the tool. It does not explicitly mention alternatives, but the constraint is clear.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive, and the description adds rich behavioral context: the two routing paths, return format (verdict list, citation, reasoning), and crucial semantics for could_not_verify vs unsupported, including verification_error details. This goes well beyond the annotations and prevents misinterpretation.

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

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

The description is long but front-loaded with trigger phrases and structured logically: usage, routing, return values, then warnings. It is dense with necessary information for a complex verify tool; the 'Replaces 4–6 sequential calls' note adds efficiency context. Some minor redundancy exists (e.g., restating verdict types), but overall it earns its length.

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

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

For a tool with 2 params, no output schema, and strong annotations, the description fully covers: purpose, routing logic, output format, verdict definitions, error semantics, and the benefit over sequential calls. Nothing critical is missing for an agent to safely and effectively 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?

Schema coverage is 100% for both parameters, providing solid baselines. The description adds extra meaning beyond schema by explaining tolerance_pct overrides the implied tolerance and its default cap, and shows examples for claim. This is a small but meaningful increment over the schema.

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

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

Description clearly identifies the tool as a natural-language claim verification tool with a specific verb ('check'), resource ('factual claims'), and scope ('against authoritative sources'). It includes multiple trigger phrases and distinguishes from siblings by describing the company-financial fast path vs. grounded pipeline, making it unmistakable when to invoke.

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 'Use whenever the agent needs to check whether something a user said is factually correct' sets a clear condition. It also implies exclusions by contrasting with the grounded pipeline and noting it replaces 4–6 sequential calls, though it doesn't explicitly mention alternative tools or when NOT to use it.

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