Wayback

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the default free model, the requirement for an API key to use Anthropic, and the return structure (per-model fields + combined view). 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 long, front-loading the main action. Every sentence is necessary and informative, with no superfluous text. It is highly efficient.

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

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

Given the tool has 4 parameters and no output schema, the description explains the return structure sufficiently (per-model fields + combined). It covers purpose, behavioral nuances, and parameter usage well. Minor gaps like score calculation or confidence interpretation are not critical for basic usage.

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

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

With 100% schema description coverage, the baseline is 3. The description adds meaningful examples for entity (e.g., 'Pipeworx'), practical usage for models (which are supported, defaults), clarifies _apiKey purpose and pass-through, and explains context for disambiguation. This extra guidance justifies a 4.

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

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

The description clearly states it probes LLMs for knowledge about an entity and assigns a visibility score (0-100). It specifies the default model and optional Anthropic probe, but does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it's clear but lacks sibling distinction.

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 suggests uses like 'AI-marketing audits, pre-launch brand checks, competitive monitoring', providing context. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., entity_profile or deep_research), so guidance is implicit 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 declare readOnlyHint=true and destructiveHint=false, and the description adds value beyond them: internal routing behavior ('routes the question to the right one of 5,566 tools'), argument-filling behavior, stable pipeworx:// citation URIs in return values, and performance characteristics ('works on every tier, one fast call'). The description's read-only, idempotent query nature is fully consistent with all annotation hints — 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?

Dense but efficient — every sentence earns its place. The all-caps signposts ('PREFER OVER WEB SEARCH', 'START HERE', 'Step up only when needed') improve scannability, and the example list is compact. It's a long paragraph that could arguably be structured into bullets, but no word is wasted given the tool's default-entry-point role. Slight room to trim, hence 4 rather than 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 single-risk (non-destructive) tool with one required string parameter, no output schema, and no nested objects, the description is admirably complete: it covers what to ask, when to use it, when NOT to use it, what alternatives exist, expected output shape (structured with citations), and even handles edge cases like breaking news routing. No obvious gap in the agent's ability to decide when to invoke this tool correctly.

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

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

Schema description coverage is 100% — the schema documents the 'question' parameter with aliases (q, text, input, query, prompt) and provides descriptions and examples for each. The description doesn't add parameter-specific detail, but per the rubric, 100% coverage sets a baseline of 3, and the description's example queries do reinforce the parameter's usage without expanding semantics.

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

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

The description clearly states this is a query router for real-world data across 1,462 verified sources, with explicit categories (SEC, FDA, FRED/BLS, patents, etc.) and behavior (routes to one of 5,566 tools, fills arguments, returns pipeworx:// citations). It differentiates from siblings directly: 'START HERE for most questions — this is the default entry point' with explicit escalation paths to ask_pipeworx_grounded and deep_research.

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

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

Exceptionally explicit usage guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks "what is", "look up", "find"...', and most importantly, explicit when-NOT-to-use and what to use instead: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. Includes concrete example queries covering diverse domains.

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

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

Annotations already declare read-only and idempotent, but the description adds valuable context: it clarifies this is a fully working router (not a fallback), explains the experimental candidate lifecycle, and notes that no candidate is currently active so behavior matches stable. This goes beyond annotations without contradicting them.

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

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

The description is concise and front-loaded: it starts with the beta identification, immediately explains the relationship to ask_pipeworx, then gives usage guidance and a reassurance about functionality. No wasted words, well-structured in a few sentences.

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

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

For a router tool with no output schema, the description covers all essential aspects: purpose (universal router), current state (identical match), usage recommendation (newest routing), and behavioral transparency (experimental comparisons). It's complete for an agent to understand when and how to use it.

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

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

The input schema covers all parameters with 100% coverage—each alias is defined as an alias for 'question' and the canonical parameter has a full description. The description adds no additional parameter-level meaning beyond referencing that arguments are identical to ask_pipeworx, so a baseline of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools and arguments. It names the resource (ask_pipeworx) and distinguishes it from the stable version by calling out the experimental routing improvements and current alignment with stable.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and clarifies results are compared against the stable router to decide merges. This gives clear contextual guidance on when to choose this tool over the stable sibling.

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

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

Annotations only declare readOnly/idempotent/openWorld/destructiveHint flags, but the description discloses the full behavioral contract: internal routing across 5,566 tools and 1,462 sources, extraction strictly from tool results, exact success shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, and the complete failure contract with all refusal_reason enums (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also discloses the extra LLM call cost. Fully consistent with annotations; no contradiction.

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

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

Roughly 130 words that follow a logical, information-dense arc: purpose statement → routing behavior → output contract → use cases → cost tradeoff. Every sentence carries unique information; the return type and refusal semantics earn their place given there is no output schema to carry that data.

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 must carry the full return contract because there's no output schema, and it does so thoroughly: both return shapes, all refusal_reason enum values, and the semantic meaning of each failure. I deduct slightly for underspecified definitions of 'confidence' (no scale/type range) and 'source' semantics, which could confuse an agent acting on the result.

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

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

With 100% schema description coverage and 6 parameters that are all documented aliases for the same free-text question prompt, the schema fully describes the single conceptual parameter. The description adds usage context but no parameter-level semantics are needed beyond what the schema provides, so the baseline of 3 is warranted.

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+differentiator: 'Hallucination-resistant answer mode for high-stakes reads,' then precisely distinguishes from the sibling via 'Same routing as ask_pipeworx' with the concrete extraction-only behavior. The distinction from the sibling is explicit and operationalized (evidence verbatim quote, refusal_reason contract).

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

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

Explicitly states when to use ('Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'), gives concrete domain examples (financial verdicts, legal claims, medical lookups, public statements), names the alternative (prefer ask_pipeworx for casual lookups), and discloses the cost tradeoff (one extra LLM call). This is the gold standard for a usage directive.

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

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

Adds extensive behavioral context beyond annotations: resolution process, fan-out details, response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, wide-spread handling, cancellation rule risk. 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?

Long but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Front-loaded with main purpose and usage. Every sentence adds value for a complex tool. Slightly verbose but justified by breadth.

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

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

Given no output schema, the description thoroughly covers inputs, processing, outputs, edge cases (low confidence, closed markets, wide spreads), and cancellation rules. Leaves no major gaps for an agent to misinterpret.

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 parameter descriptions. Description adds value by clarifying the market parameter's flexible input formats (slug, URL, text) and the depth/include_raw options. Demonstrates usage via examples.

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 researches a Polymarket bet by pulling Pipeworx data. Distinguishes from sibling tools (e.g., polymarket_arbitrage, polymarket_edges) by focusing on individual bet research with specific usage examples.

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: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides examples but does not mention when not to use or direct alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), explains how off-calendar fiscal years are handled, and notes that output includes citation URIs. This goes beyond annotations, though it does not mention any rate limits or caching 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 moderately concise but front-loaded with common query patterns and a strong usage guideline. Every sentence contributes purpose or context. Minor redundancy (e.g., 'side-by-side comparison' is stated twice) but overall efficient for the information conveyed.

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

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

Given the tool has only 2 parameters with 100% schema coverage, good annotations, and no output schema, the description is fully adequate. It covers purpose, usage, parameter details, and behavioral traits, leaving no significant gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% (both parameters described). The description adds meaningful context: for the 'type' enum, it explains what data each entity type pulls (latest 10-K data for companies; adverse-event counts, FDA approvals, trial counts for drugs). For 'values', it provides concrete examples and constraints (tickers/CIKs for companies, drug names). 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: side-by-side comparison of 2-5 companies or drugs in one call. It starts with typical user query patterns (e.g., 'compare X and Y', 'X vs Y') and immediately distinguishes itself from sequential single-entity lookups, which are sibling tools like 'entity_profile'.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent when to use this tool instead of alternatives. It also clarifies that results are sorted by primary metric for queries like 'largest' or 'most'.

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?

Far exceeds annotation coverage. Annotations declare readOnlyHint=true and the description adds crucial behavioral context: account/auth requirements, timing expectations ('15-60s... up to ~90s'), the gaps[] never-invented guarantee, contradictions[] behavior, stable pipeworx:// citations that are 'always fetchable,' and semantic excerpting behavior. Discloses what the description acknowledges are its own limits around non-structural data.

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

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

Every sentence earns its place — there's no fluff. The description is dense and information-rich, front-loaded with the critical account requirement. The single-paragraph wall of text is hard to scan; better use of line breaks or bullet-style structure would help, but given the density of useful, non-redundant information across auth, semantics, timing, edge cases, and examples, it's highly 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?

For a complex tool with no output schema, the description fully compensates: it explains the findings packet format (verbatim evidence + confidence + source + fetched_at + stable citation), gap recovery hops, contradiction scanning, timeouts/expectations, auth prerequisites, and what happens with off-catalog topics (empty gaps[]). Given 1462 sources, 3 depth levels, 2 hops, and cross-cutting concerns like citations and contradiction detection, the description leaves nothing material uncovered.

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 strong inline descriptions of both params, so baseline is 3. The description adds real value on top with detailed depth-level semantics (quick=3 facets, standard=3 with gap-recovery, thorough=paid with iterative hops), concrete question examples, and what the 'question' parameter does when decomposed. Slight deduction for redundancy with the schema's depth descriptions, but the added behavioral meaning (e.g., contradictions[], timing implications) is genuinely useful.

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 is exceptionally clear: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' with specific verbs and scope. It explicitly differentiates from siblings by name: 'For a single lookup use ask_pipeworx' and 'this is NOT open-web search.' No ambiguity about what this tool does or how it differs from alternatives.

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

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

Explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx,' 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx,' plus account prerequisites ('If you are not signed in, use ask_pipeworx instead'). Also provides concrete example use cases and explains depth-level selection criteria.

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 and idempotent; description adds that it returns top-N tools with full schemas, no side effects. 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?

Single paragraph, front-loaded with purpose, efficient language, no redundancy.

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

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

Description covers input, output format, and usage context; no output schema needed as explained.

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 detailed descriptions and examples; description reinforces but does not add substantial new meaning beyond what's in schema.

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

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

The description clearly states the tool finds tools by describing data or task, and distinguishes it from siblings by being a discovery tool that returns schemas for direct calling.

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 calling this tool first when many tools are available, providing clear when-to-use guidance. Could be more explicit about when not to use, but still strong.

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

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

Annotations indicate readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral context: fans out across multiple sources, includes details on patents sunsetting, and mentions fallback mechanisms, going beyond annotations.

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

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

The description is a single paragraph but front-loads with examples and key guidance. Every sentence adds value, though the length could be slightly reduced for better scanability. Still efficient overall.

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

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

Given the tool's complexity (multi-source profile) and absence of an output schema, the description is fairly complete. It lists return fields, mentions limitations (patents sunset), and fallback behavior. Minor gaps in return structure, but 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% with both parameters described. The description adds value by clarifying that 'type' is only 'company' and 'value' is ticker or CIK, and emphasizes that names are not supported. This adds meaning beyond schema.

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

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

The description clearly states the tool's purpose as a 'full cross-source profile of a US public company in ONE parallel call' with specific examples like 'Tell me about X'. It distinguishes itself from chaining single-source 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 advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. Also specifies that names are not supported and directs users to use resolve_entity first, providing clear when-to-use and alternatives.

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

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

The description confirms the destructive nature ('Delete'), which aligns with the destructiveHint=true annotation. It adds little beyond the annotation, only hinting at the use case for clearing sensitive data, but does not contradict annotations.

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

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

The description is extremely concise with two sentences, no wasted words, and front-loads the core purpose ('Delete a previously stored memory by key').

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

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

Given the tool has only one parameter, no output schema, and annotations covering destructive and idempotent hints, the description is complete. It explains the purpose, when to use it, and references sibling tools for context.

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

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

The schema covers 100% of the single parameter with a description for 'key'. The description repeats 'by key' without adding format or additional constraints, so it meets the baseline but adds no extra 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 clearly states the action ('Delete') and the resource ('a previously stored memory by key'), which is specific and distinct from siblings like '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?

It explicitly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data'), providing clear context. However, it does not specify when not to use it or give alternatives beyond mentioning sibling tools.

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

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

The description adds behavioral context beyond the annotations: it fetches the page, extracts title/description/links, emits markdown. Annotations declare readOnly and idempotent, which align with the description. No contradictions; the process details enhance transparency.

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

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

The description is concise (two sentences) with a clear, front-loaded purpose statement. Every sentence adds value, and there is no redundancy or fluff.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers what the tool does, the output format, and typical use cases. Nothing essential 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%, and the description adds minimal new parameter info (mentions max_links default/max values). The description explains the overall tool behavior but does not deepen parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, explaining the purpose and output format. It distinguishes itself from sibling tools by specifying its unique action (generating llms.txt) and use cases (indexing, drafting, auditing).

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. While it doesn't list when not to use or direct alternatives, the sibling tools list has no direct substitutes, making the guidance clear enough.

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

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

Annotations already declare readOnlyHint=true. Description adds that it returns timestamps in YYYYMMDDhhmmss format, providing useful additional behavioral context beyond annotations.

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

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

Two concise sentences with no wasted words. Front-loaded with purpose, then 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?

Simple 1-param tool with rich annotations; description explains output (count + earliest/latest timestamps) adequately. 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 coverage is 100% with clear description of 'url' parameter. Description does not add new meaning beyond what schema already provides.

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

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

Description clearly states verb 'Count' and resource 'captures by Internet Archive Wayback Machine', and distinguishes from siblings like 'get_snapshot' and 'list_snapshots'.

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

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

No explicit when-to-use or when-not-to-use guidance. Context of counting vs retrieving snapshots is implied but not stated, 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, idempotentHint, and not destructive. The description adds behavioral context: it returns the 'closest available' snapshot (not exact) and specifies the returned fields (URL, timestamp, status).

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

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

Two sentences, no unnecessary words, front-loaded with the core 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?

For a simple lookup tool with no output schema, the description adequately explains the return value (Wayback URL, timestamp, HTTP status). It is complete enough for an agent to use.

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

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

Schema covers both parameters. Description adds semantics by explaining the effect of including/excluding the timestamp parameter, going beyond the schema's type and format hints.

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 an archived web page from the Internet Archive Wayback Machine, specifying the verb (look up) and resource (archived version). It distinguishes from sibling tools by focusing on historical snapshots.

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

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

It explains when to include the timestamp parameter (to get snapshot near a specific date) and when to omit it (get latest). While it doesn't explicitly list exclusions, the context is clear for this tool's single purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safe behavior. The description adds value by detailing the output fields and date format constraints, beyond what annotations provide. No contradictions.

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

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

The description is two sentences, front-loaded with the core action. Every sentence provides essential information without redundancy.

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

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

For a simple listing tool, the description covers the purpose, output structure, optional date range, and constraints. No output schema exists, so the description appropriately describes return fields. Annotations cover safety and idempotency.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the meaning of from/to as date range parameters with YYYYMMDD format, but this is already clear from the schema. No additional semantic depth 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 snapshots of a URL from the Internet Archive Wayback Machine, specifying key fields (timestamp, URL, status, MIME, digest, Wayback URL) and the use of the CDX index. This distinguishes it from siblings like get_snapshot (single snapshot) and get_capture_count (count only).

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 listing multiple snapshots with optional date range restriction, but does not explicitly state when to use this tool versus alternatives (e.g., get_snapshot for a single capture). No exclusions or when-not-to-use guidance are provided.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by listing return fields and default filtering (active subscriptions). No contradiction with annotations.

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

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

Two sentences, efficient and front-loaded. The first sentence states the core purpose, the second adds usage guidance. No unnecessary words.

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

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

With annotations covering safety and schema covering parameters, the description adds return field details and usage context. It is complete for a simple list tool, though it could mention response format or pagination if applicable.

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

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

Schema coverage is 100% with the single boolean parameter clearly described. The description does not elaborate further on the parameter beyond the schema context, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifying return fields (id, type, params, etc.). This distinguishes it from sibling tools subscribe and unsubscribe, which perform different actions.

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

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

Explicitly provides use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool versus alternatives.

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

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

With all annotations false, the description carries the full burden and delivers rich behavioral context: it is rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, returns a claim_token when filed without an account, and the team reads digests daily. This goes well beyond what annotations state and contains 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?

Although lengthy, the description is front-loaded with purpose and every sentence adds operational detail—scope boundaries, token flow, rate limits, and quota behavior. Nothing feels redundant; the length is justified by the tool's nuanced behavior.

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 that there is no output schema and the tool has nuanced semantics (claim_token follow-up, scope restrictions, rate limiting), the description covers all essential aspects: input conventions, expected return token, status checking, and operational limits. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns a 4 by adding practical semantics beyond the schema: it advises describing issues in terms of Pipeworx tools/packs rather than pasting the user's prompt, and it explains the claim_token round-trip invocation pattern for reading replies.

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 opening sentence 'Tell the Pipeworx team something is broken, missing, or needs to exist' gives a specific verb and resource. It also distinguishes itself from siblings by explicitly limiting feedback to tools served by this Pipeworx connection and excluding tools from other MCP servers.

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 enumerates when to use the tool (bug, feature/data_gap, praise) and provides a clear when-not case ('if the tool came from a different MCP server... file it with that server instead'). It also explains the claim_token flow for later status checks, which is strong usage guidance.

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

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

Adds behavioral details beyond annotations: data derived from CF analytics-engine, no PII, caching policy (5min-1h). Complements readOnlyHint/openWorldHint with concrete implementation context.

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

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

Three well-structured sentences, bulleted list of use cases, no redundant words. Every sentence earns its place.

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

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

Given low complexity (1 param, no output schema) and rich annotations, the description fully covers purpose, use cases, caching, and data source. No gaps.

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

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

Schema already describes enum and default. Description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond schema.

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

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

Description clearly states the tool returns top tools, packs, and call volume. Uses specific verb 'Returns' and resource. Differentiates from siblings like ask_pipeworx and discover_tools by focusing on aggregated analytics.

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?

Lists three explicit use cases with bullet points and window selection guidance. Lacks explicit when-not-to-use, but context is strong.

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

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

The description discloses detailed internal logic: monotonicity checks, partition-sum with >3pp threshold, Jaccard similarity filter, placeholder filtering, and fill check against CLOB depth. Annotations already indicate read-only, idempotent, non-destructive; description adds significant behavioral context and does not contradict.

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

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

The description is well-structured with sections and bullet points, front-loading the purpose. However, it is quite lengthy and includes technical details that could be summarized more concisely, but the complexity of the tool justifies the length.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities[] with fields) and includes fill check results. It also mentions when not to trade and directs to a related tool for custom sizing, making the description self-contained.

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 has 100% coverage with descriptions for event and topic. The tool description adds examples and explains how each parameter changes behavior (single-event vs cross-event), which is valuable but only extends the schema description moderately.

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 itself from general edge-finding tools by specifying the method, but does not explicitly differentiate from sibling tool 'polymarket_edges', which may cause confusion.

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

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

The description provides explicit when-to-use guidance: no args for trending scan, event for specific market, topic for cross-event scan. It also recommends event mode and advises against trading when realizable_edge_pp ≤ 0, and mentions polymarket_fill_risk for custom sizing, covering alternatives.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent. Description adds caching detail ('Cached 1h at the KV level'), response structure, and edge computation transparency (slippage, Kelly, diagnostics). 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?

Well-structured with front-loaded purpose, clear sectioning of model families, knobs, and response. Slightly long but each part adds value; could be more concise on technical details.

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

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

No output schema, but description thoroughly explains output structure (by_segment, fed_candidates, diagnostics), edge calculation, caching, and all parameters in context. Fully complete for a complex tool.

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

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

Schema coverage is 100%, but description adds context beyond schema: e.g., slippage_pp explanation of Polymarket fees, min_partition_leg_kelly distinction from min_kelly, and usage of knobs in model 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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and is built for 'what should I bet on today.' It distinguishes from siblings by focusing on model-disagreement edges, not just 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?

Provides extensive guidance on model families, tradeable-edge knobs, Fed bet exclusion, and diagnostics for empty segments. Lacks explicit when-not-to-use vs siblings like polymarket_arbitrage but is implicitly clear through unique value proposition.

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 beyond annotations: response structure (tracked, expired, snapshot_dates), fields (edge_pp_net time-series, first_seen, trend, decay_pp_per_day, lifespan_days), and limitations (60-day snapshot TTL, decay computed from daily closes not intraday). Annotations already indicate read-only, open-world, idempotent, non-destructive; description adds detailed behavioral context.

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

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

Description is concise yet comprehensive: two sentences on purpose, then a structured breakdown of the response, followed by limitations. Every sentence adds essential information without redundancy.

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

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

Given no output schema, the description fully explains the response structure: tracked[] with time-series and computed fields, expired[] with lifespan_days, and snapshot_dates[]. It also explains limits like TTL and computation basis, making the tool's behavior fully understandable.

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 with descriptions including defaults and clamp. Description adds 'lookback default 14, max 30' for days and 'default 1wk' for window, providing a bit more usage context. Schema already has these details, so description adds minor value beyond schema.

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

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

Description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it is shrinking. It contrasts with a fresh wide edge vs. a 3-week-old one, distinguishing it from sibling tools like polymarket_edges which likely provide current edge data.

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?

Implicitly guides usage by explaining the significance of edge age: 'a fresh wide edge and a 3-week-old wide edge are different trades' and that the latter is wide for a reason. It does not explicitly state when not to use it, but the context is clear enough for an AI agent to decide.

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. The description adds significant behavioral context: explains that it checks against live order-book depth, walks the ladder, returns fill details, warns about partial basket fills converting into unhedged directional positions, and describes size_usd interpretation. No contradictions.

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

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

The description is lengthy but front-loaded with purpose. Uses all-caps for key distinctions (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence provides necessary detail given the tool's complexity (two modes, output fields, risks). Could be slightly more concise but justified.

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

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

Despite lacking an output schema, the description thoroughly enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict for single-market; theoretical_sum, capture_ratio, profit_usd, etc. for basket). Explains interpretations and risks, making it complete for agent understanding.

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%, but the description adds substantial value: clarifies the difference between market and event parameters, explains default side behavior ('auto from partition sum'), interprets size_usd differently for single-market vs basket, and mentions defaults and clamps. This goes well beyond the schema.

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

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

The description states a specific verb-resource pair ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes between single-market and basket modes. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by explicitly recommending use before acting on their signals.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains context for when to use each mode (single-market vs basket) and highlights risks. Lacks explicit when-not-to-use scenarios but overall strong.

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

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

Annotations indicate readOnly, openWorld, idempotent. The description goes far beyond by explaining response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and caveats (non-equivalent bet shapes, temporal gaps). This is comprehensive transparency.

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

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

The description is verbose but well-structured: overall purpose, modes, response format, safety fields, and warnings. Every sentence adds value, though it could be slightly tightened. It is front-loaded with the main idea.

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 three optional parameters, no output schema, and complex behavior, the description is remarkably complete. It explains input options, output structure with safety fields, and provides troubleshooting guidance for the two modes.

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

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

Schema coverage is 100%, and the description adds extensive meaning: explains the two modes, lists the 10 pre-mapped topics, and clarifies that explicit parameters override the topic-mapped side. It also contextualizes the topic parameter's limitations (most pre-mapped topics return warnings).

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with two modes (topic shortcuts and explicit tickers). It distinguishes itself from other tools like polymarket_arbitrage by focusing on cross-venue spread.

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

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

Provides explicit guidance on when to use (cross-venue spread for same resolving question) and details two modes. It warns that most pre-mapped topics return compatibility warnings, guiding against over-reliance. However, it doesn't explicitly state when not to use, though the safety fields implicitly do.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail (by identifier) and pairing with remember/forget. No contradictions.

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

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

Three sentences: core function, usage motivation, scoping/pairing. No extraneous words. Information is front-loaded.

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

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

Given the single optional parameter, no output schema, and annotations covering safety, the description fully covers behavior, scoping, and relationships with sibling tools.

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

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

Schema description coverage is 100%. Description explains the key parameter's effect when omitted ('list all keys'), which adds behavioral context beyond the schema's property description.

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

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

The description uses specific verbs ('retrieve', 'list') and resources ('value saved via remember', 'saved keys'). It clearly distinguishes from sibling tools 'remember' and 'forget' by naming them.

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

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

Explicitly states when to use (look up stored context) and when to omit the key (list all). Implicitly suggests when not to use by directing to sibling tools for save/delete. No explicit when-not conditions, 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?

The description reveals a side effect via 'mark_read:true to flag returned events read', which contradicts the annotation 'readOnlyHint': true. According to rules, this contradiction merits a score of 1.

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

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

The description is a single paragraph of five sentences, front-loading the action and avoiding wasted words. It is efficient, though slightly more structured formatting could improve scannability.

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 (source, citation_uri, raw payload). It covers all parameters, usage context (polling, alternative access), and behavior. Lacks only edge-case details for a perfect score.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameters: 'Filter by type (e.g. 'sec_8k') and/or since (ISO timestamp)' and 'Set mark_read:true to flag returned events read', enhancing understanding beyond the schema.

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

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

The description clearly states 'Pull fired events from your subscription feed' and 'Returns the most recent alerts', specifying the verb and resource. It distinguishes the tool's purpose from siblings like 'recent_changes' but does not explicitly differentiate from other alert-related 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 mentions 'Polls work fine' and points to an alternative URL for scripts/dashboards, providing some usage context. However, it does not explicitly guide when to use this tool over siblings or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, ensuring safety. The description adds key behavioral details: parallel fan-out to multiple sources, soft-failure for USPTO, and GDELT→GNews fallback on rate limits or 5xx errors. This goes beyond annotations to inform the agent of operational traits.

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

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

The description is concise yet thorough, covering purpose, sources, fallback, parameter formats, return structure, and sibling differentiation in a well-organized single paragraph. Every sentence adds value, and the structure is front-loaded with key examples.

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?

Since there is no output schema, the description compensates by describing the return format (changes grouped by source, total_changes count, citation URIs). It also covers all key behaviors (parallel calls, fallbacks, soft-fails). For a complex tool with 3 required parameters and no output schema, the description is fully 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%, but the description adds significant meaning: it explains that 'since' accepts ISO dates or relative shorthand with examples, confirms 'type' is limited to 'company', and specifies that 'value' accepts ticker or CIK. This rich context helps the agent use parameters correctly.

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

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

The description clearly states that this tool provides a change feed for a company, covering SEC filings, news via GDELT/GNews, and patents. It uses multiple example queries to illustrate common use cases and explicitly differentiates from the sibling 'entity_profile' for static profiles.

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

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

The description provides explicit guidance on when to use this tool (dynamic changes over time) versus 'entity_profile' (static profile). It also details fallback behavior between GDELT and GNews, giving the agent clear decision criteria.

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

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

Description adds context beyond annotations: memory duration (persistent for authenticated users, 24-hour for anonymous sessions), scoping by identifier. No contradictions with annotations.

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

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

Three concise sentences, front-loaded with purpose, efficient structure, 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?

Complete for a simple key-value store tool; covers when to use, storage details, and pairing with siblings. No output schema needed for this straightforward action.

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 provides clear descriptions and examples; description reinforces with usage context (e.g., 'resolved ticker, target address'). Adds value without redundancy.

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?

Explicitly states the tool saves data for reuse, with clear verb+resource. Distinguishes from siblings by mentioning recall and forget.

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

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

Provides explicit when to use: 'when you discover something worth carrying forward'. Also specifies alternatives: 'Pair with recall to retrieve later, forget to delete.'

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, but the description adds substantial behavioral context: identifiers are labeled by source, unresolved identifiers are explicitly stated under 'unresolved', ISIN-to-LEI mapping covers non-US issuers, and GLEIF/OpenFIGI degradation is handled gracefully. It also discloses internal multi-endpoint cascading, going well beyond annotation basics.

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

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

The description is long but front-loaded with examples and the core directive. Each section (supported types, details, degradation) is purposeful, yet some phrasing like 'cross-source identity spine' adds jargon without clear benefit. The structure is organized by type and is easy to scan, but a few sentences could be tightened without losing value.

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

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

Despite lacking an output schema, the description thoroughly covers return values and behaviors: for company it lists CIK, ticker, LEI, FIGI, ownership info, source labels, and unresolved handling; for drug it lists RxCUI, ingredient, brand, and citation. It also addresses failure modes (GLEIF/OpenFIGI unavailability) and notes that internal cascading replaces multiple manual lookups, 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 description coverage is 100% (both parameters are described), so the baseline is 3. The description adds significant meaning by elaborating the 'type' enum (company vs. drug) with detailed outputs and explaining accepted input formats for 'value' (ticker, CIK, ISIN, names). While the schema already gives examples, the description's enrichment justifies a 4.

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

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

The description clearly states the tool resolves a user-spoken NAME to canonical/official identifiers, with a specific verb ('resolve') and resource ('entity name to identifiers'). It provides concrete query examples and differentiates itself by saying 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools like entity_profile that likely operate on known IDs.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also lists supported types (company, drug) and input formats (ticker, CIK, ISIN, name, brand/generic), making the when-to-use context clear. It does not name alternatives, but the 'FIRST' directive strongly implies using this before other tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: probes each entity, ranks by score, surfaces most/least recognized, and treats first entity as 'subject'. No contradiction with annotations.

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

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

Three sentences, front-loaded with main purpose, then details. No fluff or repetition. Efficiently conveys purpose, process, and use case.

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 4 parameters and no output schema, the description adequately explains the workflow and output (ranked list with score, confidence, signal density). It covers the use case and process. Minor gap: does not explicitly mention idempotency constraints.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds some meaning: explains that first entity is treated as subject and context disambiguates common names. However, it does not significantly extend 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 compares AI visibility across multiple entities side-by-side, uses specific verbs like 'Compare' and 'probes', and distinguishes from sibling tools like ai_visibility_check and compare_entities by focusing on AI recognition.

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

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

Provides clear context for usage: 'competitive AI-marketing audits' and gives an example question. Implicitly suggests ai_visibility_check for single entity checks, but does not explicitly state when not to use this tool or list alternatives.

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

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

Beyond annotations (readOnly, idempotent, etc.), description details partial failures, bundlephobia latency (5-30s) on new versions, and the sources_failed field. 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?

Description is somewhat long but front-loaded with core purpose. Every sentence adds value, no redundancy. Could be slightly more concise but overall efficient.

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

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

Despite no output schema, the description enumerates return fields (summary block, advisories, links, alternative versions) and covers edge cases (partial failures, ecosystem limitation). Complete for a 2-param 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 already describes both parameters (100% coverage). Description adds value by noting scoped packages are accepted and giving version example format. Baseline 3, plus extra contextual guidance.

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

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

Description clearly states the tool performs a composite check for evaluating an npm package across deps.dev and bundlephobia, answering questions about safety, popularity, size. It distinguishes itself by being a one-call aggregation, and no sibling tool has overlapping purpose.

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

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

Explicitly says use when agent asks about safety/popularity/size or cost of adding a package. NPM-only scope stated, with fallback instructions for other ecosystems via deps.dev:version directly. Provides clear context and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral details: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars), and truncation behavior. This goes beyond annotations.

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

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

The description is concise (4-5 sentences) and front-loaded with the core purpose. Every sentence adds value: usage context, examples, pairing, technical details, and output format. 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?

For a tool with no output schema, the description fully explains return format (passages with offsets and scores). Annotations cover safety, schema covers parameters, and context signals are clear. No missing aspects.

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 detailed parameter descriptions. The description adds example queries and clarifies the text cap, but these are minor additions. Baseline is 3 due to high schema coverage.

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

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

The description clearly states it performs 'semantic search INSIDE a fetched record' with examples like SEC 10-K, which is a specific verb and resource. It also distinguishes itself from siblings by noting the use case for large records and pairing with ask_pipeworx_grounded for grounding.

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 using this tool when a record is too big for the prompt and mentions pairing with ask_pipeworx_grounded, providing clear usage context. It doesn't list exclusions or alternative tools beyond that pairing, but the guidance 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?

Disclosures beyond annotations include requiring OAuth accounts, phone verification for SMS with a 10/day cap, webhook HMAC signing with secret retrieval, and auto-disable after 10 consecutive failures. These details add significant value and align with annotations (idempotentHint=true, destructiveHint=false). No contradiction.

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

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

The description is about 150 words, front-loaded with the main action, and uses examples and bullet-like formatting. While detailed, it occasionally repeats schema info (e.g., enum values) and could be slightly more concise.

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

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

Given the complexity (3 parameters, nested objects, multiple types, delivery channels, no output schema), the description covers prerequisites, type-specific filters, delivery mechanisms, and idempotency hints. Missing return value details and omission of two subscription types prevent a perfect score.

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 useful parameter examples for three out of five types (sec_8k, polymarket_edge, fred_series) but omits patent_grant and clinical_trial, reducing completeness. The delivery object is well-explained with additional 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This provides a specific verb (create) and resource (subscription to event stream), distinguishing it from siblings like list_subscriptions (listing) and unsubscribe (removing).

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 prerequisites ('Requires a Pipeworx OAuth account'), provides examples of supported types with parameter hints, and details delivery constraints. However, it does not explicitly contrast with alternative tools like 'polymarket_edge_tracker' or when not to use subscribe, leaving room for improvement.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds value by explaining the call behavior (no args vs. topic) and the output structure, which goes beyond what annotations provide.

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

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

The description is clear and front-loaded with example queries. It contains multiple clauses but each adds necessary context; could be slightly more concise but is well-structured.

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

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

Despite lacking an output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shape) and references the live tool catalog. The context signals support the description's completeness.

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

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

Schema coverage is 100% with a single optional parameter 'topic'. The description enumerates the possible values (finance, pharma, etc.) and clarifies behavior when omitted, adding meaningful semantics beyond the schema's brief description.

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

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

The description explicitly states the tool returns category-bucketed example questions with exact tool and argument shapes, making it clear that it helps users discover what to ask. It distinguishes from siblings by positioning it as the onboarding entry point.

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

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

The description directly says 'Use this FIRST when you do not yet know what Pipeworx can do for you,' providing clear guidance on when to invoke. It also specifies optional topic parameter usage and when to omit for a full spread.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds value by explaining that the row is deactivated (not deleted) and historical events remain available via recent_alerts. No contradiction with annotations.

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

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

Two concise sentences that deliver essential information immediately. No unnecessary words or repetition.

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

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

Given the tool's simplicity (1 param, no output schema), the description covers all necessary aspects: action, parameter source, ownership constraint, and side effects. Fully adequate 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?

The single parameter 'id' is fully described in the schema as a subscription id returned by subscribe. The description does not add additional meaning beyond that, so baseline 3 is appropriate.

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

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

The description clearly states the action (cancel a subscription by id) and the resource (subscriptions). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the operation (cancellation) and uniqueness (by 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?

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when the tool can be used. It does not explicitly mention alternatives or when not to use, but the context is clear enough for an agent.

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

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

Goes beyond annotations by explaining the crucial distinction between could_not_verify (check did not happen due to LLM/source failure) and unsupported (no source coverage), including that could_not_verify must not be shown as evidence. Discloses return structure (verdict, actual value, citation, reasoning) and error semantics. No contradiction with readOnlyHint/openWorldHint.

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

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

The description is longer than average but densely packed with useful routing, error-handling, and replacement guidance. Each section contributes value, though a few phrases (e.g., 'grounded pipeline — routed to the right live source') are slightly redundant with earlier mentions. Overall well-structured and front-loaded with the core purpose.

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

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

Despite no output schema, the description fully explains return values (verdict types, actual value with citation, reasoning) and error states (could_not_verify with verification_error, unsupported). It accounts for the tool's complexity by covering two distinct pipelines and the tolerance semantics. Given its complexity, this is a complete and self-sufficient description.

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

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

Schema coverage is 100%, so the baseline is 3. The description provides claim examples but does not add meaningful semantic detail beyond the schema. The tolerance_pct parameter is explained in the schema (and the description implies its existence through grading logic) but not elaborated in the description itself.

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 defines the tool as a claim verifier with specific trigger examples ("Is it true that…", "fact check"). It uniquely identifies the resource (factual claims) and distinguishes itself from sibling tools, which are unrelated to claim verification.

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?

States explicitly when to use ("Use whenever the agent needs to check whether something a user said is factually correct") and provides routing guidance between the SEC EDGAR path for company-financial claims and the grounded pipeline for all other claims. Also notes it replaces 4–6 sequential calls, clarifying efficiency.

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