Politics Feeds

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

Annotations already declare readOnlyHint and idempotentHint. The description adds critical behavioral context: the financial implication of using Anthropic (BYO key, pay directly), the return shape (per-model fields + combined view), and the default free model. No contradictions with annotations.

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

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

Three sentences, each dense with information. The description is well-structured: opening with the core action, explaining key parameters, and ending with use cases. No redundant phrases.

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 (multiple models, scoring), the description covers the return structure (per-model + combined) and usage contexts. No output schema exists, but the description compensates adequately. Slightly more detail on scoring methodology (0-100 scale interpretation) would elevate to 5.

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 enhances understanding by explaining the default model for 'models', the role of '_apiKey' as payment shim, and 'context' as disambiguation aid. This adds meaningful guidance beyond the schema alone.

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

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

The description uses specific action verbs ('Probe', 'score') and clearly identifies the resource (LLMs' knowledge about an entity). It does not simply restate the name; it explains the purpose and distinguishes from potential siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring across models.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). It also implies when not to use (e.g., if no Anthropic key, default model works). However, it does not directly contrast with sibling tools like 'compare_entities' or 'deep_research', leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds valuable behavioral context: it returns stable pipeworx:// citation URIs, routes dynamically across 5,801 tools, is fast and works on all tiers, and handles news/breaking news via built-in feeds. No contradictions with annotations; it enriches beyond them.

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

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

The description is long but well-structured: it opens with the critical preference instruction, then explains routing, usage triggers, examples, and alternative selection, closing with news handling. It front-loads the most actionable guidance and each section earns its place. Slightly verbose, but not redundant or padded.

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 routing tool with no output schema, the description is fully self-sufficient: it explains purpose, when to use, examples, citation output, and how it differs from alternatives. Given the rich annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%: all six parameters are aliases for the natural-language 'question', and the schema already describes that. The description reinforces that the input is a natural-language question and gives examples, but adds no new semantics beyond what the schema states. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description clearly states the tool answers factual questions about real-world entities, events, and numbers, routing to thousands of verified sources and returning structured answers with citations. It explicitly distinguishes itself from web search and names sibling tools (ask_pipeworx_grounded, deep_research) that serve different use cases, so an agent can tell them apart without opening schemas.

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

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

It gives explicit 'PREFER OVER WEB SEARCH' guidance, lists trigger phrases ('what is', 'look up', 'find', etc.), provides concrete examples, and clearly states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for multi-part fan-out). It also notes it works on every tier and is the default entry point. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it is currently identical to ask_pipeworx because no candidate is active, results are compared against the stable router for merges, and it does not fall back to anything. This fully discloses the experimental nature and current 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 informative and front-loaded with the key point (beta, identical router). It has a few redundant phrases, such as repeating 'same 5,801 tools, same arguments, same response shape' after calling it an 'identical universal router,' but overall it is concise and well-organized. It earns a 4 for being slightly wordy yet still efficient.

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

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

Given the tool's simplicity (one question parameter with aliases) and the presence of annotations covering safety, the description is mostly complete. It explains the experimental status, current equivalence to ask_pipeworx, and that it's a full router. The only gap is the absence of an explicit response shape, but since it says 'same response shape' and the stable ask_pipeworx is a sibling, an agent can infer it. A 4 is appropriate.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for the 'question' field. The description adds no additional parameter details, but since the schema fully covers semantics, the baseline of 3 is appropriate. The description's mention of 'same arguments' reinforces that the parameters match ask_pipeworx but doesn't add new meaning.

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

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

The description explicitly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes from the stable sibling by emphasizing the experimental routing improvements, giving the agent a clear understanding of what this tool does and how it differs.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (ask_pipeworx) and the condition for selection, and clarifies that it is a full working router, not a fallback. This leaves no ambiguity about when to invoke it.

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

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

Discloses refusal behavior with specific refusal_reason values, confirms it extracts only from tool results, and is fully consistent with readOnlyHint, openWorldHint, and idempotentHint 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 reasonably concise but repeats the routing explanation ('picks the right tool from 5,801...') and the return shape twice. Still, every sentence adds meaningful guidance.

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

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

Includes enough context for an agent to decide when to use it, what to expect on success/failure, the cost trade-off, and the relationship to the sibling ask_pipeworx 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?

All six parameters are aliases for the same question input, each is described, and the canonical 'question' parameter is clearly explained. Schema coverage is 100%.

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 is a hallucination-resistant answer mode for high-stakes reads, names the specific resource (Pipeworx tools), and distinguishes itself from ask_pipeworx by grounding answers exclusively in tool results.

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

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

Explicitly says when to use it (quoted, cited, or acted-on answers; financial, legal, medical, public statements) and when not to (casual lookups, prefer ask_pipeworx). Also notes the extra LLM call cost.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: resolution process, classifier fan-out, response shapes (market, analysis, evidence), resolver contract (match confidence, alternatives), parent event extractor, news fallback mechanisms, safety short-circuits, wide-spread warnings, and cancellation rule parsing. This far exceeds what annotations provide.

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

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

The description is long (multiple paragraphs) but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads purpose and usage. Every sentence adds necessary detail for a complex tool. While length is justified, it could be slightly more concise without losing critical information.

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

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

Given the tool's complexity (multiple data sources, edge cases, safety checks) and the absence of an output schema, the description is remarkably complete. It covers all aspects: input formats, behavior, response structure, resolver contracts, parent events, news fields, safety conditions (low-confidence, closed markets, wide spread), and cancellation rules. No gaps are evident.

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 3 parameters with 100% description coverage. The description enriches each parameter: market can be slug, URL, or question text; depth explains quick vs thorough with source counts; include_raw explains summarized vs raw payloads. This adds significant meaning beyond the schema alone.

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

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

The description clearly states that the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and explicitly lists usage scenarios ("should I bet on X", "what does the data say about Y", "is there edge in Z"). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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

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

The description provides explicit usage scenarios ("Use for ...") and detailed examples of classifiers and fan-out. It does not explicitly state when not to use the tool or directly name alternatives, but it does describe blocking conditions (low-confidence, closed markets) that effectively guide the agent. The context is clear, though exclusions are implied rather than explicit.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral details: results sorted by primary metric, data sources (SEC EDGAR, FAERS), and citation URI format. 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 moderately concise but front-loaded with query patterns. Every sentence adds value, though it could be slightly more streamlined. No redundant phrasing.

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 2 parameters, rich annotations, and no output schema, the description adequately covers return format (paired data + citation URIs) and behavior. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the 'type' enum values, providing examples for 'values' (tickers vs. drug names), and clarifying constraints (2-5 items).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 entities (companies or drugs) in one parallel call. It provides example queries and distinguishes itself from sequential single-pack lookups, making the purpose unambiguous.

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

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

Explicitly recommends preferring this tool over sequential lookups for comparisons. However, it lacks guidance on when not to use it (e.g., for more than 5 entities or different data needs).

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 auth/payment requirements ('ACCOUNT REQUIRED... thorough needs a paid plan'), output shape (findings packet with confidence, source, fetched_at, contradictions, gaps), citation resolvability rules, and performance expectations ('15-60s... up to ~90s'). It also transparently notes when citations are present and that gaps are 'never invented'. No contradiction with the readOnly/openWorld/idempotent 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 dense, repetitive wall of text with all-caps emphasis and repeated refrains like 'ask_pipeworx', '1517 STRUCTURED data sources', and 'IN PARALLEL'. It front-loads the account/payment note, but the excessive length and redundant phrasing obscure the core message and make it harder to scan.

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

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

The description is highly complete for the tool's complexity: it covers when to use, when not to use, depth semantics, output contents, contradictions and gaps behavior, citation resolution, excerpting behavior, and performance expectations. It also situates the tool relative to ask_pipeworx and other siblings, so an agent has enough context to call it correctly.

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

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

The schema already fully describes both parameters: 'question' with natural-language guidance and 'depth' with enum semantics including the paid thorough tier. The description adds no significant new parameter meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in 'ONE call', decomposing questions into facets and returning findings. It also explicitly distinguishes itself from ask_pipeworx, making the separation from sibling tools obvious.

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 strong usage guidance: 'Best for broad/multi-part questions over structured data', and explicitly directs users away for 'single lookup' and 'BREAKING or colloquial CURRENT-NEWS' topics toward ask_pipeworx. It also explains depth-level behavior differences, so an agent knows when quick/standard/thorough 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 valuable context: returns top-N relevant tools with curated examples, each result ready to call directly, 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?

Efficient 4-5 sentences with front-loaded purpose, clear usage guidelines, and no redundant information. Every sentence adds value.

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

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

Given the tool's discovery nature, 6 parameters fully documented in schema, and no output schema needed as description explains return format, the description is complete and self-sufficient.

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

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

Schema coverage is 100%, so the description doesn't need to re-document each parameter. However, it adds value by explaining that the query accepts natural language and providing example queries. A slight bonus above baseline 3.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of use cases (SEC filings, FDA drugs, etc.) and distinguishes itself by emphasizing it should be called first to discover available tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and lists domains. Also instructs 'Call this FIRST when you have many tools available and want to see the option set', giving clear when-to-use guidance.

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

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

Annotations already carry readOnly/openWorld/idempotent hints, yet the description adds substantial behavior beyond that: parallel fan-out architecture, USPTO PatentsView 'soft-fails until reactivated,' GDELT→GNews fallback chain, 'an empty section is a real no-data, not a bug,' resolved:false with notes for private companies, and resolved_from/resolved_to traceability when a name is resolved. No contradiction with any annotation.

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

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

The description is long, but every clause earns its place given the 8-source complexity — the opening query examples front-load intent, and the semicolon-delimited return enumeration packs per-source semantics into single clauses. The returns list is slightly run-on, and there are minor transcription artifacts, but there is zero fluff or repetition of schema content.

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

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

With no output schema, the description carries the full burden of explaining return values and largely delivers: core fields (cik, company_name, resolved_from/to), recent_filings (up to 5 with pipeworx URIs), fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash), and per-source descriptors for patents, contracts, FDA products, and hiring. Minor gaps: LEI and news return shapes are only named, not structured.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds concrete value beyond schema: worked examples ('AAPL', '0000320193', 'Modena'), the zero-padding requirement for CIKs, explicit interchangeability of the type enum values, and edge-case semantics for private companies (no CIK/ticker). It reinforces and enriches the schema rather than just repeating it.

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

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

States a specific verb+resource — 'full cross-source profile of a US public company in ONE parallel call' — and enumerates the eight data sources it fans out to (SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, news, GLEIF). This unmistakably differentiates it from siblings like resolve_entity or compare_entities, and the leading example queries ('brief me on Tesla', 'company profile for Microsoft') give an agent immediate pattern-matching hooks.

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

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

Gives an explicit decision rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies valid input forms (ticker, zero-padded CIK, company name) and the private-company fallback (resolved:false). It does not name exclusions for adjacent siblings like deep_research or compare_entities, but the primary alternative (chaining single lookups) is clearly addressed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, indicating a safe, non-destructive operation. The description adds valuable context like 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway', disclosing fallback behavior beyond annotations.

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

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

Two sentences that efficiently convey purpose and usage guidance. No unnecessary words, and the key information is front-loaded.

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

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

For a simple fetch tool with 3 parameters and no output schema, the description covers purpose, usage guidance, and a key behavioral trait (fallback). It sufficiently differentiates from siblings in a list of 30+ tools. Could mention that it returns normalized feed items, but still complete enough.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters well. The description does not add new semantic information about parameters beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states it fetches and normalizes any RSS/Atom/RDF feed by URL. It distinguishes from the sibling 'list_feeds' by suggesting to use that for curated sources, making the purpose distinct.

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 to use 'list_feeds' first for curated sources, providing a clear when-not-to-use scenario and suggesting an alternative tool. This helps an AI agent decide which tool to invoke.

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. Description adds usage context but no additional behavioral traits beyond deletion.

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 action, 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?

Complete for a simple single-parameter delete tool. Covers purpose, usage, parameter meaning, and pairing.

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 100% with 'key' description. Description only says 'by key', no added value over 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?

Specific verb 'delete' with resource 'memory' by key. Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicit use cases: stale context, task done, clear sensitive data. Mentions pairing with remember and recall as alternatives.

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

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

Annotations already indicate safe, read-only, idempotent, non-destructive behavior. The description adds details: fetches page, extracts title/description/key links, emits markdown. No contradictions, and it complements annotations well.

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

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

The description is four sentences, front-loaded with action and purpose, followed by process, output, and use cases. 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 no output schema, the description explains the output as a single text blob. All aspects are covered: purpose, process, output, and use cases. Annotations cover safety. The definition is complete for an agent to use correctly.

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

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

Schema coverage is 100%, and the description adds meaningful context beyond the schema: url is described as 'Full URL of the site to summarize', max_links includes default and max values. No parameter information is missing.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, explains the purpose (helping AI crawlers index the site), and the output format. It distinguishes itself from siblings by focusing on a specific action not covered by others like scan_competitor_ai_presence.

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

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

The description provides explicit use cases (getting client's site indexed, drafting for own project, auditing competitor visibility). It lacks explicit when-not-to-use or alternatives, but the scenarios are clear enough for an agent to determine applicability.

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, and non-destructive. The description adds that feeds are curated and politics-focused, and suggests a sibling tool. 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 that front-load purpose, then filtering options, then sibling usage. No wasted words.

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

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

Despite no output schema, the description specifies returned fields (id, title, category, source) and covers filtering and relationship to read_feed. Complete for a list 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%, but the description adds that category filter is for 'politics' and keyword matches title/source/description, providing extra context beyond the schema.

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

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

The description clearly states the tool lists curated politics & policy feeds with specific fields, optional filtering by category or keyword, and hints at using the id with read_feed. This distinguishes it from siblings like read_feed.

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 tells when to use this tool (to list feeds) and when to use read_feed (by passing an id). It doesn't explicitly state when not to use it, but the context is clear.

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

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

Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description clarifies the scope ('caller's') and lists the return fields, adding value about what the caller can expect.

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

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

Two sentences, front-loaded with the core purpose, no wasted words. Every sentence provides essential information.

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

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

The tool is simple (single optional param, no output schema), and the description covers the key aspects. It could mention pagination or limits, but the annotations and schema are sufficiently rich, making the description adequate.

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 parameter 'include_inactive' already has a description. The tool description does not add additional meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the action ('List') and the resource ('the caller's active subscriptions'), and lists the returned fields. It distinguishes this tool from siblings like 'subscribe' and 'unsubscribe' by its listing function.

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

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

Explicitly advises when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for usage, though it doesn't discuss alternatives like searching subscriptions.

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 non-read-only and non-destructive. The description adds valuable behavioral context: filing returns a claim_token, passing it back later reads the status, rate-limited to 5 per identifier per day, free, and doesn't count against quota. It also explains the team reads digests daily. 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 dense but every sentence earns its place. It front-loads the main purpose, then systematically covers usage, exclusions, token mechanics, rate limits, and quota. No fluff, no repetition of schema content.

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

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

Covers purpose, usage, exclusions, claim_token flow, rate limits, and quota. The only minor gap is that since there is no output schema, the description doesn't fully specify the response format beyond mentioning the claim_token. For a tool with 0 required parameters, it could also clarify what happens if called with no arguments, though the read-back use case is implied.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond schema: claim_token should be passed with no other arguments, message should describe issues in terms of Pipeworx tools/packs (not end-user's prompt), and the type enum is mapped to concrete scenarios. This is strong added value.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from siblings by naming the exact use cases (bug, feature/data_gap, praise) and explicitly excluding reports about other MCP servers. This makes it unmistakably the feedback tool for this connection.

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 when' conditions with concrete examples ('tool returns wrong/stale data', 'tool you wish existed isn't in the catalog', 'worked surprisingly well'). It also gives a clear exclusion: if the tool is from a different MCP server, file it there instead. This is outstanding when-to-use guidance.

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

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

Annotations already indicate safe, read-only behavior. Description adds caching details (5min-1h) and data source (CF analytics-engine, no PII), enhancing transparency 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?

Every sentence adds value. Front-loaded with purpose, then use cases, then technical details. 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?

Covers purpose, usage, parameter effects, caching, and data source. Minor gap: output structure (e.g., how 'top' is defined) not detailed, but sufficient given simplicity and annotations.

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

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

Schema coverage 100%, but description adds value by explaining the meaning of each window option: shorter for 'hot right now', longer for '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 what the tool does: returns trending tools, packs, and call volume. Distinguishes from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on aggregate usage trends.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use cases). No negative guidance or alternatives, but context is clear for selection.

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

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

Annotations indicate read-only, open-world, idempotent behavior. The description adds extensive detail: explains monotonicity checks, partition checks (sum ≈1), thresholds (3pp, 20% placeholder, 0.30 Jaccard), fill check with book depth, and response structure. This far exceeds what annotations provide.

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

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

The description is lengthy and dense, containing many technical details and nested rules. While well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), it could be more concise for quick comprehension. Adequate but not optimally succinct.

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

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

Given the complexity of the tool, the description covers all necessary aspects: mode selection, algorithmic details, thresholds, response structure, and safety checks (fill check). It also references sibling tools. No output schema is present, but the description explains the return format sufficiently.

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

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

Schema coverage is 100% with clear descriptions. The description adds examples of slugs and seed questions, explains the internal logic, and recommends event mode. Since schema already covers basics, the description provides valuable extra context, justifying above baseline.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes: no-args trending scan, event-specific, and cross-event topic scan. This specificity differentiates it from sibling tools like polymarket_edges and 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?

The description explicitly advises when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also warns when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing. Lacks explicit 'do not use' scenarios but provides sufficient context.

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

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

The description discloses extensive behavioral traits: how each model family works (e.g., crypto_price using FRED log-returns, news_momentum using GDELT), edge calculation net of slippage, Kelly sizing, diagnostics for empty segments, Fed bets handling, and caching. Annotations already mark readOnlyHint=true, and the description adds nuance without 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 long but well-structured: intro sentence, three model segments, knobs, response structure, diagnostics, caching. Each section is dense with information. While not extremely concise, it is organized and front-loaded with key purpose.

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

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

Given 9 parameters, no output schema, and complex logic (three segments, diagnostics, caching), the description provides comprehensive details: response top-level keys, segment contents, diagnostics counts, and Fed note. It explains what to expect when segments are empty, making it complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the logic behind parameters like min_partition_leg_kelly (why it applies to per-leg inside partitions) and min_kelly (for single-leg). It also frames min_liquidity and max_spread_pp as 'tradeable-edge filters,' adding 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?

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx model-driven, structural arbitrage, and concentrated longshots, not pure arbitrage or tracking.

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 'Built for "what should I bet on today"' and mentions agents discover opportunities without paging hundreds of markets. It also explains caching and knob usage. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides extensive behavioral context beyond the annotations: bounded by 60-day TTL, decay from daily closes not intraday, and explains the meaning of expired and snapshot_dates. Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent and uncontradicted.

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

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

The description is a single paragraph that efficiently conveys key details: purpose, parameter defaults, response structure, and limitations. It is front-loaded with the core question, making it easy to grasp. Could be slightly more structured, but overall concise for the content.

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

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

Despite lacking an output schema, the description fully compensates by detailing the response fields (tracked[], expired[], snapshot_dates[]) and their inner structure. It also covers limitations and provenance, ensuring the agent can interpret results correctly.

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

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

Schema coverage is 100%. The description adds defaults (days default 14, max 30; window default '1wk') and clarifies the window family values (24hr, 1wk, 1mo). This adds practical guidance over 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers how long has this edge existed and is it shrinking?'. It distinguishes from related tools by focusing on historical persistence rather than current edges, and details the response structure (tracked, expired, snapshot_dates).

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

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

The description implies usage for historical edge analysis but does not explicitly state when to use this tool versus alternatives like polymarket_edges. However, the context of sibling tools and the focus on time-series makes the intended use clear.

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

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

The description adds significant context beyond the annotations (readOnly, idempotent, not destructive). It details the return fields, the verdict system (clean|degraded|cannot_fill), and warns about forced directional risk. 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 lengthy but well-structured with clear sections for single-market and basket modes. Every sentence adds value; however, it could be slightly more concise without losing necessary detail.

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

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

Without an output schema, the description thoroughly documents all return fields for both modes, including edge cases like thin legs and forced directional risk. This makes the tool fully understandable for an agent.

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

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

Schema coverage is 100%, but the description adds value by explaining the meaning of size_usd in basket mode (settlement notional) and the default behavior for side. It also clarifies the required parameter constraint (one of market or event).

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it before those 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 directly tells agents to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (partial basket fills convert arb into directional position) and when not needed (implicitly small trades under $500). This is explicit and actionable.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by explaining what results mean, when warnings are emitted, how unmatched legs are handled, and that spreads are gross rather than net of Kalshi fees. It discloses specific compatibility codes, skipped counters, and the limitation that pairing is keyword-based, not resolution-source-confirmed.

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?

Despite being long, the description is densely informative and well-structured: it leads with the core concept, then modes, response shape, safety fields, codes, and caveats. Every section adds necessary operational detail; there is no filler or redundant restating of the name.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does so thoroughly: top_spreads_pp, compatibility_warning, compatibility_codes, temporal_alignment, fees_note, skipped counters, and low_confidence_pairs are all covered. It also addresses real-world ambiguity such as unknown resolution dates and non-equivalent bet shapes.

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

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

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the two operational modes, how the topic values map to auto-fetched events, and how explicit tickers/slugs override the topic-mapped side, making the interaction between parameters clearer.

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

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

The description states a precise function: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It is clearly differentiated from Polymarket-only siblings by the explicit cross-venue framing and the tool name/title reinforce this.

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

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

The description clearly explains two modes: pre-mapped `topic` shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` pairings, with concrete examples. It also gives important usage caveats: pre-mapped topics often return compatibility warnings and pre-mapped does not imply tradeable, which helps an agent decide when to trust results.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return structure details and keyword filtering capability, which are not in 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 with no fluff. Purpose, usage, output, and optional filtering all stated concisely.

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 3 parameters, no output schema, and low complexity, the description fully explains input, output fields, and filtering. No missing information.

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

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

Schema covers all parameters (100% coverage), so baseline 3. Description adds domain context ('politics & policy'), source hint for feed param, and clarifies query scope ('item title/summary').

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 ('Read'), resource ('curated politics & policy feed'), and specifies source ('from list_feeds') and output format ('normalized items with fields'). Distinguishes from sibling tools like 'list_feeds' and 'fetch_feed'.

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?

Description implies prerequisite (feed id from list_feeds) and scope ('politics & policy'). Does not explicitly state when not to use, but context is clear.

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

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 scoping by identifier and behavior when key is omitted. 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, each adds value: action, use case, scoping, and pairing. No redundancy. Efficient and front-loaded.

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

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

For a simple retrieval tool with no output schema, the description covers behavior, scoping, and pairing with siblings. No missing elements.

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. Description adds the nuance that omitting key lists all keys, which is not obvious from schema property description 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 clearly states the tool retrieves values saved via 'remember' or lists all keys when key is omitted. It explicitly distinguishes from siblings 'remember' and 'forget' by mentioning pairing.

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

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

The description advises using recall to look up previously stored context and notes pairing with remember/forget. It doesn't explicitly say when not to use, but the context is clear enough given sibling scope.

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 safe read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral details: returns most recent alerts, each carries specific fields, filter options, mark_read effect, and polling suitability. 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 three sentences, each earning its place: purpose, payload details with filtering, and mark_read/polling guidance. No redundant words, well-structured, and front-loaded with the core action. Ideal conciseness.

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

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

Given no output schema, the description explains return values and filter behavior adequately. It mentions polling and REST endpoint. Minor gaps: the limit parameter maximum (200) is only in the schema, and pagination is not discussed. However, for a simple read tool with 100% schema coverage, this is nearly complete.

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

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

Schema coverage is 100% with concise descriptions for all 5 optional parameters. The description adds value by providing examples (e.g., 'sec_8k' for type), explaining the effect of mark_read ('flag returned events read so the next call only shows newer ones'), and clarifying the since parameter as ISO timestamp. This goes beyond the schema's brief descriptions.

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

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

The description starts with a clear verb-resource pair ('Pull fired events from your subscription feed'), specifies what each event carries (source, citation_uri, payload), and distinguishes the tool by mentioning filtering and mark_read behavior. It implicitly contrasts with siblings by noting the feed is also available via a REST endpoint, making the purpose highly specific.

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 clarifies when to use this tool (for recent alerts, with optional filters and mark_read), states that polling works fine, and mentions an alternative REST endpoint for scripts/dashboards. It does not explicitly list when not to use it or contrast with sibling tools like read_feed, but the context is sufficient for typical use.

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

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

The description details the fan-out behavior to multiple data sources, fallback logic (GDELT preferred, GNews on rate limits or 5xx), and the soft-failure of USPTO PatentsView API after May 2025. This adds significant context beyond the annotations (which only indicate read-only, open-world, idempotent, non-destructive).

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

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

The description is efficiently front-loaded with user-facing examples, then systematically covers parameters, sources, and return structure. Every sentence provides necessary information without redundancy, and it is 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?

Despite the absence of an output schema, the description details the return format: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' All parameters, sources, and fallback behavior are adequately covered.

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 description explains that 'since' accepts ISO dates or relative shorthand, gives examples ('7d', '30d', '3m', '1y'), and recommends '30d' or '1m' for typical monitoring. It also clarifies that 'value' can be a ticker or zero-padded CIK, adding meaning beyond the schema.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific sources (SEC, GDELT/GNews, USPTO) and distinguishes from the sibling tool 'entity_profile' which covers static profiles.

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

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

The description explicitly advises to 'Use entity_profile instead when you want the static profile' and provides a clear alternative usage. It also includes typical monitoring suggestions for the 'since' 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 indicate write, idempotent, non-destructive. Description adds critical behavioral context: key-value storage scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. This goes beyond annotations and aligns with them without 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 purpose, followed by usage and details. It is slightly longer than minimal but every sentence adds value. Could be tightened, but structure is logical and clear.

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

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

For a simple tool with 2 parameters and no output schema, the description provides complete context: purpose, usage triggers, storage mechanics, retention policy, and links to related tools. No gaps remain for the agent to guess.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds no new parameter details beyond schema examples (e.g., 'subject_property'). It provides high-level context but does not significantly enhance parameter understanding.

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

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

The description clearly states the tool saves data for reuse, using verbs like 'save' and 'store'. It distinguishes from siblings by mentioning related tools recall and forget explicitly, and gives examples of use cases (resolved ticker, target address, etc.).

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

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

The description provides explicit guidance on when to use: 'Use when you discover something worth carrying forward'. It also explains pairing with recall and forget, and details persistence behavior for authenticated vs anonymous sessions, helping the agent decide contextually.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral context: cascading lookup endpoints, explicit handling of unresolved identifiers, behavior for ambiguous matches (figi_candidates), and graceful degradation when external sources are unavailable. This far 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 and well-structured with sections (SUPPORTED TYPES, LEI/FIGI enrichment) and front-loaded with purpose and examples. Every sentence adds value, though it could be slightly trimmed without losing critical information. The length is justified by the tool's complexity.

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

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

For a two-parameter tool with no output schema, the description is remarkably complete. It explains return elements (identifiers, unresolved list, figi_candidates), handles edge cases (non-equity instruments, ambiguous names, non-US issuers), and gives precise input instructions. Nothing an agent needs to call it correctly is missing.

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

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

Even though schema coverage is 100%, the description adds considerable extra meaning: for 'value' it gives examples, warns against including trailing security-class words for bonds, and distinguishes between company and drug inputs. For 'type' it explains what each type returns (CIK, ticker, LEI, FIGI vs RxCUI, ingredient, brand). This goes well beyond the minimal 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 states a specific verb ('resolve') and resource ('entity' names to canonical identifiers) with numerous concrete query examples, and explicitly differentiates from siblings by noting it replaces 2-3 manual lookups and should be used 'FIRST whenever you have a name but need an ID.'

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

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

Provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID'), detailed input formatting rules (e.g., for bonds pass exactly the issuer name, not the full noun phrase), supported types, and graceful degradation behavior. It also implies when not to use it (when IDs are already known).

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, openWorldHint, and destructiveHint=false. The description adds valuable context: it probes each entity via ai_visibility_check, ranks by score, and surfaces most/least recognized. No contradictions.

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

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

Two sentences, front-loaded with the primary action. Every sentence adds value—no fluff. Could be slightly more terse, but overall efficient and well-structured.

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

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

No output schema, but the description explains the output format (ranked list with score, confidence, signal density). Parameters are fully described. The tool's role among siblings is clear. Adequate for a read-only, idempotent tool with rich annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by noting that the first entity is treated as the 'subject' for narrative purposes, which is not in the schema. This slightly improves parameter understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities by probing each with ai_visibility_check and ranking results. It distinguishes itself from the sibling ai_visibility_check (single entity) and compare_entities (generic) by specifying the exact verb, resource, and output format.

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

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

Provides explicit use case ('competitive AI-marketing audits') and an illustrative question ('does Claude know about us as well as our competitors?'). Lacks explicit when-not-to-use directives but sufficiently implies the tool is for multi-entity comparisons.

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?

Details beyond annotations: fans out across multiple services, partial failures degrade gracefully, bundlephobia first measurement may take 5-30s. Describes return format (summary block, advisories, links, alternative versions). 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 dense but well-structured, front-loaded with purpose. Slightly verbose but each sentence adds value; could be slightly shortened but overall effective.

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

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

Completely covers return structure (though no output schema), edge cases (scoped packages, default version), partial failures, and timeouts. No gaps for an AI agent to understand behavior.

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

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

Schema description coverage is 100%. The description adds extra context: explains that scoped packages are accepted and that version defaults 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 clearly states the tool's purpose: a composite check for deciding whether to add an npm package, combining data from deps.dev and bundlephobia. It specifies the resource (npm package) and the verb (scan), and distinguishes itself from sibling tools by focusing on npm dependencies.

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

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

Explicit guidance on when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies limitations (NPM only in v1, other ecosystems handled elsewhere) and partial failure behavior (bundlephobia delays, sources_failed listing).

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral details: BGE-base-en embeddings + cosine over 500-char overlapping windows, 200K char cap with truncation flag, and offset for verification. 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?

Five sentences, front-loaded with purpose. Every sentence adds value (e.g., alternative tool pairing, technical details, return format). Very concise and well-structured.

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

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

Given no output schema, the description covers return values (passages with offsets and scores), parameter details (max 200K chars, limit range), and algorithm specifics. Complete for a search tool with good annotations.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds example queries and mentions the embedding algorithm, but these are more behavioral than semantic. Baseline 3 is appropriate.

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

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

The description clearly states 'Semantic search INSIDE a fetched record.' It specifies the verb (semantic search) and resource (inside a fetched record). It distinguishes from siblings like ask_pipeworx_grounded (for grounding) and fetch_feed (for fetching).

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded'. Provides clear when-to-use and alternative tool guidance.

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

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

The description fully discloses behavioral details: OAuth requirement, non-persistence for anonymous/BYO, return of subscription ID, webhook auto-disable after failures, and delivery channel rules. Annotations already indicate non-readonly, non-destructive, idempotent; the description adds significant context without 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 well-structured with clear sections for type and delivery examples. It is thorough but not excessively verbose; every sentence adds value. Could be slightly more concise, but no wasted words.

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

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

The tool has 3 parameters and moderate complexity. The description covers all subscription types, parameter formats, delivery methods, prerequisites, and return value. No major gaps, though error handling or rate limits are not mentioned.

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 valuable context to each parameter: type examples, params format for each type, delivery options with signing and disabling behavior. This goes beyond schema descriptions, justifying a 4.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, returning a subscription ID. It lists supported types and delivery channels, distinguishing it from siblings like unsubscribe 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 the prerequisite of a Pipeworx OAuth account and gives detailed guidance on which subscription type to use for what purpose. It also mentions limitations like SMS verification and daily cap, but does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds value by explaining it returns example questions with tool shapes from a live catalog, and its role as the onboarding entry point. No contradiction.

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

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

Single paragraph but well-structured: starts with common user questions, describes return value, then usage. No wasted sentences, though could be broken into clearer sections for readability.

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

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

Despite no output schema, description explains what is returned (category-bucketed examples with tool+argument shapes) and ties into broader system (meta-tools). Input is simple with one optional parameter; explanation is thorough and sufficient.

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

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

Schema description covers the only parameter (topic) with full coverage (100%). Description adds extra examples and clarifies behavior (omit for full spread, pass topic to focus), enhancing 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 it is the onboarding entry point returning category-bucketed example questions with tool and argument shapes. Distinguishes itself from siblings like ask_pipeworx by being the first tool to call when unfamiliar with Pipeworx capabilities.

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

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

Explicitly says use this first when you don't know what Pipeworx can do, and to learn meta-tools. Also explains how to call with or without topic. Lacks explicit 'when not to use' but context is clear.

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

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

Discloses key behaviors: ownership enforcement, deactivation vs deletion, preserving historical events. Adds value beyond annotations (idempotentHint, destructiveHint).

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

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

Two sentences, front-loaded with action, no wasted words. Information is well-structured.

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

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

Fully explains effect, constraints, and outcome for a single-parameter tool. 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; description adds context that 'id' is the UUID returned by 'subscribe', aiding correct invocation.

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 'Cancel' and resource 'subscription by id'. Distinguishes from sibling 'subscribe' by describing cancellation and ownership enforcement.

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 ownership enforcement and that the row is deactivated, providing clear use context. No explicit alternative mentioned, but the context is sufficient.

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 behavioral detail beyond those: the two-tier routing, the exact verdict enum, the distinction between could_not_verify and unsupported, the presence of verification_error{stage,detail}, and the instruction not to present a failed check as evidence. This is high-value context not available from annotations alone.

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 long paragraph but every sentence carries useful information: trigger phrases, routing logic, return values, error semantics, and the efficiency benefit. It is front-loaded with the use case and alternatives. It is somewhat long, but there is no filler or repetition, so it earns a 4 rather than a 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?

For a tool with no output schema, the description compensates thoroughly by listing the verdict enum, the structure of the result (grounded/structured value + citation + reasoning), the failure semantics, and the coverage scope. It also explains the two processing pipelines and the replacement of multiple sequential calls, making the tool's behavior clear even without seeing the output schema.

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

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

The input schema already documents both parameters fully with examples, constraints, and defaults (100% coverage). The description reinforces the purpose of the claim parameter and mentions tolerance override behavior only implicitly; it adds no significant new parameter semantics beyond what the schema provides. Therefore a baseline of 3 is appropriate.

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

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

The description opens with concrete natural-language triggers ('Is it true that…', 'fact check') and states the core function: natural-language claim verification against authoritative sources. It goes beyond a simple definition by distinguishing itself from sibling tools—it covers both the SEC/XBRL fast path for company financials and the grounded pipeline for all other claims, and explicitly notes it replaces 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides internal routing guidance (company financial claims vs. other claims) and a critical usage warning about not treating could_not_verify as evidence. It does not name alternative tools, but the 'replaces 4–6 sequential calls' note effectively implies when to choose this tool over chaining other operations.

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