Leetcode

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: default model, payment model for Anthropic, and return structure. No contradictions.

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

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

The description is concise with four sentences, front-loading the core action and return structure. Every sentence provides useful 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?

With no output schema, the description compensates by detailing return fields (score, confidence, signals, raw_response) and combined view. It covers all relevant aspects for agent use.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema by explaining the default model, the need for `_apiKey`, and the purpose of `context`, which helps interpret entity ambiguity.

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

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

The description clearly states the tool probes LLMs for entity knowledge and scores visibility (0-100). It is specific about the action and resource, but does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', which may overlap.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not specify when not to use or contrast with alternatives. For a tool with many siblings, more explicit guidance would be helpful.

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

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

Annotations already mark readOnlyHint and idempotentHint. The description adds that it routes to one of 5,564 tools from 1,462 sources and returns 'stable pipeworx:// citation URIs', which usefully explains its internal behavior and output format 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 front-loaded with the key recommendation, then explains scope, examples, and fallback options. It's detailed but each sentence adds value; minor inefficiency from listing all aliases again.

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 compensates by describing the return format (stable pipeworx:// citation URIs). It covers inputs, usage rules, and alternatives comprehensively, making it complete for a broad factual query tool.

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

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

Schema coverage is 100% with aliases documented. The description adds no additional parameter nuance beyond what the schema provides, 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 answers factual questions with structured data citations. It explicitly contrasts with web search and names the specific data domains (SEC, FDA, etc.), making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), provides example queries, and names specific alternatives (ask_pipeworx_grounded, deep_research) with clear conditions for stepping up.

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

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

The description adds significant behavioral context beyond annotations. While annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature, the description explains the beta behavior: candidate improvements are tested live, results are compared to decide merges, and the tool falls back to the stable behavior when no candidate is active. Annotations already cover the safety profile well, so the bar is lower; the description provides excellent additional transparency about the routing logic without contradiction.

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

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

Exceptionally concise and well-structured. The description uses three focused sentences: the first establishes identity and relationship to the stable router, the second provides current status (no active candidate), and the third gives clear usage directives. Every sentence earns its place with no wasted words—a model of efficient tool documentation.

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

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

Given the tool's complexity as a universal router with over 5,000 tools, the description is remarkably complete. Without an output schema, it could discuss return shape, but it notes 'same response shape' referring to ask_pipeworx, which suffices. The description covers purpose, current state, usage instructions, and fallback behavior, making it self-contained and sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema thoroughly documents all six parameters and their aliases. The description adds no specific parameter-level detail, which is appropriate given complete schema coverage (baseline 3). However, it earns a 4 because the description's context about the tool being a universal router for 5,564 tools implicitly clarifies that the 'question' parameter is a natural language query that gets routed to the appropriate underlying tool, adding semantic meaning beyond the bare schema descriptions.

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

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

The description is exceptionally clear: it states the tool is a 'Beta version of ask_pipeworx' that serves as an 'identical universal router' for over 5,000 tools. It explicitly distinguishes itself from the stable router by noting it is the experimental edge for testing candidate routing improvements, leaving no ambiguity about the purpose.

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

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

Usage guidelines are explicit and comprehensive. The description states 'Use it exactly like ask_pipeworx when you want the newest routing' and provides the exclusion context: 'No candidate is active right now... this currently matches ask_pipeworx exactly.' It also explains the tool's role in A/B testing (results compared against stable router), enabling the agent to decide when to invoke this version over its sibling.

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

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

The description adds significant behavioral context beyond the annotations: it explains the hallucination-resistant extraction process, the explicit refusal reasons (list of five), and the return format with evidence and source. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is well-structured with a clear first sentence stating purpose, followed by process details, return format, usage guidelines, and cost trade-off. Every sentence is informative and earns its place with no redundancy.

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

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

Given the tool's complexity (selecting from 5564 tools, filling arguments), the description is highly complete: it explains the return schema and refusal reasons, differentiates from siblings, and notes the extra cost. Despite no output schema, the description covers what to expect on success and failure.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description does not add any new meaning beyond what the schema provides for the parameters. Baseline 3 is appropriate since the schema already carries the full burden.

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

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

The description clearly states the tool's purpose as 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling 'ask_pipeworx' for casual lookups. It explains the process of picking the right tool, fetching data, and extracting the answer using only the tool result, making the purpose highly specific.

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

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

Explicitly states when to use (high-stakes reads where answers will be quoted, cited, or acted on) and when to prefer the sibling 'ask_pipeworx' (casual lookups). Also mentions the cost trade-off of one extra LLM call, providing clear decision guidance.

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

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

The description is exceptionally transparent about behaviors: market resolution, classifier fan-out, response shapes, resolver contract conflict warnings, parent event extraction, news fallback mechanisms, safety low-confidence blocking, closed market handling, wide-spread flags, and resolution-rule risk. All align with annotations (read-only, idempotent, open world) without contradiction.

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

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

The description is verbose and contains extensive detail (examples, fan-out specifics, edge cases). While thorough, it could be more concise and structured (e.g., using bullet points or sections) to aid quick parsing by an AI agent. The front-loading of the core action is good, but the density of information reduces overall conciseness.

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

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

Given the tool's complexity (multiple outputs, classifier categories, fan-out, safety mechanisms) and the absence of an output schema, the description covers all necessary context: inputs, examples, classification list, fan-out examples, response shapes, resolver contract, parent event extraction, news fields, low-confidence handling, closed markets, spread warnings, and resolution rules. It 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% with descriptions for all three parameters. The tool description adds value beyond the schema by explaining the market parameter accepts multiple formats, the depth parameter defaults to 'thorough', and include_raw provides summarized vs. full payloads. This extra context justifies a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison). The purpose is distinct from sibling tools like polymarket_edges or polymarket_arbitrage, as it is a comprehensive research call.

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

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

Explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples and fan-out patterns. However, it does not explicitly state when NOT to use this tool or mention 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?

Beyond the readOnlyHint annotation, description adds that it pulls latest data, sorts by primary metric for easy interpretation, and returns citation URIs. Explains fiscal year handling and data sources.

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 well-structured with front-loaded examples and clear separation of company vs drug details. Every sentence adds value, though minor trimming possible.

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

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

Despite no output schema, description explains return format (paired data + citation URIs). Covers both entity types comprehensively, making it complete for the tool's complexity.

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

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

With 100% schema coverage, description adds meaning by giving concrete examples (tickers/CIKs for company, names for drug), explaining max/min items, and detailing how type parameter affects data sources.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2-5 companies or drugs, with many example queries. It distinguishes itself from siblings by noting it replaces up to 15 sequential lookups.

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

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

Provides explicit guidance on when to use (comparing entities) and when to prefer it over alternatives. Includes examples for inputs and notes correct handling of off-calendar fiscal years.

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 minimal behavioral context beyond the annotations. Annotations already indicate readOnly=true, idempotent=true. The description merely says 'today's' implying time-dependence but without detail on time zone or caching policy.

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 at 4 words, no fluff. It front-loads the core purpose effectively for a simple parameterless tool.

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 presence of an output schema and rich annotations, the description is minimally complete. However, it does not explain what constitutes a 'daily challenge' or the format, which could be inferred from the schema but is not explicitly stated.

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 tool has no parameters and schema coverage is 100%. The description does not need to elaborate on parameters, so it is adequate.

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

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

The description clearly states it provides 'Today's daily coding challenge,' specifying verb (challenge) and resource (daily coding). However, it does not differentiate from sibling tools like 'problem' or 'suggest_questions' that may also relate to coding challenges.

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 guidance is given on when to use this tool versus siblings. For instance, if the agent needs a specific problem by ID, 'problem' would be more appropriate; but the description does not mention such 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 (readOnlyHint etc.), the description details account requirements, depth level behaviors (gap recovery, contradictions, hop field), expected duration (15-90s), return findings structure (verbatim evidence, confidence, citations, gaps[], contradictions[]), and semantic excerpting. No contradiction with annotations.

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

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

The description is verbose but every sentence adds value. It is front-loaded with critical account requirement and alternatives. Could be slightly more scannable with bullet points or sections, but remains efficient given the complexity of the tool.

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 the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]), depth behavior, and edge cases (e.g., empty gaps for unstructured topics). Covers all aspects needed for correct invocation and expectation setting.

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

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

Description adds significant meaning beyond the input schema. It explains depth enum values in detail (quick=3 single hop, standard=3 with gap recovery+contradictions, thorough=6 paid iterative hop+contradictions) and clarifies question as natural language supporting broad/multi-part decomposition. Schema coverage is 100%, but the description provides operational 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 it performs grounded multi-source research across 1462 structured data sources in one call, decomposing questions into facets. It distinguishes itself from sibling tools like ask_pipeworx, which is for single lookups or breaking news. The verb 'research' plus resource specification is precise.

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

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

Explicitly tells when to use this tool vs alternatives: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also states best use case: 'Best for broad/multi-part questions over structured data'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral details: returns top-N tools with full schemas and curated examples, ready to call directly. No contradiction.

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

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

The description is front-loaded with the core purpose, followed by usage guidance and return value details. It is concise (3-4 sentences) with no wasted words.

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

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

Given 35 siblings and no output schema, the description fully explains the return value (names, descriptions, schemas), all parameters are covered, and the use case is clear. No apparent gaps.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds context about aliases and natural language usage, but doesn't significantly expand beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Find' and resource 'tools', and distinguishes from siblings by emphasizing discovery and browsing of many domains (SEC filings, FDA, etc.). It is specific and not a tautology.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST' when many tools are available, providing clear guidance on when to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it fans out across multiple sources, notes USPTO PatentsView API sunset (soft-fails), and explains fallback behavior (GDELT→GNews). 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?

Front-loaded with examples and core purpose, then details. A bit lengthy but every sentence adds value. Well-structured for readability.

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

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

Despite no output schema, the description comprehensively lists return fields (CIK, filings, fundamentals, patents, news, LEI) and describes data sources and ordering. Adequately covers the complexity of a multi-source profile 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 documented). The description reinforces meaning with examples ('AAPL', '0000320193') and reiterates that names are not supported, adding clarity beyond the schema. Baseline 3 for high coverage, but extra examples earn 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 starts with example queries like 'Tell me about X' and clearly states the tool returns a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from siblings like 'resolve_entity' by noting that names are not supported.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also directs users to 'use resolve_entity first if you only have a name,' 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?

Description aligns with annotations (destructiveHint=true, idempotentHint=true) but adds minimal behavioral context beyond stating deletion. Annotations already cover the safety profile.

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 the core action and followed by usage guidance.

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

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

Adequately covers the simple delete operation with one parameter and no output schema, but could mention permanence or side effects of deletion for 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 parameter 'key' described as 'Memory key to delete'. Description adds no additional meaning beyond the schema.

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

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

The description uses a specific verb 'Delete' and resource 'memory by key', clearly distinguishing from sibling tools 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?

Explicitly states when to use (context stale, task done, clear sensitive data) and pairs with 'remember' and 'recall', providing clear guidance.

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

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

The description details the tool's behavior: fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. This adds context beyond the annotations, which already indicate read-only, idempotent, and non-destructive traits. 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 concise sentences plus a usage list. It is well-front-loaded with the key action and output format. Every sentence adds value without redundancy.

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

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

For a simple tool with 2 parameters and no output schema, the description sufficiently explains input, behavior, output format, and use cases. It covers the essential context for an AI agent to 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 schema already documents both parameters. The description adds minor value (e.g., example for url) but doesn't provide new semantics beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a llms.txt file for any URL, specifying the exact action and resource. It also highlights the benefit for AI crawlers and distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation.

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

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

The description explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor). While it doesn't compare directly to siblings, the scenarios are clear. It could be improved by stating when not to use it, but it's generally helpful.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns the caller's subscriptions and lists the fields, providing useful context beyond annotations without contradiction.

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

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

The description is three sentences, front-loaded with the main purpose, and each sentence adds value. No redundant or verbose phrasing.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the return fields, caller scope, and usage context. It could mention pagination or ordering but is generally complete.

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

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

The input schema has full coverage (100%) for one parameter. The description does not add new information about the parameter but reinforces its effect by mentioning 'active subscriptions' and the inclusion of cancelled via the flag.

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 'List the caller's active subscriptions' and specifies return fields, making the purpose explicit. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing.

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 advises when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implicitly contrasts with subscribing and unsubscribing.

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 no safety hints beyond all-false flags, so the description carries the burden and excels: it discloses rate limiting ('5 per identifier per day'), the free/no-quota nature, the claim_token behavior for anonymous filing, and the daily digest processing. No contradiction with annotations; the description adds substantial behavioral context.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then systematically covers exclusions, workflow, rate limits, and policy. No filler or redundant rewording of the schema; the structure is logical and dense.

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

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

With no output schema, the description must explain return values and it does: anonymous filing returns a claim_token that can be later passed back to read resolution status. It covers the full feedback lifecycle, rate limits, quota exemption, and reporting guidelines—complete for a tool of this complexity.

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

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

Schema coverage is 100% and each parameter is already described well. The description adds workflow-level semantics beyond the schema: it explains how claim_token is used to read follow-up status, and clarifies the expected message content ('in terms of Pipeworx tools/packs'). This goes beyond the baseline, though the schema already handles the core parameter meanings.

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

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

The description states a clear verb ('Tell the Pipeworx team') and resource ('Pipeworx feedback') with specific use cases (bug, feature/data_gap, praise). It explicitly distinguishes this tool from any other MCP server's feedback mechanism, making its scope unambiguous even without sibling overlap.

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 (wrong data, missing tool, praise) and when-not-to-use (feedback for other MCP servers) guidance, including the alternative action ('file it with that server instead'). Also advises against pasting end-user prompts and explains the claim-token return flow, leaving no ambiguity about usage context.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds significant context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). This exceeds what annotations offer and helps the agent understand side effects and freshness.

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 but uses a few bullet-like enumerations in prose. It is front-loaded with the key outputs. Could be slightly tighter, but essentially 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 tool with one optional parameter, no output schema, and rich annotations, the description covers purpose, usage, behavior, and caching completely. No gaps identified.

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 enum for window. The description adds meaning by explaining that shorter windows surface 'what's hot' and longer windows show 'steady-state demand', which is valuable for parameter selection beyond the schema's enum descriptions.

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

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

The description clearly specifies the verb 'Returns' and the resource: 'top tools, top packs, and total call volume over a recent window'. It distinguishes from siblings by focusing on aggregated trending data, not individual queries.

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

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

The description explicitly lists three concrete use cases (discovering hot data, confirming canonical choice, checking alignment). While it does not state when not to use, the use cases provide strong guidance. No alternative tools are named, but the context of siblings implies differentiation.

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, openWorld), description details scanning scope (~200 markets), calculation methods (partition sum, Jaccard threshold), filtering (placeholders), and fill check behavior. 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 long but well-structured, with clear separation of modes, filters, and response. Every sentence adds value, though some redundancy could be trimmed. Front-loads the core action and parameters.

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

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

Despite no output schema, description thoroughly explains response fields (opportunities, partition_check, fill_check). Covers edge cases like placeholder filtering, low similarity, and book depth checks. Adequate 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?

With 100% schema coverage and short schema descriptions, the tool description adds substantial meaning: explains event slug format, topic as seed question, recommended usage, and behavioral differences between modes (e.g., cross-event catches patterns single-event misses).

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', using specific verbs and resources. It distinguishes itself from sibling tools like polymarket_edges or polymarket_fill_risk by focusing on arbitrage detection.

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

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

Description explicitly covers three modes (no args for trending scan, event for specific market, topic for cross-event scan), explains when to use each, and mentions fill check to avoid non-tradeable signals. It also references polymarket_fill_risk for custom sizing, providing 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 is extremely transparent, revealing caching policy (1h at KV level), edge calculation details (slippage, Kelly), segment logic (e.g., concentrated_longshot is 'rare-by-design'), and diagnostic fields. This goes well beyond the annotations (readOnlyHint, etc.) and adds substantial behavioral context.

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

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

The description is long but well-structured with numbered sections, clear formatting, and no wasted sentences. It front-loads the purpose, then methodically explains model families, knobs, and response structure. Every sentence earns its place, making it appropriate for the tool's complexity.

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

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

Given the tool has 9 parameters, no output schema, and complex logic (three segments, diagnostics, caching), the description is remarkably complete. It covers output structure (by_segment, diagnostics), explains Fed candidates exclusion, and lists every knob's effect. The only minor omission is not explicitly listing all output fields, but it describes them in text.

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

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

While schema descriptions cover 100% of parameters, the tool description adds deep semantic meaning: it explains the purpose of each knob (e.g., min_liquidity drops 'thin-book opportunities'), the interplay between min_kelly and min_partition_leg_kelly, and how slippage affects edge. This is far beyond what the schema alone 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 that the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly distinguishes itself by being 'built for what should I bet on today' and mentions it saves agents from paging hundreds of markets, differentiating it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The tool description provides clear context on when to use it (for discovering opportunities) and explains filtering knobs like min_liquidity and max_spread_pp. It also notes that Fed candidates are excluded from ranking due to unreliable signal. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage.

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 aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) and adds value: explains history bounded by 60-day TTL, decay from daily closes (not intraday), and snapshot gaps. 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?

Well-structured with clear sections (RESPONSE, LIMITS) and front-loaded with core question. Slightly verbose but each sentence adds value.

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

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

Given no output schema, description fully explains response fields (tracked, expired, snapshot_dates) and their semantics. Covers parameters, limitations, and data sources completely.

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: default values (14 days, 1wk window), clamp range (2-30), and explains how parameters affect data retrieval. Also describes response structure, which is not 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?

Clearly states it tracks edge persistence and decay from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. Distinguishes from sibling polymarket_edges by focusing on time-series and decay rather than current edges.

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

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

Explains when to use (understanding edge age and shrinkage) and implies alternatives via sibling names. Mentions LIMITS and TTL, but could explicitly state when not to use or compare directly with polymarket_edges.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it checks live CLOB depth, returns fill details, and discloses the risk of partial fills leading to unhedged positions. No contradiction with annotations.

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

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

The description is a single paragraph of about 8 sentences, well-structured starting with purpose, then requirements, then modes and outputs. While dense, every sentence adds value. Slightly long but still clear; could be broken into sections for readability.

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

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

Given the complexity (two modes, many return fields, risk context) and absence of an output schema, the description covers all essential aspects: what the tool does, required parameters, return fields for each mode, risk warnings, and usage guidance. It is thorough and leaves no major gaps.

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

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

Schema description coverage is 100%, but the description adds significant meaning: clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. Also explains default side behavior for basket mode. This goes 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific outputs like top_of_book, vwap_fill_price, slippage_pp, and verdict, making it distinct from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to use this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Provides clear context: one of `market` or `event` is required, and warns about partial basket fills converting arb into unhedged directional position.

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 safe read. Description adds rich behavioral details: two modes, safety warnings (non-equivalent bet shapes, unrelated events, temporal misalignment), and exposes skipped cross-type/subtype counters. No contradiction with annotations.

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

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

The description is long but information-dense, front-loading the core concept and then detailing safety fields. Every sentence adds value, though it could be slightly trimmed for brevity. Still well-structured for a complex tool.

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

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

No output schema is provided, so the description must explain return values. It does so thoroughly: leg-by-leg prices, spread calculation, and safety fields (compatibility_warning, temporal_alignment, skipped counters). Given the tool's complexity, this 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 covers all 3 parameters (100% coverage). Description adds meaning beyond schema: explains the topic shortcut list, how explicit overrides work, and the relationship between modes. This provides valuable context above the schema definitions.

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 calculates the cross-venue spread between Kalshi and Polymarket for the same question, specifying two modes (topic shortcuts and explicit tickers) and distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Provides explicit usage modes and explains when the spread is meaningful via safety fields (compatibility_warning, temporal_alignment). Does not directly list alternatives but implicitly differentiates from other tools. Could be improved by stating when not to use it, but the detail is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and behavior. The description adds no extra context (e.g., authentication, rate limits, caching), so it is adequate but not additive.

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 (5 words) and front-loaded, but it sacrifices necessary detail. It is not 'appropriately sized' because it omits information about what the tool returns or how the slug is used.

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 1 parameter, annotations, and an output schema, the description is too brief. It does not specify what 'detail' includes (e.g., problem statement, constraints, examples), leaving the agent uninformed about the output.

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 0%, so the description must explain parameters. It implies 'title_slug' is the slug but does not clarify format, validation rules, or examples beyond the schema's examples. This fails to compensate for the missing schema descriptions.

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

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

The description 'Problem detail by slug.' clearly states the action (retrieve details) and resource (problem) using a specific identifier (slug). It distinguishes from siblings like 'problemset_stats' or 'daily_question' which serve different purposes.

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 guidance on when to use this tool versus alternatives such as 'problemset_stats' or 'user_recent_submissions'. The agent receives no context about tool 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 already declare readOnlyHint, idempotentHint, and non-destructive. The description adds no behavioral details beyond these annotations, but does not contradict 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 extremely concise (3 words) and front-loaded. Every word is necessary and no filler.

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

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

Given the presence of an output schema (context signal), the description need not explain return values. However, it could be slightly more descriptive about the format of 'by difficulty'.

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?

There are no parameters, so the baseline is 4. The description adds no parameter information, which is acceptable given zero parameters.

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 returns total problems grouped by difficulty. It is a specific verb+resource combination, but does not distinguish from siblings like 'problem' tool. However, the purpose is clear.

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 guidance is provided on when to use this tool versus alternatives. There is no mention of context or 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=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail ('scoped to your identifier') and the dual behavior of retrieving a specific key vs listing all keys.

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

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

Two sentences, front-loaded with action, no wasted words. Clearly 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?

Completeness is adequate given simplicity. No output schema, but retrieval tools often return simple values. Description covers scoping and pairing with siblings.

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 description. Description adds semantics about omitting key to list all, reinforcing schema. No further clarification on format or values.

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

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

States clear verb+resource: 'retrieve a value previously saved via remember, or list all saved keys'. Explicitly distinguishes from siblings 'remember' and 'forget'.

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

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

Provides context on when to use: 'look up context the agent stored earlier' with examples. Mentions pairing with remember/forget but no explicit when-not-to-use.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds critical behavior: mark_read flags events as read, affecting subsequent calls. It also notes that polls work fine, providing practical usage insight. No contradiction with annotations.

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

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

The description is concise and front-loaded with the core purpose in the first sentence. Every subsequent sentence adds value: return fields, filters, side-effect of mark_read, and alternative access method. No redundancy or 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?

For a read-only list tool with 5 optional parameters and no output schema, the description adequately explains the return structure (source, citation_uri, payload) and usage patterns. It could mention ordering or pagination, but the mention of 'most recent' and polling implies default ordering, making it fairly 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 enriches semantics by explaining the mark_read parameter's effect (flag returned events read so next call shows newer ones) and the purpose of type and since filters. This goes beyond the schema descriptions.

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

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

The description explicitly states it pulls fired events from the subscription feed, clearly identifying the verb (pull) and resource (alerts). It distinguishes the tool by specifying the return fields (source, citation_uri, payload) and filter capabilities, making its purpose unmistakable.

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

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

The description provides clear context on when to use the tool (to retrieve recent alerts) and includes an alternative method (GET endpoint for scripts/dashboards). However, it does not explicitly contrast with sibling tools or mention when not to use it, slightly limiting guidance.

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

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

Annotations already indicate safe read-only, idempotent behavior. The description adds rich detail: parallel calls to multiple sources, fallback mechanisms, soft-fail for USPTO, and return format with citation URIs. 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 comprehensive and front-loaded with examples, but it is relatively long. Every sentence is informative and well-organized into usage examples, source details, parameter guidance, and return format. Minor opportunity to trim, but still efficient.

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

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

No output schema exists, but the description adequately describes the return structure (changes grouped by source, total count, citation URIs). It covers inputs, behavior, limitations, and fallbacks, 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 meaningful context beyond the schema, such as relative shorthand formats for `since` and the ability to use ticker or CIK for `value`. It also recommends '30d' or '1m' for typical monitoring.

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

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

The description clearly states the tool provides a change feed for a company in a time window, covering SEC filings, news, and patents. It explicitly distinguishes from the sibling entity_profile tool by noting when to use each.

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 concrete query examples and guidance on when to use this tool vs entity_profile. It explains the `since` parameter formats and typical monitoring values, and clarifies fallback behavior (GDELT to GNews) and limitations (USPTO soft-fail).

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context beyond annotations: memory retention duration (24 hours for anonymous, persistent for authenticated), which aids agent decision-making.

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 tightly written with no extraneous words. Purpose is stated first, followed by usage guidance, then behavioral details. Every sentence serves a clear function.

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

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

For a simple key-value store tool with no output schema, the description covers storage mechanism, pairing with recall/forget, and persistence rules. No missing information for effective use.

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

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

While schema covers parameters fully, the description adds meaningful examples for key naming conventions ('subject_property', 'target_ticker') and value content (findings, addresses), improving clarity beyond the schema.

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

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

The description uses a specific verb ('Save') and resource ('data'), providing clear purpose and distinguishing from sibling tools like recall and forget by specifying the action of storing key-value pairs.

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 ('when you discover something worth carrying forward'), pairs with recall and forget, and clarifies persistence behavior for authenticated vs anonymous sessions.

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

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

Goes well beyond annotations by disclosing internal behavior: cascading through multiple lookup endpoints, graceful degradation (EDGAR identifiers still return if GLEIF/OpenFIGI unavailable), source labeling, and explicit `unresolved` handling. These details are not implied by the harmless annotations and add significant behavioral context.

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

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

The description is front-loaded with example queries and structured by SUPPORTED TYPES, making it easy to scan. It is fairly long but every sentence adds value; it could be tightened (e.g., trimming redundant phrasing), but no unnecessary filler is present.

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 multi-type resolver with no output schema, the description covers all critical context: supported types, input variations, cross-source resolution, unresolved handling, and fallback behavior. It provides enough detail for an agent to confidently decide and invoke, including edge cases like ISIN and non-US issuers.

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

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

Schema covers 100% of parameters, but the description enriches semantics with type-specific details: ISIN input resolves to legal entity via GLEIF mapping (covering non-US issuers), accepted formats (ticker, CIK, name), and drug returns RxCUI + ingredient + brand. This adds meaning beyond the schema's basic type/value descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists explicit example queries, supported types (company, drug), and output identifiers (CIK, LEI, FIGI, RxCUI), distinguishing it from siblings like entity_profile or compare_entities.

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

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

Provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative tools, so it lacks full when-not/alternatives coverage.

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

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

Annotations already indicate read-only, open-world, idempotent. Description adds that it probes with ai_visibility_check, ranks by score, and returns score, confidence, signal density per entity—behavioral details beyond annotations.

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

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

Three sentences, no filler. Front-loaded with main purpose and key behavior. Every sentence contributes essential information.

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

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

For a tool with 4 params and no output schema, the description covers usage scenario, behavioral flow (probe, rank, surface), and return format (ranked list with fields). 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?

Parameter schema has 100% coverage. Description adds meaningful context: first entity is 'subject for narrative', models and _apiKey usage explained. This goes beyond the schema alone.

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

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

Description uses specific verbs (compare, probe, rank) and resource (AI visibility across entities). Clearly distinguishes from sibling ai_visibility_check by stating it compares multiple entities side-by-side.

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 use case: 'competitive AI-marketing audits' with an example question. Lacks explicit when-not-to-use or alternative tools, but context strongly implies usage scenario.

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, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral context: bundlephobia first measurement can take 5-30s, partial failures degrade gracefully with sources_failed listing timeouts. This goes beyond annotations and is essential for agent decision-making.

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 relatively long but each sentence earns its place: purpose, usage, return fields, scope, and behavioral notes. Front-loaded with the composite check purpose. Could be slightly more concise but well-structured and informative.

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

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

Despite no output schema, the description enumerates return fields (summary block with specific fields, per-advisory detail, links, alternative versions). Also covers partial failure behavior and timeout. For a 2-parameter tool, this is highly complete.

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

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

Schema coverage is 100% with both parameters described. Description adds extra context: package parameter accepts scoped packages ('@types/node'), version defaults to latest. This provides slight additional value over schema.

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

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

The description clearly states the tool is a composite check for npm package evaluation, combining deps.dev and bundlephobia data. It specifies the exact use case ('should I add this npm package') and the constraints (npm ecosystem only). No sibling tool covers package analysis, so it is distinct.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides guidance on when not to use it: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives 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 discloses internal mechanics beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also explains output structure (passages with offsets and similarity scores), adding value beyond the readOnlyHint, openWorldHint, and idempotentHint annotations.

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

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

The description is a single, well-structured paragraph of five sentences. It front-loads the core purpose, then adds usage guidance and technical details. Every sentence adds value, and there is no wasted text.

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 three parameters and no output schema, the description covers input (text, query, limit), output (passages with offsets and scores), technical details (embeddings, windowing, cap), and context (pairing with sibling tool). It is fully self-contained and enables correct use.

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

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

Schema coverage is 100%, so baseline is 3. The description provides some extra context (e.g., truncation flag for text parameter), but mostly reiterates schema information. The examples in the schema for 'query' are already detailed.

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: 'Semantic search INSIDE a fetched record.' It specifies the verb 'search' and resource 'inside a fetched record', and distinguishes itself from siblings by pairing with 'ask_pipeworx_grounded' and noting when to use it instead of cramming text into the prompt.

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

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

The description explicitly says when to use the tool: 'Use when the record is too big to cram into the prompt.' It also mentions a complementary sibling tool ('ask_pipeworx_grounded'), providing clear context. However, it does not explicitly state 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 indicate idempotent and non-destructive. The description adds critical behaviors: OAuth requirement, that subscriptions persist, delivery channel-specific constraints (SMS cap, webhook signing, auto-disable after 10 failures), and that webhook secret is returned once. 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 thorough but slightly lengthy. However, it is well-structured with clear sections for types and delivery channels, uses bullet-like formatting, and front-loads the main purpose. Every sentence adds useful information.

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

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

Given 3 parameters (one enum, two objects), no output schema, but the description covers all aspects: input formatting, return value (subscription id), delivery behavior, error conditions (phone verification, auto-disable). It is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%. The description adds significant value beyond the schema: explains the meaning of sec_8k item codes, gives concrete examples for each type's params, elaborates on delivery channel validation and constraints (e.g., phone must match verified number, webhook signing details).

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

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

The description clearly states it creates a proactive monitoring subscription, names the return value (subscription id), and distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation. Supported types and delivery channels are explicitly enumerated.

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

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

Describes when to use (requires Pipeworx OAuth, anonymous not allowed), and for each type provides example parameters. Includes constraints like phone verification and SMS cap. Mentions alternatives for pulling alerts (recent_alerts, GET endpoint). Could be stronger on explicitly stating when not to use.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds context about returning 'category-bucketed example questions' and 'exact tool + argument shape' from a live catalog, which goes beyond annotation information.

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

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

The description is informative without being verbose, but could be slightly more concise. However, every sentence serves a purpose, and it front-loads the tool's role.

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

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

Given there is no output schema and the tool is an onboarding entry point, the description fully covers what the tool does, how to call it, what it returns, and when to use it. No gaps.

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

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

Schema coverage is 100%, and the description adds meaning by listing possible topic values (e.g., 'finance', 'pharma') and behavior when omitted ('full spread'). This complements 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 clearly states it is the onboarding entry point for new agents, explaining what it does (returns categorized example questions with tool+argument shapes) and distinguishes it from other tools by advising 'Use this FIRST' when unsure of Pipeworx's capabilities.

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

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

Explicitly states when to use ('when you do not yet know what Pipeworx can do') and how to pass an optional topic argument. While it doesn't list alternatives or when-not-to-use, the context makes it clear this is the starting point.

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

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

Adds significant context beyond annotations: ownership enforcement, deactivation (not deletion), and that historical events remain via recent_alerts. 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?

Two sentences, 17 words, front-loaded with main action. Every sentence adds distinct value without redundancy.

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

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

For a simple tool with one parameter and good annotations, the description fully covers the behavioral effect, ownership, and data retention, making it 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% for the single parameter 'id', with a clear description in the schema. The tool description adds no additional 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?

Clearly states it cancels a subscription by id. Distinguishes from siblings like subscribe (creates) and list_subscriptions (lists). Ownership enforcement and deactivation vs deletion are specified.

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 context for when to use (cancel own subscription) with ownership constraint. Does not explicitly mention alternatives or when not to use, but the sibling set implies context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context by specifying the GraphQL method and the exact return fields, which is valuable beyond the annotations. However, it does not mention potential rate limits or data freshness.

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

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

The description is a single, well-structured sentence that front-loads the action and resource. Every word adds value, with no redundancy or filler.

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

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

Given the tool's simplicity (one required param) and the presence of an output schema, the description is adequately complete. It covers what the tool does and what it returns. Minor improvement could mention that the profile is public.

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 0% schema description coverage, the description partially compensates by explaining that the username is for LeetCode and listing the return fields. However, it does not elaborate on the username format or constraints, leaving the agent to infer from the 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?

The description clearly states the verb 'Fetch', the resource 'LeetCode user's public profile', the input 'by username', and the method 'via GraphQL'. It also lists specific return fields, making the tool's purpose unambiguous and distinct from siblings like 'entity_profile'.

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

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

The description provides no guidance on when to use this tool versus alternatives. With 30+ sibling tools, the lack of explicit usage context or exclusions leaves the agent to infer when this is the appropriate choice.

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, so the safety profile is clear. However, the description adds no further behavioral context, such as what constitutes 'recent' or that only accepted submissions are returned.

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 short at 3 words, which is under-specification rather than efficient conciseness. It lacks front-loading of key information like the required username parameter.

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

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

Despite having an output schema, the description is too minimal to be complete. It does not clarify that the tool retrieves submissions for a specific user or how 'recent' is defined.

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

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

Input schema has 2 parameters (username, limit) with 0% schema description coverage. The description provides no explanation of these parameters, leaving the agent without guidance on required format or 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 'Recent accepted submissions' is vague and does not include a specific verb like 'list' or 'retrieve'. It reads as a label rather than a clear purpose statement, and there is no differentiation from siblings like 'user_solved' or 'recent_changes'.

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 guidance on when to use this tool vs alternatives. With siblings such as 'user_solved' and 'user_profile', the description should explain that this tool returns accepted submissions specifically, but it does not.

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 as false. The description adds that the output is counts by difficulty, but does not disclose pagination, ordering, or any side effects beyond what annotations cover. The behavioral context is minimal but not contradictory.

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 at three words. While there is no waste, the brevity sacrifices clarity. A balance between conciseness and informativeness is not achieved.

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

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

Given a single parameter and an output schema (not shown), the description still lacks completeness. It does not explain what 'solved counts' encompasses (e.g., total solved, per difficulty breakdown) or how to interpret the output. An agent would need to infer too much from the tool name alone.

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

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

The single parameter 'username' has 0% schema description coverage. The description does not explain how the username should be provided or what it represents (e.g., platform-specific username). Without schema details, the description should clarify the parameter meaning, but it fails to do so.

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 'Solved counts by difficulty.' It suggests the tool returns counts of solved items grouped by difficulty, but it does not explicitly mention that it is per user or what platform. The parameter 'username' implies user-specific data, but the description fails to clarify the resource being queried. It partially distinguishes from siblings like 'user_recent_submissions' but lacks specificity.

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 usage guidelines are provided. The description does not indicate when to use this tool versus alternatives such as 'user_profile' or 'problemset_stats'. Agents have no guidance on context or prerequisites.

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?

Despite strong annotations (readOnlyHint, etc.), the description adds crucial behavior: the two-path routing (SEC EDGAR vs grounded), the verdict values, and, importantly, the distinction between could_not_verify (check didn't happen) and unsupported (no source), with a specific warning not to show could_not_verify as evidence. This is valuable behavioral disclosure beyond the annotations.

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

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

The description is lengthy but every sentence carries important information. It leads with trigger phrases and examples, then proceeds logically through routing, output, and caller warnings. Slightly dense but not bloated; a small amount of trimming could improve structure, but it's appropriate for the tool's complexity.

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

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

Given the absence of an output schema, the description compensates by listing possible verdicts, mentioning citation and reasoning, and covering error cases. It also explains the tool's value proposition (replaces 4-6 sequential calls). This makes the description complete for an agent to use the tool effectively.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds useful semantics for tolerance_pct: it overrides the implied tolerance, defaults to a cap of 5, and suggests 1-2 for hallucination detection. This goes beyond the schema's description, so a 4 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 clearly identifies the tool's function: verifying natural-language factual claims against authoritative sources, with trigger phrases and a specific verb ('verify'). It distinguishes the tool's scope by focusing on claim verification, but it does not explicitly name sibling tools or state how it differs from similar tools like ask_pipeworx_grounded, so it falls just short of a 5.

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

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

Provides explicit 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the routing between financial and other claims, giving clear context. However, it does not mention alternative tools or when not to use this tool, so it lacks the exclusions needed for a 5.

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