Datos Ar

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

Annotations declare read-only, idempotent, non-destructive behavior. Description adds that Anthropic calls require a user-provided API key and incur direct costs, and that results include per-model details—valuable context beyond annotations.

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

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

Two concise sentences front-load the main purpose and key details. Every sentence adds value (what it does, default model, optional Anthropic, return structure, use cases). 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 no output schema, the description explains the return format (per-model fields + combined view). Covers all essential aspects: inputs, models, key requirement for Anthropic, and use cases. Slightly misses listing all output fields explicitly but sufficient.

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

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

Schema covers all 4 parameters (100%). Description adds meaning: default model, optionality of _apiKey and its purpose, and how 'context' disambiguates. Goes beyond schema by clarifying default behavior and usage flow.

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 brand visibility and scores it, using specific verbs ('probe', 'score') and resources ('LLMs', 'visibility'). It distinguishes itself from sibling tools (e.g., ask_pipeworx) by focusing on AI marketing audits rather than general Q&A.

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 the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Explains model selection (default vs. Anthropic with BYO key). Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it explains that the tool routes to sub-tools, fills arguments, returns structured answers with citation URIs, and is a fast single call. This provides useful non-obvious behavior without contradicting the annotations.

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

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

The description is longer than average, but it is well-structured: it opens with an emphatic usage directive, lists supported domains, gives concrete examples, and closes with escalation guidance. Every section earns its place; it is dense but not padded. A slight trim of the example list could improve conciseness, but the structure is effective.

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

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

There is no output schema, so the description appropriately explains the return format ('structured answer with stable pipeworx:// citation URIs'). It also covers the tool's broad scope, usage triggers, alternatives, and edge cases like breaking news routing. It does not discuss what happens on failure or ambiguity, but for a routing tool with rich annotations, the description is sufficiently 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 100% coverage: it documents 'question' and five aliases with descriptions. The description adds example queries ('current US unemployment rate', 'Apple's latest 10-K') but those are illustrative rather than necessary to understand the parameter's semantics. With schema coverage at 100%, the description contributes marginal value beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it answers factual questions by routing them to one of 5,529 tools across 1,455 sources and returns structured answers with citation URIs. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, and from web search, so the agent knows exactly what this tool does.

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

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

The description gives explicit when-to-use guidance: it says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', while also directing when to step up to alternatives such as ask_pipeworx_grounded (for verbatim evidence) or deep_research (for multi-part questions). This is a textbook example of clear usage boundaries and alternative selection.

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

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

The description discloses the experimental nature, current state (no candidate active), and that it behaves identically to ask_pipeworx right now. It explains the routing comparison purpose and confirms it is a full router, not a fallback. This goes well beyond the annotations (which already indicate read-only, idempotent, open-world strengths) by adding the live-testing context and the fact that behavior may change when a candidate is under test.

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 key identity of the tool, and each sentence carries essential information: beta status, current equivalence to stable, usage guidance, and reassurance that it is fully functional. No filler or repetition.

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

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

For a simple one-question router with no output schema, the description is complete. It covers the experimental state, usage direction, response shape alignment with ask_pipeworx, and confirms it is a complete router. The annotations supply safety and world-knowledge hints, leaving no significant gaps.

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

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

The schema description covers all 6 parameters (including aliases) with 100% coverage and clear descriptions. The tool description adds no additional parameter semantics, but the schema provides sufficient detail for an agent to understand that a single natural-language question is expected. 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 it is the 'Beta version of ask_pipeworx' and identifies it as an 'identical universal router' with the same tools and response shape. It distinguishes from siblings by specifying it has 'candidate routing improvements enabled live' and explicitly differentiates from the stable router by saying 'this currently matches ask_pipeworx exactly.'

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

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

The description gives explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also provides context about when to prefer it over the stable variant, notes that results are compared against the stable router, and clarifies that it is a fully working router ('Falls back to nothing'). No alternative tool names are given, but the sibling context makes the stable vs beta distinction clear.

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

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

The description reveals critical behaviors beyond annotations: it guarantees grounding to tool results, outputs evidence as verbatim quotes, returns structured refusal reasons on failure, and incurs an extra LLM call. This adds substantial transparency not available from readOnlyHint/idempotentHint alone.

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

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

The description is concise for the complexity it covers, packing routing, grounding, return format, usage guidance, and cost tradeoff into three sentences. Slightly dense but well-structured, front-loading the purpose. Every sentence contributes value, though it could be tightened for quick scanning.

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

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

The tool has no output schema, but the description fully documents the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and lists all possible refusal codes. This makes the behavior predictable and complete for an agent, especially given the tool's high-stakes use case.

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

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

Schema description coverage is 100%: all six parameter aliases (q, text, input, query, prompt, question) are fully documented. The description itself adds no new parameter semantics, but the schema already handles this dimension, so the baseline score is appropriate.

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

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

The description clearly states the tool's function as a 'hallucination-resistant answer mode for high-stakes reads' with a specific process (same routing as ask_pipeworx, then extraction using only tool result). It differentiates from the sibling ask_pipeworx by emphasizing the grounded, evidence-based nature and explicit refusal behavior, making it 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also gives an alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM cost, enabling clear tool selection.

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

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

Even with comprehensive annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds substantial behavioral detail: fan-out mechanism by category, low-confidence short-circuit, closed market handling, wide-spread liquidity warnings, resolution-rule risk parsing, and parent event extraction. 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 but verbose, with long paragraphs and many examples. It front-loads the purpose but includes extensive detail on classifiers, fan-out examples, response shapes, and edge cases that could be condensed. It earns its place but could be more concise without losing clarity.

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

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

Given the complexity (3 parameters, no output schema, rich behavior), the description is exceptionally complete. It covers all major aspects: input formats, fan-out logic, response structure (market, analysis, evidence, resolver contract), parent event extraction, news fallback mechanisms, safety blocking, and resolution-rule risk. Agents have full context for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the market parameter as accepting slug, URL, or question text; providing examples; detailing the depth enum behavior (quick vs thorough) and include_raw trade-offs (payload size). The parameter descriptions in the schema are already good, but the narrative adds 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?

Purpose is crystal clear: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies verb (research), resource (Polymarket bet via Pipeworx), and scope (single call, parallel fan-out). The description distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on a single bet's evidence packet and market comparison.

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

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

Explicit usage scenarios are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also provides guidance on inspecting market_match_confidence before trusting analysis, and explains blocking paths for low-confidence/closed markets. However, it does not explicitly contrast with related sibling tools or state when not to use this tool.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals that for companies it pulls latest 10-K financial data from SEC EDGAR/XBRL with proper fiscal year handling, and for drugs it pulls FAERS and FDA data. It also mentions sorted results and citation URIs.

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

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

The description is somewhat verbose with multiple trigger phrase examples. While it is front-loaded with key purpose, some sentences could be condensed without losing meaning.

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

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

Given no output schema, the description covers return format (paired data + citation URIs), sorting behavior, and entity-specific data sources. It is thorough and leaves no obvious gaps for using 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%, but the description adds significant context: explains what each 'type' retrieves, gives concrete examples for 'values', and clarifies constraints (2–5 items). This adds value beyond 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 explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs with specific data sources per type. It distinguishes itself from sibling tools like entity_profile by stating it should replace 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?

The description lists explicit trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger', etc.) and instructs to prefer over sequential single-pack lookups. However, it does not explicitly mention when not to use the tool, leaving a slight gap.

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?

Exceeds annotations by detailing return packet structure (verbatim evidence, confidence, source, fetched_at, citations), the gaps[] behavior (never invented), contradictions[] availability, hop field semantics, citation_uri fetchability, semantic excerpting, latency expectations, and account/plan constraints. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

The description is dense and information-rich; every sentence conveys necessary details about purpose, usage, behavior, and outputs. It is front-loaded with account requirements and core purpose. Slightly long and unstructured as a wall of text, but justified for a tool with many behavioral nuances; it earns its length.

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

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

For a complex tool with no output schema, the description thoroughly explains return values (findings packet fields, gaps[], contradictions[], hop, citation_uri), latency, account/plan requirements, and comparison to alternatives. It leaves no critical aspect unexplained, making it fully complete for an agent to select and invoke the tool correctly.

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

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

Schema already covers both parameters (100% coverage), but description adds meaningful behavioral semantics: depth values are explained in terms of facets and hops (quick=3, standard=5 with gap recovery, thorough=8 with iterative hop), and question description emphasizes broad/multi-part suitability. This goes beyond the schema's basic descriptions, though the schema already handles the basics.

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

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

Description clearly states the verb ('research') and resource ('Pipeworx's 1455 STRUCTURED data sources'), and explicitly distinguishes from siblings ('this is NOT open-web search', contrasts with ask_pipeworx). It conveys the exact scope and mechanism (decomposes question, routes to 5,529 tools in parallel) with concrete output details.

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 and when-not-to-use guidance: single lookups should use ask_pipeworx, breaking/current-news topics should prefer ask_pipeworx due to empty gaps. It also mentions account requirements and paid tier for thorough depth, offering clear decision rules.

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

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

Annotations declare readOnlyHint and idempotentHint as true, and destructiveHint as false, so the agent knows it is safe and repeatable. The description adds that the tool returns top-N relevant tools with names, descriptions, and full input schemas with curated examples, ready to call directly, providing behavioral context beyond annotations.

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

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

The description is fairly long but well-structured and front-loaded with purpose and use cases. It includes a list of domains which adds clarity, though slightly verbose. Every sentence serves a purpose.

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

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

Given no output schema, the description explains the return format sufficiently. Annotations cover safety. However, it lacks details on error handling or empty results, but for a search/discovery tool, this is acceptable.

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 parameters are described in the schema, including aliases for query. The description does not add significant new information about parameters; it only reiterates that query accepts aliases. 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 finds tools by describing data or task, listing specific domains. It distinguishes itself from sibling tools by being the discovery tool, as indicated by the instruction to call it FIRST.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly differentiates from 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?

Discloses parallel fan-out behavior, return fields (CIK, filings, fundamentals, patents, news, LEI), patent source sunset (soft-fail), and input constraints. Annotations (readOnlyHint, idempotentHint) are consistent; description adds rich behavioral context beyond annotations.

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

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

Description is front-loaded with example queries, followed by purpose, then detailed behavior and input constraints. Every sentence adds value, though length could be slightly reduced without losing clarity.

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

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

Despite no output schema, description thoroughly enumerates all returned fields (CIK, filings with URIs, fundamentals sorted, patents with caveat, news, LEI). It covers edge cases and future changes (patent sunset), making the tool fully understandable for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that value can be ticker or zero-padded CIK, explaining that names are not supported, and providing example formats. This goes a step 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?

Description clearly states the tool generates a comprehensive profile of a US public company using multiple data sources in one call, with specific verb 'profile' and resource 'entity'. It contrasts with sibling tools like resolve_entity and deep_research by emphasizing holistic cross-source aggregation.

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

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

Explicitly provides when-to-use examples ('Tell me about X'), advises preference over chaining single-source lookups, and specifies when not to use (names only, recommending resolve_entity instead). Alternatives are clearly named.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, reinforcing safe retry behavior. No contradiction.

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

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

Two sentences plus a pairing reference, no wasted words, front-loaded with purpose. Excellent 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?

For a simple tool with one parameter and no output schema, the description is complete given annotations. Clearly covers when and why to use.

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

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

Schema coverage is 100% with a single parameter 'key' and its description 'Memory key to delete'. Description adds no further meaning beyond schema, meeting baseline.

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

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

The description clearly states the verb 'Delete' and resource 'previously stored memory by key'. It distinguishes 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?

Provides explicit when-to-use scenarios: stale context, task done, or clearing sensitive data. Mentions pairing with 'remember' and 'recall' trades of alternatives. No explicit when-not, but context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds value by detailing the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' 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 (two sentences plus a bulleted list) with no wasted words. It front-loads the core purpose and then provides additional context. Perfect structure for quick comprehension.

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

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

Given the tool's simplicity (2 params, no output schema, straightforward behavior), the description fully covers input, process, output, and use cases. An agent can reliably decide to invoke this tool based on this information alone.

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

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

Schema coverage is 100% and both parameters are already well-described in the input schema (e.g., max_links default and max). The description mentions the URL parameter implicitly but adds no new semantic information 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?

Description starts with clear verb and resource: 'Generate a production-ready llms.txt file for any URL'. It specifies output format and lists three distinct use cases, making its purpose unambiguous and differentiating it from siblings (none of which are similar).

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 when to use the tool (e.g., 'getting a client's site indexed by AI'), providing clear contextual guidance. However, it does not mention when not to use it or cite alternative tools, so it's slightly below perfect.

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

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

Annotations already indicate read-only, idempotent, and non-destructive nature. Description adds behavioral details: aligning series on same dates, returns rows of [date, value, ...] plus metadata, and transformation options. No contradiction.

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

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

Two sentences with no wasted words. First sentence states core purpose and source of ids; second sentence details key features and output format. Front-loaded and efficient.

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

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

Covers return format and key behaviors (alignment, resampling, transformation). Mentions Spanish titles for context. Could mention metadata parameter detail but schema covers that. Complete for a data retrieval tool with no output schema.

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

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

Schema coverage is 100% with each parameter described. Description adds value by explaining that ids come from search_series, alignment behavior, and output row format. Moderate extra context beyond schema.

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

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

Description clearly states verb 'Fetch' and resource 'observations for Argentine time series'. Identifies source of ids as 'from search_series', a sibling tool, which provides context. However, it does not explicitly distinguish from other sibling tools beyond this.

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

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

Describes key usage: passing comma-separated ids for alignment, and optional parameters like collapse and representation_mode. Lacks explicit when-not-to-use guidance but effectively implies typical use case.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns specific fields (id, type, params, etc.) and that it only returns active subscriptions by default, with an optional include_inactive parameter. This supplements the 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?

Two sentences, front-loaded with purpose, no wasted words. Efficient and to the point.

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

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

Given the single optional parameter and lack of output schema, the description fully covers what the tool does, 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% with one parameter that has a clear description. The description does not add extra meaning beyond the schema; it only restates the default behavior. 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 'List the caller's active subscriptions,' specifying the verb 'list' and the resource 'subscriptions'. This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description provides context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides the agent on when to use the tool, though it does not explicitly exclude other uses or mention 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?

Despite annotations providing no safety hints (all false), the description discloses the claim_token follow-up mechanism, rate limiting ('Rate-limited to 5 per identifier per day'), and cost ('Free; doesn't count against your tool-call quota'). It also reveals that the team reads digests daily, setting expectations for response time.

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 each sentence serves a purpose—purpose, triggers, exclusions, claim_token flow, rate limits, and cost. It is front-loaded with the core purpose, and the structure is logical.

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

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

The description covers every aspect needed to use this tool correctly: when to use it, when not, how to format the message, the follow-up token, and operational constraints. With no output schema, it even explains what the return value contains (claim_token) and how to use it.

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

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

With 100% schema description coverage, the schema already explains each parameter in detail, so the description adds marginal extra meaning. It does clarify that claim_token should be passed 'with no other arguments' and advises against pasting end-user prompts, but these are usage nuances rather than parameter 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which names the verb and resource clearly. It further distinguishes from siblings like ask_pipeworx by specifying feedback categories (bug, feature, data_gap, praise).

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

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

It explicitly provides conditional triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states when NOT to use: 'if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: self-aggregating signal from CF analytics-engine, no PII, and caching (5min-1h depending on window). 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 a single paragraph with bullet points, front-loading the main output and caching info. No wasted sentences, though slightly longer than minimal. Efficient for the information conveyed.

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

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

Despite no output schema, the description hints at return fields (tools, packs, count). Caching and data source notes cover behavioral completeness. Lacks explicit return format or pagination, but acceptable for a simple trending report.

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% (1 parameter with enum and description). The description adds marginal value by explaining window tradeoffs ('shorter windows surface what's hot right now; longer windows show steady-state demand'), but baseline 3 is appropriate since the schema already documents the parameter adequately.

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 returns 'top tools, top packs, and total call volume' over configurable windows. This specific verb-resource combination distinguishes it from siblings like 'discover_tools' or 'ask_pipeworx', 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?

The description enumerates three concrete use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. It provides explicit contextual guidance without needing external references.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent. Description adds rich behavioral context: scans top ~200 markets, uses Jaccard similarity, filters placeholder slugs, checks live CLOB depth with theoretical vs realizable edge. 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?

Fairly long but well-structured with clear sections (modes, semantic anchor, partition filter, fill check). Front-loaded with purpose. Every sentence adds value, though could be slightly more concise without losing clarity.

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

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

Covers all aspects: usage, modes, filters, fill check, response structure. No output schema but description details opportunities[], partition_check, fill check fields. Refers to sibling tool for fill risk. Complete for a complex tool.

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

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

100% schema coverage, but description adds significant meaning: event accepts slugs or full URLs, topic is a seed question, and explains the behavioral difference between the two modes. Schema alone is insufficient without this 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?

Explicitly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Clearly distinguishes three modes: no args (trending scan), event (per-event partition check), topic (cross-event scanning). Differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides detailed when-to-use guidance: recommends event for specific markets, explains that cross-event mode catches patterns single-event misses, mentions semantic anchor (≥0.30 Jaccard), partition filter, and fill check. Directs users to polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate readonly and idempotent, but the description adds extensive behavioral details: caching policy (cached 1h at KV level), segment definitions, filtering knobs (min_liquidity, max_spread_pp), diagnostics for empty segments, and per-opportunity fields. No contradiction with annotations.

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

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

The description is long but well-structured with clear segmentation (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.), bullet-like formatting, and acronym explanations (e.g., GDELT, OIS/SOFR). Some redundancy (e.g., repeated mention of Fed bets) but overall effective for an agent.

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, so description fully covers return structure: top-level fields (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and knob effects. Also explains diagnostics for empty segments, ensuring users understand why results are empty.

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

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

Schema coverage is 100% (baseline 3), but the description adds rich context well beyond schema descriptions, e.g., slippage_pp explains Polymarket fee structure and typical bid/ask, min_partition_leg_kelly clarifies why min_kelly doesn't apply to partitions, and knobs like min_liquidity are explained in terms of execution impact. This significantly aids correct parameter selection.

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 the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs like 'scan' and 'return opportunities', and distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection across model-driven, structural arbitrage, and concentrated longshot segments.

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

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

Frames the tool as 'what should I bet on today' and notes agents discover opportunities without paging hundreds of markets. Mentions Fed bets exclusion and knob usage but lacks explicit when-not-to-use comparisons with siblings. The context is clear enough for an agent to decide when to invoke it.

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

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

Annotations declare the tool read-only, idempotent, and non-destructive. The description adds substantial behavioral details beyond annotations, including response format (tracked, expired, snapshot_dates), data limitations (60-day TTL, snapshot gaps), and computation method (daily closes, not intraday). 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 relatively long but well-structured, with the purpose first, followed by response fields and limitations. Every sentence adds value, but it could be slightly more concise, especially in the response breakdown.

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, the description thoroughly explains the return values (tracked[], expired[], snapshot_dates[]) and their significance. It also covers data gaps, limits (60-day TTL), and computation details, making the tool fully understandable for an AI agent.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reiterates defaults (14 days, '1wk' window) and provides context like clamp range, but does not add new semantic information beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge duration and uses comparative reasoning to differentiate from related tools like polymarket_edges.

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

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

The description gives context for when to use the tool (e.g., comparing fresh vs. old wide edges) and explains the output structure, but does not explicitly state when not to use it or mention alternative tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds operational details like walking the order book ladder, returning a verdict (clean|degraded|cannot_fill), and warning about forced directional risk. No contradiction with annotations.

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

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

The description is somewhat lengthy but well-structured with block-capitalized sections (REQUIRES, SINGLE-MARKET, BASKET). Every sentence adds useful information. It is front-loaded with the core purpose. Minor redundancy could be trimmed, but overall efficient.

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

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

Given 4 parameters, no output schema, and good annotations, the description covers all necessary aspects: modes, parameter details, return fields (top_of_book, vwap_fill_price, verdict, etc.), and warnings about thin books and forced directional risk. It is comprehensive for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the dual interpretation of 'side' (single-market vs basket), the size_usd interpretation (settlement notional for baskets), and default values. It provides context beyond the schema, such as the clamp range (10–1,000,000).

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool (trades above $500 and arb signals).

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

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

The description provides explicit guidance on when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (partial fills lead to unhedged positions). While it doesn't explicitly state when not to use, the guidance is clear and actionable.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by explaining the underlying mechanics: venues price outcomes differently due to participant pools, and the tool indicates when bet shapes are not equivalent. It details response structure, safety fields, compatibility_warning cases, temporal alignment, and skipped counters.

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 serves a purpose: introducing the concept, explaining modes, describing response fields, and covering edge cases. It is front-loaded with the core purpose. Slight verbosity is justified given the tool's complexity.

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

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

Despite lacking an output schema, the description completely explains the response structure (leg-by-leg prices, spread, top_spreads_pp, safety fields). It covers all important aspects: two modes, compatibility_warning scenarios, temporal alignment, and skipped comparison counters. No gaps remain for a complex multi-venue spread tool.

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

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

Schema coverage is 100%, but the description adds value by explaining the two modes, how topic maps events, and that explicit parameters override topic mapping. It provides actual example values for parameters (e.g., 'fed', 'btc', 'KXFED-26OCT', 'fed-decision-in-june-825'), which aids understanding beyond the schema alone.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools like polymarket_arbitrage. It specifies two distinct modes (topic with pre-mapped macros and explicit event tickers) and provides concrete examples.

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

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

The description explicitly explains when to use each mode (topic for 10 pre-mapped shortcuts, explicit for custom pairings). It warns that most topic shortcuts return compatibility warnings, guiding the agent to not expect tradeable spreads from topic mode. It also details when to check safety fields like compatibility_warning and temporal_alignment.

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, and destructiveHint=false. The description adds context about scoping to an identifier and pairing with remember/forget. No contradictions, and it covers behavioral aspects beyond the annotations.

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

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

The description is concise at three sentences, front-loading the primary action and immediately following with usage context. 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 retrieval tool with full schema coverage and comprehensive annotations, the description completes the picture with use-case examples and scoping details. While no output schema is provided, the return behavior (value or list of keys) is adequately implied.

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

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

Schema coverage is 100% for the single 'key' parameter. The description adds nuance: 'omit to list all keys' and 'Memory key to retrieve', which provides meaningful guidance beyond the schema 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 that recall retrieves a value saved via remember, or lists all keys if no key argument is provided. It distinguishes itself from siblings like remember (save) and forget (delete) with explicit pairing language.

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

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

The description explains when to use the tool: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairs with remember and forget, but does not explicitly state when NOT to use it or provide alternatives beyond implied 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?

The annotation declares readOnlyHint=true, implying no side effects, but the description mentions that setting mark_read:true flags events as read, which modifies state. This is a direct contradiction between the description and the annotations, warranting a score of 1.

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

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

The description is concise with five sentences, each adding value (purpose, return structure, filtering, mutation, alternative endpoint). No superfluous information, though it could be slightly more terse.

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 5 optional parameters and no output schema, the description covers return fields, filtering, and the mark_read side effect. However, it does not mention the 'limit' parameter or its default, nor pagination behavior, leaving some gaps for an agent.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds meaningful context: it gives an example for 'type' (sec_8k), clarifies the format for 'since' (ISO timestamp), and explains the effect of 'mark_read'. However, it omits the 'unread_only' parameter, so it's not fully comprehensive.

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 pulls fired events from the subscription feed and lists what each event carries. It is specific enough, though it does not explicitly distinguish from sibling tools like 'recent_changes' or 'subscribe', but its purpose is distinct enough to be 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?

The description explains how to filter (by type and since), the effect of mark_read, and notes that polling works fine. It also provides an alternative REST endpoint for scripts, offering some guidance on when to use alternatives, though it doesn't explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds rich behavioral details: fan-out to multiple sources, fallback logic (GDELT→GNews), USPTO soft-fail, and return format. 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 a single dense paragraph that front-loads with example queries. Every sentence adds value, but it could be slightly more structured. Overall efficient given the complexity.

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

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

Despite no output schema, the description explains the return format (changes[] grouped by source, total_changes, pipeworx URIs). It covers parameters, behavior, limitations, and alternatives comprehensively.

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

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

Schema coverage is 100% so baseline is 3. The description adds examples for 'since' (ISO date and relative shorthand) and clarifies 'type' is only company, adding modest value beyond the schema.

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

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

The description explicitly states the tool provides a change feed for a company in a time window, detailing specific sources and return structure. It distinguishes from sibling tool 'entity_profile' which handles static profiles.

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

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

The description gives clear when-to-use examples ('What's new with X', 'latest on Y') and explicitly advises using 'entity_profile' for static profile needs, providing clear 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?

Discloses key-value storage scoped by identifier, with persistence differences for authenticated vs anonymous users. Annotations already indicate idempotent and non-destructive; description adds useful context without contradiction.

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

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

Three sentences with no wasted words. Purpose is front-loaded, followed by usage conditions and pairing hints. Highly efficient.

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

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

For a simple write tool with no output schema, the description covers purpose, usage, behavior, and pairing. No gaps given the tool's complexity and schema coverage.

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

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

Schema covers both parameters with descriptions; description adds context on valid key naming conventions and value types (findings, addresses, etc.), adding meaning beyond schema.

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

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

Description clearly states the tool saves data for reuse across sessions, with specific examples like tickers and user preferences. It distinguishes from sibling tools recall and forget, making the purpose unambiguous.

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

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

Explicitly advises use when discovering valuable information to avoid re-lookup. Mentions pairing with recall/forget, but 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes beyond these by disclosing detailed behavior: identifier provenance (source-labelled), explicit unresolved list rather than omission, graceful degradation when GLEIF/OpenFIGI are unavailable, and internal cascading endpoint logic. No contradiction with annotations.

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

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

The description is dense but each sentence adds useful information: example queries, primary function, supported types with detailed outputs, failure behavior, and efficiency rationale. It is appropriately sized for a complex tool, though the long paragraph could be broken into shorter sections for easier scanning. It is front-loaded with the core purpose.

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

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

Given the complexity (two entity types, multiple data sources, fallback behavior) and the absence of an output schema, the description thoroughly covers inputs, outputs, data provenance, unresolved handling, and graceful degradation. It also positions the tool within a workflow, making it complete for an agent to understand what to expect.

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 values and examples for both parameters. The description adds value by explaining what each type returns (e.g., company returns CIK/ticker/LEI/FIGI, drug returns RxCUI/ingredient/brand) and input flexibility (ticker, CIK, name; brand or generic). While the schema already lists parameters, the description enriches interpretation of the 'value' parameter through practical examples and output semantics.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers (CIK, ticker, LEI, FIGI, RxCUI) that other tools require. It uses a specific verb and resource, and distinguishes itself from sibling tools by positioning it as the 'FIRST' step for name-to-ID lookup, with clear differentiation between company and drug types.

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

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

The description provides explicit usage context: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups, guiding when to choose this tool. However, it doesn't explicitly name alternatives or when-not-to-use scenarios, leaving a small gap in full usage guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density. This exceeds annotation coverage and provides a clear behavioral model.

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

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

Three sentences, each essential: core function, internal process and output, and a use-case example. No wasted words; information is front-loaded and scannable.

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 (4 params, no output schema) and rich annotations, the description adequately explains the output shape (ranked list with score, confidence, signal density) and internal call to ai_visibility_check. It does not cover edge cases or error handling, but is sufficient for correct usage.

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

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

Schema coverage is 100% with good descriptions, but the description adds extra meaning: treating the first entity as the 'subject' and the rest as competitors, defaulting models to workers-ai, and disambiguation of common names via context. This adds value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb 'Compare' and resource 'AI visibility'. It explicitly distinguishes itself from the sibling 'ai_visibility_check' by describing a multi-entity ranking process, making the purpose highly specific and differentiated.

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

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

The description mentions the tool is useful for competitive AI-marketing audits and implies using ai_visibility_check for single entities, but it does not explicitly list when not to use it or name alternatives like 'compare_entities'. The guidance is clear but lacks exclusions or direct sibling comparisons.

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

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

Description adds significant behavioral context beyond annotations: explains composite nature, potential timeout on bundlephobia first measurement (5-30s), graceful degradation with sources_failed field, and return structure (summary, advisories, links, alternatives). No contradiction with annotations.

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

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

The description is dense but well-organized. It front-loads the core purpose and then details behavior, edge cases, and return structure. Every sentence adds value, though it could be slightly tightened without loss of clarity.

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

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

For a composite tool with multiple external sources and potential partial failures, the description covers all necessary context: ecosystem, fallback, timing, return content, and graceful degradation. No output schema exists, but the description adequately describes the return shape.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by mentioning scoped packages (e.g., '@types/node') are accepted, which is not in schema. This reinforces understanding, but the schema already covers version defaulting. Overall adds moderate extra meaning.

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

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

The description clearly states the tool's composite function: checking npm packages across deps.dev and bundlephobia for safety, popularity, size, etc. It distinguishes from sibling tools like scan_competitor_ai_presence by specifying the domain (npm ecosystem) and the one-call composite nature.

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 an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies ecosystem boundaries (NPM only in v1, fallback to deps.dev for others) and handles partial failures gracefully.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that it returns specific fields and queries a known endpoint (apis.datos.gob.ar). It does not detail pagination behavior (offset, limit) or mention that openWorldHint means results may change, but the schema covers pagination parameters. 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 three sentences with no wasted words. It front-loads the main purpose, then provides practical examples, and ends with what is returned. Every sentence adds 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?

Given the tool is a simple keyword search with one required parameter and no output schema, the description covers input (keyword, optional filters), output (returned fields), and follow-up action (use ids with get_series). It could mention default limit or pagination behavior, but the schema examples help. Overall, it's sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100% (all parameters described). The description adds value with examples (q values like 'inflacion', limit=20, dataset_theme='precios') and clarifies that q should be in Spanish. This goes beyond the schema parameter descriptions to give real-world usage context.

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

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

The description clearly states the tool searches Argentina's national time-series catalog for series matching a keyword (verb 'Search', resource 'catalog'). It provides example Spanish keywords and specifies return fields (ids, titles, units, frequency, date coverage, dataset, source). It distinguishes from sibling tool get_series by noting that returned ids are used with get_series.

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

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

The description explains when to use the tool (to find series by keyword) and gives example queries in Spanish. It implies an indirect alternative (get_series for full data) but lacks explicit when-not-to-use guidance or comparison with other search tools among siblings. However, the context is clear enough for most agents to determine appropriateness.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag. No contradiction with annotations.

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

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

Two concise paragraphs, front-loaded with key information. Every sentence adds value, 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 full schema coverage, good annotations, and no output schema, the description thoroughly explains return values (passages with offsets and scores), embedding model, windowing, truncation, and pairing with sibling. Complete for correct invocation.

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

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

Schema coverage is 100%, so baseline 3. The description adds useful context for 'text' (max length) and 'query' (example queries), but does not add meaning beyond schema for 'limit'. Value added but not substantial.

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 semantic search inside a fetched record. It specifies the verb ('search_within'), the resource (a fetched record's text), and distinguishes from siblings by explaining it is for records too large for the prompt and pairs with ask_pipeworx_grounded.

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt') and provides an alternative usage pattern with ask_pipeworx_grounded, giving clear guidance on when not to use this tool.

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

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

The description discloses significant behavioral details beyond annotations: requires OAuth account, returns subscription ID, details on subscription types and delivery channels, SMS cap (10/day), webhook HMAC signing, and auto-disable after 10 failures. Annotations (idempotentHint=true) are not contradicted.

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 main purpose and then details types and delivery channels efficiently. It is somewhat lengthy but each sentence provides essential information. Minor improvement could be a list format for types.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers many aspects. However, it does not describe the full return structure beyond 'Returns the new subscription id'. An agent might need to know if it returns a full object, creating a minor gap in 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%, and the description adds meaningful context for each parameter: examples for 'params' per type, explanation of 'items' codes, and delivery channel specifics. This adds value beyond the schema alone, though the schema already has solid 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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id', using a specific verb and resource. It distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by detailing the creation aspect.

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

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

The description explains when to use the tool (to set up proactive monitoring) and prerequisites (Pipeworx OAuth account). It notes that anonymous users cannot persist subscriptions, but does not explicitly exclude cases where polling via 'recent_alerts' might be preferable. Sibling tools are listed but no direct alternatives mentioned.

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, openWorldHint=true, destructiveHint=false. The description adds context about what the tool returns (category-bucketed example questions) and that it does not modify state, complementing the annotations effectively.

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 and front-loaded with the purpose. It includes trigger phrases, output description, and usage instructions in a logical order. However, listing all categories in both the description and the schema is slightly redundant, making it a bit longer than necessary.

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

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

Given no output schema, the description adequately explains the return value (category-bucketed example questions with tool+argument shapes). It covers the single optional parameter, usage scenarios, and provides enough context for an agent to use it 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 coverage is 100% with a clear description of the 'topic' parameter and its possible values. The description reiterates this but adds the context that omitting the parameter gives a full spread and including it focuses on a category. This adds some value but the schema already covers the core meaning.

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

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

The description clearly states this is the onboarding entry point for new agents, returns category-bucketed example questions, and explicitly distinguishes itself from sibling tools like ask_pipeworx, entity_profile, and compare_entities by directing the agent to use this tool first.

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 this tool ('when you do not yet know what Pipeworx can do for you'), what it returns (example questions with exact tool+argument shapes), and how to use it (with no arguments for full spread or with topic for focus). Also suggests it should be used before other meta-tools.

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

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

Annotations already indicate non-destructive (destructiveHint=false) and idempotent (idempotentHint=true). Description adds that the row is 'deactivated (not deleted)' and points to 'recent_alerts' for historical events, providing extra behavioral context beyond annotations.

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

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

Two sentences, no redundancy. First sentence gives action and input, second adds ownership and side effects. Highly efficient.

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

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

For a simple single-param tool with no output schema, the description covers purpose, ownership constraint, and behavioral impact (deactivation vs deletion). References related tool 'recent_alerts' 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?

Parameter 'id' is fully described in schema (type, format, origin). Description merely restates 'by id'. With 100% schema coverage, baseline 3 is appropriate; no additional semantics added.

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 states 'Cancel a subscription by id' – a clear verb+resource pair. The phrase 'by id' specifies the input. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states 'Ownership is enforced — you can only cancel your own subscriptions', which guides when to use. Does not mention alternatives, but the context of ownership is clear enough.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description adds critical behavioral nuance: could_not_verify explicitly means the check did not happen and must not be treated as evidence, and unsupported means no source coverage. This is essential for correct agent interpretation.

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 ~200 words, front-loaded with query examples and core purpose. It is longer than minimal but every sentence adds value—routing logic, verdict list, and caveats—so it is appropriately sized for its complexity.

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

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

With no output schema, the description covers the return structure (verdict, actual value with citation, reasoning) and explains the two non-obvious verdict states. It provides sufficient context for the agent to use the tool correctly, including the efficiency benefit over sequential calls.

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?

Both parameters (claim, tolerance_pct) are fully described in the input schema with examples and constraints. The tool description itself does not discuss parameters, so baseline 3 applies for schema coverage of 100%.

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

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

The description explicitly identifies the tool as 'natural-language claim verification against authoritative sources' and provides concrete query examples ('Is it true that…', 'fact check'), clearly distinguishing it from sibling research tools.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two processing paths (SEC EDGAR vs grounded pipeline). It does not explicitly name alternatives or when-not-to-use, but the strong use-case statement provides clear context.

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