Gong

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that it calls external APIs (Workers AI free, Anthropic with user's key), explains `_apiKey` passes straight through to Anthropic, and details the return structure (`{score, confidence, signals, raw_response}` per model plus combined view). No contradictions with annotations.

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

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

The description is a single paragraph that front-loads the core purpose and is well-structured. While it is concise, it could be slightly tighter by removing redundant phrasing like 'per model' (already in schema). However, it is not verbose.

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 return values (per-model object and combined view). It covers all parameters and use cases. However, it lacks information about error handling or rate limits, which would improve completeness for a tool that calls external APIs.

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, but the description adds significant value: it notes the default model (Workers AI Llama-3.3-70b free), clarifies that `_apiKey` is optional and only required for Anthropic, and explains that `context` helps disambiguate common names. This goes beyond schema alone.

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

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

The description uses a specific verb 'probe' and resource 'LLMs', clearly stating it scores visibility (0-100) per model. It is distinct from sibling tools like 'ask_pipeworx' or 'deep_research' by focusing on multi-model visibility rather than single queries or research.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains when to use optional parameters like `_apiKey` for Anthropic. However, it does not explicitly state when not to use this tool or provide alternatives, which would make it a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds valuable behavioral context: it routes across 5,529 tools, returns stable citation URIs, works on every tier, and is a single fast call. It also clarifies that answers are structured and that it can handle current/historical data. 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 relatively long but highly structured: it leads with the most important directive, then explains the routing behavior, gives trigger phrases and examples, and ends with sibling comparisons. Every sentence adds useful information, though some redundancy exists ('START HERE' repeated with 'default entry point'). It earns a high score for effective front-loading and organization.

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

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

Despite having no output schema, the description explains what the tool returns ('structured answer with stable pipeworx:// citation URIs'). It covers use cases, exclusions, alternatives, and example queries. For a complex routing tool with many aliases and broad scope, the description is comprehensive and leaves no major gaps.

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

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

Schema coverage is 100% and all six parameters are aliases for the free-text question, with the schema already describing them. The description goes beyond the schema by providing concrete example queries and specifying the domain scope ('SEC filings, FDA drug data, FRED/BLS...'), which helps the agent understand what kinds of questions are acceptable. This justifies a score slightly above the baseline of 3.

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

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

The description clearly states the tool's function: it routes factual questions to the appropriate underlying tools and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases, and identifies itself as the default entry point.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for a long list of domains, 'START HERE for most questions', and 'Step up only when needed' with specific alternatives (ask_pipeworx_grounded, deep_research). It also provides example queries and notes limitations (works on every tier, one fast call).

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 strong annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses beta status, live candidate routing improvements, the absence of an active candidate, and confirms 'this IS a full working router, just the experimental edge.' 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 four sentences, each adding value: what the beta is, current state, usage instruction, and reliability reassurance. It is well-front-loaded and has no filler, making it efficient for an agent to process.

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 and rich annotations, the description covers all essential context: beta nature, parity with the stable router, usage purpose, and response shape. No output schema exists, but the statement 'same response shape' as ask_pipeworx sufficiently communicates expected results.

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

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

With 100% schema description coverage, the schema itself fully documents the 'question' parameter and all five aliases. The description adds only 'same arguments' context, which is redundant with the schema and doesn't provide additional parameter-level meaning. 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 identifies the tool as a beta version of ask_pipeworx, a universal router with 5,529 tools, same arguments, and same response shape. It distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_grounded by emphasizing the experimental edge and current parity with the stable router.

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

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

The description explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies current behavior ('currently matches ask_pipeworx exactly') and notes that results are compared against the stable router, giving clear selection criteria.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses detailed behavioral traits: it returns a structured object with evidence verbatim quote, confidence, refusal reasons covering failure modes ('not_in_source', 'no_tool_match', 'tool_error', etc.), and that it uses ONLY the tool result. It also mentions the extra LLM call cost. These go well beyond what annotations convey.

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

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

The description is information-dense but well-organized: it opens with the core purpose, explains the internal routing and extraction, details the success and failure return structures, gives concrete use cases, and ends with a cost comparison. Every sentence earns its place; no filler or redundant restating of the tool name.

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

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

Given the tool's complexity (routing across 5,529 tools, high-stakes usage) and the absence of an output schema, the description provides a comprehensive picture: return fields, refusal reasons, performance cost, and indicative use cases. It fully explains the behavioral contract, making it complete for an agent to decide and invoke the tool correctly.

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

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

Schema coverage is 100% with the 'question' parameter described and aliases listed. The description does not add parameter-level detail, but the schema fully documents the single required parameter. Baseline 3 is appropriate since the schema handles parameter semantics 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 begins with 'Hallucination-resistant answer mode for high-stakes reads,' clearly identifying the tool's function as a grounded, extractive answer generator. It explicitly contrasts with 'ask_pipeworx' by describing the routing and extraction behavior, distinguishing it from that sibling. The verb 'extracts' and the resource (tool results) make the purpose specific and non-tautological.

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

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

The description gives explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists examples. It also provides an exclusion: 'prefer ask_pipeworx for casual lookups,' and justifies with cost ('Costs one extra LLM call'). This clearly differentiates when to use this tool versus the alternative ask_pipeworx.

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?

Extensive disclosure beyond annotations: resolution process, fan-out specifics, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, spread warnings, and cancellation rule parsing. 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?

While highly informative, the description is lengthy and dense, listing many edge cases and details. It could be more structured with subheadings or bullet points. However, the complexity justifies some verbosity.

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?

Comprehensive coverage of all aspects: input, processing, output shapes, edge cases (low confidence, closed markets, wide spreads), and cancellation rules. Without an output schema, the description fully explains return values and behaviors.

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%. Description adds meaning beyond schema by explaining input types for market, depth options with default, and include_raw with guidance on when to use true. Provides examples for market parameter.

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

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

Clearly states the tool researches Polymarket bets by pulling Pipeworx data. Specifies input types (slug, URL, question text) and use cases ('should I bet on X', etc.). Distinct from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on evidence gathering and market-model 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?

Provides explicit scenarios for use and examples of fan-out. Describes when results are blocked (low-confidence match, closed markets). No explicit when-not-to-use, but the context and warnings adequately guide proper usage.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of pipeworx:// citation URIs. This goes well beyond what annotations provide.

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

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

The description is a single paragraph but well-structured: first listing usage examples, then explaining data sources for each type, sorting, and return format. Every sentence adds value. Could be slightly more structured with bullet points, but is appropriately sized and front-loaded with examples.

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

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

Despite no output schema, the description explains return format (paired data + citation URIs). It covers two entity types with distinct data sources, fiscal-year handling, and sorting behavior. Minor gap: no mention of pagination or rate limits, but for a read-only comparison tool, this is sufficient.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning by specifying that type='company' pulls revenue, net income, cash, and debt from SEC EDGAR, while type='drug' pulls FAERS adverse-event counts, FDA approvals, and trial counts. It also explains values format (tickers/CIKs for company, names for drug) and constraints (2-5 items).

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

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

The description starts with concrete query examples ('Compare X and Y', 'X vs Y', etc.) that immediately clarify the tool's purpose. It specifies side-by-side comparison of 2-5 entities in one call, clearly distinguishing it from sequential lookups. The verb 'compare' and resource 'entities' are explicit.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides clear context for when to use this tool (comparison queries) and quantifies the benefit ('Replaces 8-15 sequential lookups'). While there is no explicit 'when not to use', the positive guidance is strong.

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

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

Annotations already indicate readOnly/openWorld/idempotent, but the description adds essential behavioral context: account requirement, structured-data-only orientation (not open-web), latency expectations (15-60s, up to 90s for thorough), output structure (findings packet with gaps[], contradictions[]), the promise to never invent data, semantic excerpting of large records, and citation_uri semantics. This goes far beyond the structured fields.

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?

Though lengthy, the description front-loads the most critical caveat (account requirement) and every subsequent sentence adds operational value—routing logic, output format, comparisons with alternatives, depth-specific behavior, latency, and citation guarantees. Non-redundant and well-organized for a complex tool.

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

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

With no output schema, the description fully covers what the caller should expect: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, explicit gaps[], contradictions[] (for certain depths), hop field, and semantic excerpting. It also covers edge cases like topics outside the structured catalog and large-record handling, making the tool highly self-contained.

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

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

Schema coverage is 100% (both params documented), but the description enriches both parameters: depth is expanded with detailed behavior differences (quick/standard/thorough, gap recovery, contradictory scan, paid tier), and question is explained as accepting broad multi-part natural language that will be decomposed. This adds semantic value beyond the plain 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 identifies the tool as a grounded multi-source research tool across 1,455 structured data sources, decomposed into facets and routed to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and from siblings like ask_pipeworx by stating it is NOT open-web search and handles broad/multi-part questions in one call.

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

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

Provides explicit guidance: best for broad/multi-part questions over structured data, use ask_pipeworx for single lookups or breaking/current news topics, and warns about account requirements plus a fallback alternative (ask_pipeworx) if not signed in. It even explains which depth to choose based on the need for gap recovery and contradiction scanning.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the return format (full schemas, curated examples, ready to call) without contradicting 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 purpose and use cases, then explains return format and usage advice. Slightly lengthy but well-structured and each sentence adds value.

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

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

Even without an output schema, the description fully explains what is returned (names, descriptions, full schemas with examples, ready to call). It also covers when 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?

Schema coverage is 100% with descriptions for all parameters. The description adds context with examples and emphasizes natural language usage, going beyond schema details.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and distinguishes itself by being the first call to see options. It is specific and actionable.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools'. Does not explicitly exclude other scenarios but provides strong context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable context: it fans out across multiple APIs, returns specific fields, notes patent search soft-fails until reactivated, and explains fallback mechanisms. No contradictions; description enhances transparency beyond annotations.

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

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

Description is a single dense paragraph but front-loaded with example queries and bold emphasis on preference. Every sentence serves a purpose, but it could benefit from bullet points or clearer separation of details. It's efficient but slightly overwhelming; could be more structured.

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

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

Even without an output schema, the description fully explains what the tool returns: CIK, company_name, recent_filings with URIs, fundamentals, patents, news, LEI. It also addresses limitations (patent sunset, name unavailability). Provides a complete picture for the agent to understand capabilities and constraints.

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

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

Schema coverage is 100% with descriptions for both type and value. Description adds practical nuance: only 'company' type supported, value examples (AAPL vs 0000320193), and explicit statement that names are not accepted. While schema already covers basics, description provides actionable usage hints.

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

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

Description clearly states it provides a full cross-source profile of a US public company in one call. It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. Name and examples ('Tell me about X'/AAPL) make purpose unmistakable. Differentiates from siblings like compare_entities and resolve_entity.

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

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

Explicitly advises to prefer this tool over chaining single-pack lookups for holistic views. States that names are not supported and recommends using resolve_entity first. Provides clear input constraints (ticker or zero-padded CIK). No ambiguity on when or when not to use.

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

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

Annotations already mark destructiveHint true; description confirms deletion by key. Adds context like pairing with remember/recall but doesn't detail error handling or idempotency behavior beyond annotations.

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

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

Two sentences, no fluff, front-loaded with purpose and usage guidelines.

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

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

Complete for the tool's simplicity: single parameter, no output schema. Description covers purpose, usage, and related tools.

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

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

Schema coverage is 100% and the parameter description is clear; the tool description adds no additional meaning beyond the schema.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource, and distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use the tool (context stale, task done, clear sensitive data) and mentions paired tools, guiding proper selection.

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

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

Annotations (readOnlyHint, destructiveHint false, idempotentHint) are fully consistent with description's 'Fetches the page, extracts...' and non-destructive nature. Description adds details about output format and placement 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?

Single, well-organized paragraph: purpose first, then process, output details, use cases. Every sentence adds value with no redundancy.

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

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

Adequately covers purpose, process, output format, and use cases for a tool with only two parameters. Could mention error handling or redirect behavior, but sufficient for typical usage.

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

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

Schema description coverage is 100%. Description adds example values for url and clarifies default/max for max_links, enriching the schema's descriptions slightly.

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 an llms.txt file, details the process (fetch, extract, emit), and specifies the output format and location. Distinguishes from siblings through unique functionality.

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

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

Explicitly lists three use cases (indexing client sites, drafting own, auditing competitors), providing clear context for when to use. No exclusion criteria but sufficient for the tool's simplicity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context by specifying the returned data (participants, duration, metadata, metrics, moments), which helps the agent understand the tool's output 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?

Single sentence, front-loaded with the action and resource, then lists returns. No extraneous content. Highly efficient.

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

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

Given the tool has one parameter and an output schema, the description covers key return fields. It does not address error cases or edge conditions, but the context signals indicate output schema exists, reducing the burden. Slight gap in completeness, but adequate.

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

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

Schema coverage is 100% with a clear description for callId ('The Gong call ID'). The description adds no additional parameter semantics beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

Description uses specific verb 'Get' and resource 'full details for a specific call by ID'. It lists what is returned (participants, duration, metadata, metrics, moments), clearly distinguishing it from siblings like gong_get_transcript (transcript only) and gong_search_calls (list/search).

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

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

The description implies use when needing comprehensive call details, but does not explicitly state when not to use or mention alternatives. It lacks guidance on differentiating from gong_get_transcript or gong_list_calls, leaving the agent to infer.

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 as true, and destructiveHint as false, indicating a safe, idempotent read operation. The description adds value by specifying the content of the transcript (speaker names, timestamps, dialogue), which complements the annotations. 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 consists of two sentences: one defining the function and result, the other providing usage guidance. No extraneous information. Every sentence is purposeful and earns its place.

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

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

Given the simplicity (one required parameter, full schema coverage, rich annotations, and presence of an output schema), the description sufficiently covers what an agent needs: what the tool does, what it returns, and when to use it. The mention of using after gong_get_call provides workflow context.

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

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

Schema coverage is 100%; the single parameter callId has a schema description 'The Gong call ID'. The tool description does not add any additional semantic meaning to the parameter beyond what is already in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the purpose: retrieve the full conversation transcript with speaker names, timestamps, and dialogue. It differentiates from sibling tools like gong_get_call and gong_list_calls by specifying the exact resource and the context of use after gong_get_call.

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

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

The description provides explicit usage context: 'Use after gong_get_call to analyze specific conversations.' This guides the agent on the step-by-step workflow. It doesn't explicitly state when not to use it or list alternatives, but the given context is sufficient for appropriate invocation.

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

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

Annotations already declare safe, non-destructive, idempotent behavior. The description adds useful context about pagination and return fields, which goes beyond annotations. No contradictions.

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

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

Two concise sentences, front-loaded with the main action and key features. Every word adds value, with no unnecessary details.

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

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

Covers core functionality, optional filters, pagination, and return fields. Output schema exists, so return details are sufficient. Lacks potential limitations or default behavior, but overall complete for the tool's simplicity.

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

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

Schema coverage is 100%, so the schema fully documents parameters. The description reinforces optional date filtering and pagination but does not add new semantic details beyond the schema's descriptions.

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

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

The description clearly states the action (list), resource (recorded calls), scope (from workspace), and key features (date filtering, pagination, return fields). It is specific and helps distinguish from siblings like gong_get_call and gong_search_calls.

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

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

The description implies usage through its examples but provides no explicit guidance on when to use this tool versus alternatives like gong_search_calls. It lacks instructions on prerequisites or exclusions.

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

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

The description adds behavioral context beyond annotations by specifying returned fields and the 'all users' scope. Annotations already provide read-only and idempotent hints, so the description complements them well.

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

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

The description is extremely concise, using one sentence for the main action and a second brief sentence for return fields. No wasted words, and the core purpose is front-loaded.

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

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

For a simple tool with no parameters and an output schema, the description is sufficiently complete. It specifies scope and return fields; annotations cover safety behavior.

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

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

The tool has zero parameters, so the schema provides full coverage. Per rubric, 0 params yields a baseline of 4; the description does not add parameter semantics but none are needed.

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 (List) and resource (users) with scope ('in your workspace'), and enumerates the returned fields. It distinguishes from sibling tools like gong_list_calls which deal with calls.

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

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

No explicit guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The context with sibling tools is implicit but not stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds that results are ranked by relevance, but no further behavioral context.

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

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

Single sentence that is front-loaded with the action and includes an example. 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?

Simple tool with one parameter; description covers input and output (returns calls ranked by relevance). Output schema handles details.

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 high, but description adds examples of keywords ('pricing', 'objection', 'budget'), which aids understanding beyond the schema's parameter 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?

Clearly states the tool searches calls by keyword or phrase, with specific examples. Distinguishes from sibling Gong tools like 'gong_get_call' and 'gong_list_calls'.

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

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

Implies use for keyword search but provides no explicit guidance on when to use versus alternatives or when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety profile is clear. Description adds that only active subscriptions are returned by default, and lists the returned fields. No contradictions.

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

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

Two short sentences. First covers purpose and output fields, second gives usage context. No superfluous words.

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

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

For a simple list tool with one optional parameter and no output schema, the description adequately covers purpose and return fields. Missing mention of pagination or limits, but acceptable given low 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 describes the only parameter 'include_inactive' with full detail. Description does not add new information beyond what the schema provides (baseline 3 for 100% schema coverage).

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Identifies return fields and distinguishes from sibling tools like subscribe and unsubscribe by mentioning reviewing before adding or finding id to cancel.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This ties to siblings and indicates when to use. Does not specify when not to use, but the context is sufficient for a simple list 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?

With all annotations set to false, the description carries the full burden and delivers richly. It discloses rate limits ('Rate-limited to 5 per identifier per day'), the claim_token workflow for follow-ups, the fact that it's free and doesn't count against quota, and that the team reads digests daily. It also explains what happens when filing without an account. 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 long but well-organized: purpose first, then usage conditions, exclusions, workflow, and practical caveats. Every sentence contributes meaningful information (rate limits, token flow, quota impact), though a couple of phrases like 'The team reads digests daily' could be trimmed without losing core guidance. It earns a 4 for efficiency relative to the amount of necessary context.

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 parameters, nested object, enum, no output schema), the description covers all essential aspects: purpose, usage boundaries, alternative modes (claim_token vs. new feedback), rate limits, and expected outcomes. It even specifies what the response will contain (status and what changed). The lack of an output schema is compensated by the description's explicit mention of return values.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the claim_token alternative usage ('Filing without an account returns a claim_token; pass it back later...'), giving guidance for the message field ('don't paste the end-user's prompt'), and clarifying that context is optional. This elevates it above the baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb (tell/send) and resource (Pipeworx team), and differentiates itself from siblings by focusing on feedback about the tools themselves rather than using the tools. The explicit categories (bug, feature/data_gap, praise) further clarify scope.

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

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

Provides explicit when-to-use guidance: '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 gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' The 'Not sure?' fallback adds practical decision support.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: self-aggregating signal, derived from CF analytics-engine, no PII, caching behavior (5min-1h). 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 and well-structured, with a clear opening sentence followed by bullet-pointed use cases. Every sentence adds value; no fluff.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description covers return values, caching, and use cases adequately. It provides sufficient detail for an agent to decide when to invoke this 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?

The only parameter 'window' has an enum in the schema, and the description adds semantic value by explaining that shorter windows highlight current trends while longer windows show steady-state demand. Schema coverage is 100%, but description enhances 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 purpose: returning top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources, and distinguishes from siblings like 'discover_tools' by focusing on what other AI agents are calling.

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

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

The description provides three explicit use cases (e.g., discovering hot data sources, confirming canonical choice). While it doesn't explicitly state when not to use, the context and sibling tool list (e.g., 'discover_tools') offer guidance.

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

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

Annotations already indicate read-only, non-destructive behavior. The description adds extensive behavioral context: semantic anchor with Jaccard similarity, partition filter, fill check against live CLOB depth, and response structure. 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 well-structured with clear sections and front-loaded purpose. While somewhat verbose with details like 'SEMANTIC ANCHOR:' and 'FILL CHECK:', every sentence adds value given the tool's complexity. Could be slightly more concise but 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?

Given no output schema, the description thoroughly explains return values, including fields like gap_pp, suggested_trade, reasoning, and partition_check details. It also covers edge cases (skipped_low_similarity, placeholder filter) and provides actionable warnings. Complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value beyond schema by explaining the operational details of each parameter (e.g., what 'event' does: walks child markets, checks ordering, partition_check) and the output format. Slightly above baseline.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It differentiates three modes (no args, event, topic) with specific use cases, distinguishing it from sibling tools.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. It also gives recommendations and warnings, such as not trading when realizable_edge_pp <= 0 and mentions an alternative tool (polymarket_fill_risk).

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 extensively details the three model families, response structure, caching behavior (1h KV keyed on knobs), and diagnostics for empty results. This far exceeds the annotations which only indicate read-only, idempotent, and non-destructive behavior.

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

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

The description is very long and dense, but is structured with clear sections (model families, knobs, response top-level). Every sentence adds value, though brevity could be improved.

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

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

Given no output schema, the description fully explains the response structure (by_segment, fed_candidates, diagnostics) and all parameters are well-documented in the schema. Annotations cover safety. The tool is adequately specified 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?

All 9 parameters have thorough descriptions in the schema, so the baseline is 3. The description adds context about 'TRADEABLE-EDGE KNOBS' but does not significantly enhance parameter meaning beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the use case 'what should I bet on today' and distinguishes from sibling tools that focus on specific aspects like arbitrage or fill risk.

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

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

The description provides context that this tool discovers opportunities without paging through hundreds of markets, implying it's for initial discovery. It lists knobs for filtering, but does not explicitly contrast with sibling tools or 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, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral detail: explains the returned structure (tracked with time-series, trend, decay; expired with lifespan; snapshot dates), notes that gaps indicate no scan, and discloses limits (60-day TTL, decay from daily closes). There is 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 front-loaded with purpose, then details in a structured format: a question-answer, args, response fields (tracked, expired, snapshot_dates), and limitations. It is somewhat lengthy but every sentence adds information. Minor room for tightening, but overall well-organized.

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

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

The tool has only two parameters and no output schema, yet the description thoroughly explains the output structure (tracked objects with time-series, trends, decay; expired objects with lifespan; snapshot dates) and limitations (TTL, daily vs. intraday). It leaves no major gaps for an agent to understand tool usage and expected results.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well (lookback days with clamp, window family with options). The description adds defaults and some context (e.g., window as 'snapshot family'), but this mostly duplicates the schema. Hence, the description does not add substantial value beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?', uses a specific verb (tracks, answers), and distinguishes itself from sibling tools like 'polymarket_edges' by focusing on persistence and decay rather than just edge data.

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

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

The description implies when to use: when needing to understand edge persistence (fresh vs. old wide edges). It provides context about decay numbers being from daily closes (not intraday), which helps set expectations. However, it does not explicitly state when not to use or list alternative tools, though siblings are available in the context.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) are consistent with description, which confirms a read-only check. Description adds context about partial fill risks ('unhedged directional position') and return metrics, providing rich behavioral detail 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 long but well-structured with clear sections (single-market vs basket) and each sentence provides critical guidance. Slightly verbose due to detailed enumeration of return fields, but efficient given complexity.

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

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

Despite no output schema, description comprehensively lists all return fields for both modes, explains risks (thin books, forced directional legs), and provides context for interpreting results. Covers all aspects needed for an agent to correctly use this complex tool.

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

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

Schema has 100% coverage, but description adds significant value: defaults (size_usd=1000), interpretation differences between modes (size interpreted as spend vs target proceeds for single-market; settlement notional for basket), side auto-detection logic for basket. This clarifies parameter usage beyond 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?

Description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It lists specific return fields, making the purpose highly specific and distinct from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and provides rationale (theoretical overround not capturable, partial fills create directional risk). No ambiguity about alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), description adds extensive behavioral details: the spread calculation, safety fields (compatibility_warning, temporal_alignment, skipped cross counters), and explanation of why spreads may be meaningless. It discloses limitations and edge cases comprehensively.

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

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

The description is well-structured with clear sections for modes, response, and safety fields. It is appropriately front-loaded with the core purpose. While detailed, it does not waste words, though it could be slightly condensed without losing information.

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

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

Given the tool's complexity (cross-venue comparison with safety checks) and lack of output schema, the description thoroughly covers what the response contains (leg-by-leg prices, matched spreads, safety fields) and when each field is relevant. It addresses temporal alignment and compatibility, making the tool's behavior predictable.

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

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

With 100% schema coverage, the description adds significant meaning: it explains the topic mapping, how explicit parameters override, and provides example values. The description frames parameters in the context of the tool's logic, going beyond simple type/format information.

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

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

Description clearly states it computes 'cross-venue spread between Kalshi and Polymarket for the same resolving question'. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison. Two modes are explicitly described, and the purpose is specific and 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?

Description explains two modes (topic shortcuts and explicit pairing) and warns that most pre-mapped topics return compatibility warnings. It provides context on when spreads are valid (temporal alignment) and when they are not (compatibility_warning). However, it does not explicitly state when to avoid this tool in favor of alternatives.

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

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

Annotations already mark readOnlyHint, idempotentHint, and destructiveHint, so the description carries a low burden. It adds valuable behavioral context: listing keys when omitted, scoping to an identifier, and pairing with remember/forget. No contradictions with annotations.

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

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

Two sentences packed with essential information: main action, usage guidance, scope, and pairing. No fluff; every sentence earns its place. The most critical action is front-loaded.

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

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

Given the tool's simplicity (one optional parameter, strong annotations, no output schema needed), the description covers all necessary aspects: what it does, when to use it, parameter behavior, and implications (scope). 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%, but the description adds meaning beyond the schema: it explains that omitting the key lists all saved keys. This directly aids the agent in understanding the parameter's optionality and effect.

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

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

The description uses specific verbs ('Retrieve', 'list') and resources ('value previously saved via remember', 'all saved keys'). It clearly distinguishes itself from sibling tools like 'remember' and 'forget' by stating its retrieval function and the option to list keys.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier...without re-deriving it from scratch.' It also mentions pairing with 'remember' and 'forget', providing context for its place among siblings. However, it does not explicitly state when not to use or provide alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. Description adds detail: mark_read side-effect (flags events read), and that polling works fine. 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?

Four concise sentences, each serving a purpose: action, return fields, filter arguments, mark_read behavior, and alternative access. 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?

No output schema, but description lists returned fields (source, citation_uri, raw payload). Parameters fully covered. Annotations cover safety. Adequate for 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% (5 params described). Description adds context: explains 'type' filters subscription type, 'since' uses ISO timestamp, 'mark_read' flag and effect, 'limit' default and range. Adds value beyond schema.

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

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

Description begins with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It distinguishes from siblings like list_subscriptions by focusing on alert content and providing specific return fields.

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

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

States polling works fine and mentions an external endpoint for scripts/dashboards, but does not explicitly exclude cases where other tools (e.g., search_within) might be preferable. Clear context for when to use, but lacks when-not 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?

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description details fan-out behavior to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and return structure (changes grouped by source, total_changes, citation URIs). No contradictions with annotations.

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

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

Though a single long paragraph (~100 words), every sentence adds necessary detail. Front-loaded with user-facing example queries, then operational details. Could be more concise with bullet points, but not wasteful.

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 covers multiple data sources, fallback logic, soft-fail status, return structure, and parameter formats. It fully informs an agent about what to expect and how to use the tool correctly.

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

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

Schema coverage is 100%, so schema already documents parameters. The description adds practical value: example formats for 'since' and a typical monitoring suggestion ('30d' or '1m'), plus clarifying 'value' accepts ticker or CIK. This extra context raises it above baseline 3.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with explicit query examples ('What's new with X') and a list of data sources (SEC, GDELT, USPTO). It distinguishes itself from the sibling 'entity_profile' tool.

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

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

Provides explicit guidance: 'Use entity_profile instead when you want the static profile... regardless of window.' This tells the agent when to use this tool versus the alternative, along with implied usage for recent changes.

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

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

Annotations indicate idempotent and non-destructive. Description adds scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous. No contradictions. Could mention overwrite behavior but still strong.

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

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

Four sentences efficiently packed: purpose, usage scenario, scoping/persistence, pairing. No fluff, front-loaded.

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

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

For a simple write-only tool with two params, description covers all necessary context: purpose, when, scoping, retention, and companion tools. No output schema needed.

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

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

Schema covers both params with descriptions (100% coverage). Description adds naming conventions and examples (e.g., 'subject_property'). Adds value beyond schema. Baseline 3, plus 1 for 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?

Description uses clear verb 'Save' and resource 'data as key-value pairs'. Distinguishes from siblings recall and forget, and specifies scope across sessions.

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 discovering something worth carrying forward to avoid repeated lookups. Notes pairing with recall/forget. No alternative tools given but sufficient for single-purpose 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 mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit listing of unresolved identifiers under an 'unresolved' field, source-labeling of every identifier, and internal cascading through multiple endpoints. These details exceed the annotation hints and help the agent anticipate edge cases.

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

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

The description is long but densely informative, with a clear front-loaded set of example queries and a well-structured 'SUPPORTED TYPES' breakdown. Though some redundancy exists (e.g., repeating accepted inputs), every section provides necessary context for a complex tool, so it remains efficient for its 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?

With no output schema, the description compensates by detailing the returned identifiers for each type, including source labels, unresolved fields, and fallback behavior. It thoroughly covers both entity types and explains the internal cascading lookups, making it complete for an agent to understand what will happen.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining input formats for each type (e.g., company accepts ticker, CIK, or name) and outlining the expected output identifiers, but the schema descriptions already include examples. The added value is moderate, justifying a 4.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, using a specific verb and resource. It distinguishes itself from siblings by showing example queries and noting that it supplies IDs other tools require, separating it from entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear when-to-use directive and example user intents. However, it does not name specific alternative tools or when-not-to-use scenarios, only implying this is the first step in a broader workflow.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral context: it 'probes each entity with ai_visibility_check', 'ranks by score, surfaces which is most/least recognized', and returns 'ranked list with score, confidence, signal density per entity'. This goes beyond annotations without contradicting them.

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

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

The description is two sentences long plus a brief parenthetical example. It is front-loaded with the core purpose, then specifies the method (probes + ranks), output structure, and usage context. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (multi-entity comparison, sub-calls to ai_visibility_check) and no output schema, the description provides complete information: what it does, how it works (probes each entity), output shape (ranked list with score, confidence, signal density), and use case. Annotations cover safety and idempotency. No gaps for effective agent use.

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

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

Schema coverage is 100% with 4 parameters. The description adds meaning by explaining that the first entity in 'entities' is treated as the 'subject for narrative', and clarifies that 'models' supports 'workers-ai (free default)' and 'anthropic (requires _apiKey)'. This supplements the schema's descriptions effectively.

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 'Compare AI visibility across multiple entities side-by-side' and uses a specific verb ('Compare', 'Probes') and resource ('AI visibility'). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the method (probes each with ai_visibility_check, ranks by score).

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 frames the tool as 'Useful for competitive AI-marketing audits' and gives a concrete example ('does Claude know about us as well as our competitors?'). It implies when to use this over ai_visibility_check (comparing multiple entities vs. single entity), though it does not explicitly list exclusions or alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses that bundlephobia's first measurement can take 5-30s and that sources_failed will list timeouts, with graceful degradation. 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 well-structured, front-loading the core purpose and then providing details. Slightly long but every sentence adds value.

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

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

Despite lacking an output schema, the description thoroughly lists return fields, explains partial failures, and covers scope and usage. Fully adequate for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions. The tool description adds no additional info beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, combining deps.dev and bundlephobia data. It distinguishes itself from siblings by specifying npm ecosystem and the one-call 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 tells when to use (agent asks 'is X safe/popular/small') and when not (PyPI/Maven/Cargo/Go fall under deps.dev:version directly). Also mentions partial failure behavior.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior; the description adds substantial detail: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and character offsets in results. No contradictions; transparency is high.

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

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

The description is well-structured with a clear, front-loaded first sentence. It covers purpose, usage, and technical details in about 6 sentences without redundancy. Slightly verbose in some areas (e.g., repeating the pairing advice), 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 the tool's complexity (3 parameters, no output schema) and rich annotations, the description fully covers what the tool does, how it works (embedding details, truncation, offsets), and when it should be used. It also addresses integration with a sibling tool. No gaps detected.

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 does not add significantly beyond the schema: it reiterates the max chars for text, default and range for limit, and the nature of the query. No additional depth or nuance is provided.

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 resource (the text parameter) and action (return top-N passages with character offsets and similarity scores). It distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching the whole document.

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

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

The description explicitly advises using the tool when the record is too large for the prompt and highlights the context-saving benefit. It also mentions a complementary tool (ask_pipeworx_grounded). Lacks explicit when-not-to-use guidance, but context is clear enough.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: OAuth requirement, delivery channel specifics (email, SMS with 10/day cap, webhook HMAC signing and auto-disable after 10 failures). It also lists type-specific parameter examples, all of which go 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 front-loaded with the core purpose and prerequisites. It is dense but well-organized: purpose, requirement, type examples, delivery channels. Some details (e.g., exact HMAC formula) could be abbreviated, but the structure is logical and no sentence is wasted.

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

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

Given the complexity (3 parameters, nested objects, enums, no output schema), the description covers all aspects: purpose, prerequisites, all subscription types with concrete examples, delivery channel options and constraints (verification, caps, webhook auto-disable). The return value ('new subscription id') is stated. No gaps remain for an agent to call the tool incorrectly.

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 schema descriptions are minimal ('Subscription type.', 'Type-specific filter.'). The tool description provides detailed examples for each enum type (sec_8k with items, fred_series with series_id) and explains delivery sub-parameters (SMS must match verified phone, webhook signing secret returned once). This adds substantial meaning beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb-resource pair (create subscription) and distinguishes the tool from siblings like list_subscriptions 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?

Description notes prerequisite (Pipeworx OAuth account) and lists supported types and delivery channels, implying when to use. However, it does not explicitly contrast with alternative tools (e.g., use list_subscriptions to view existing ones, unsubscribe to remove). The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating query. The description adds valuable detail about the output structure: it returns category-bucketed example questions with exactly how to call other tools. There is no contradiction with annotations.

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

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

The description is moderately long but well-structured. It begins with example user queries, then defines the output, the parameter usage, and finally the recommended use case. Every sentence adds essential information, though a minor trim could improve flow. It earns a 4 for efficiency and 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 tool's simplicity (one optional parameter, no output schema), the description thoroughly covers what the tool returns, how to use it, and when to use it. It explains the nine categories and the fact that results are drawn from a live catalog of thousands of tools. No additional information is needed for effective use.

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

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

Schema coverage is 100% for the single optional parameter 'topic', with a description of allowed values. The description adds context by explaining that omitting the parameter gives a full cross-category spread, while passing a topic focuses on that category. It also lists example topic values, reinforcing 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 starts with concrete user intents ('What can I ask Pipeworx?', 'give me ideas') and immediately positions the tool as 'the onboarding entry point'. It specifies the unique output: 'category-bucketed example questions ... each with the exact tool + argument shape'. This clearly distinguishes it from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains how to narrow results with the optional 'topic' parameter. While it doesn't list explicit alternatives, the context implies that after using this tool, users should move to specific tools like 'ask_pipeworx' or 'entity_profile'.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false; description adds that rows are 'deactivated (not deleted)' and historical events remain available. This explains the soft-delete behavior beyond annotations, with no contradictions.

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

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

Two sentences: one for action, one for side-effect and constraint. No redundant phrasing, front-loaded with the primary 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?

For a simple mutation with one parameter and no output schema, the description covers the essential: what it does, who can use it, and the effect (soft delete). References to 'recent_alerts' provide helpful linkage.

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% (single 'id' parameter with description 'Subscription id (uuid) returned by subscribe'). Description merely references 'id' without adding new semantic detail, meeting baseline but not exceeding.

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 action ('Cancel a subscription by id') and resource ('subscription'). Explicitly distinguishes from sibling tools like 'subscribe' (which creates) and 'list_subscriptions' (which lists).

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

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

States ownership enforcement ('only cancel your own subscriptions'), providing clear context. Does not explicitly contrast with siblings for when-not-to-use, but the restriction is clear and the purpose is well-defined.

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 this as read-only, open-world, and idempotent, but the description adds significant behavioral context beyond that: it details the two routing paths, returns a verdict enumeration, explains the nuanced difference between could_not_verify and unsupported (with verification_error extension), and clarifies that could_not_verify is not evidence for or against the claim. This is rich, actionable transparency that the annotations alone don't provide.

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

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

The description is longer than typical but every sentence carries load: examples, use-case, routing, return contract, and an explicit caller warning. It is front-loaded with the most important info (what it does and when to use) and well-structured with the IMPORTANT caveat separated. Minor redundancy (e.g., 'grounded pipeline' vs 'grounded or structured') but overall efficient.

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

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

Despite having no output schema, the description fully specifies the return contract (verdict enum, actual value with citation, reasoning) and the error semantics. It also anticipates a critical caller mistake (treating could_not_verify as evidence) and defines unsupported. Given the tool's complexity, this description is remarkably complete without being bloated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds extra meaning: it provides realistic examples for claim and explains that tolerance_pct overrides the wording-implied tolerance and suggests 1–2 for hallucination detection. This goes beyond the schema descriptions and helps the agent choose appropriate values.

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

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

The description clearly identifies the tool as a fact-checker for natural-language claims, provides explicit example phrasings, and distinguishes it from sibling tools by specifying the two distinct verification paths (SEC EDGAR for financial claims, grounded pipeline for others). The verb "validate" and the resource "claim" are specific, and the description clearly differentiates this from general Q&A 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?

It explicitly states "Use whenever the agent needs to check whether something a user said is factually correct," which gives clear intent. It also explains that it replaces 4–6 sequential calls, implying when to use it instead of manual pipeline composition. However, it doesn't explicitly mention when NOT to use it or name alternative sibling tools for non-claim queries, so it falls short of the top score.

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