Rawg

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds return format details (score, confidence, signals, raw_response) and notes that Anthropic calls are billed directly by Anthropic, complementing the annotations well.

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

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

Three sentences: first states action and output, second explains defaults/key usage, third lists use cases. No redundancy, front-loaded with purpose.

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

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

Given 4 params, no output schema, and no nesting, the description covers return format (per-model + combined) and key behaviors. No missing critical info for a probe tool.

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

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

Schema coverage is 100%; description adds value by clarifying defaults (Workers AI free, Anthropic requires key) and explaining the context parameter's role in disambiguation, going beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for visibility scores (0-100) per model, distinguishing it from siblings like entity_profile or scan_competitor_ai_presence by focusing on AI visibility rather than general entity info or competitive scanning.

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

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

The description specifies default model, when to use _apiKey for Anthropic, and lists use cases (AI-marketing audits, brand checks). It lacks explicit 'when not to use' or contrasts with siblings, but provides sufficient context for appropriate use.

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

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

The annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. Beyond that, the description adds useful behavioral context: the tool routes questions, fills arguments automatically, returns structured answers with stable citation URIs, and is described as a fast single call. There is no contradiction with the annotations.

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

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

The description is lengthy but front-loaded with the primary directive, followed by use cases, examples, and alternative tool routing. Each section serves a distinct purpose, and the structure makes it easy to scan for when-to-use and when-not-to-use guidance. Minor repetition around deep research conditions prevents a perfect score.

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

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

For a tool with no output schema, the description explains the return format, citation behavior, scope of sources, and limitations. It also gives enough examples and alternative routing to make invocation safe and correct. An agent has all the context needed to select and call this tool without further clarification.

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

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

The input schema already covers the question parameter and its aliases with 100% description coverage. The description adds meaningful usage guidance beyond the schema by instructing the agent to ask only one thing at a time and by providing a variety of example question shapes. It does not need to repeat the alias details already in the schema.

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

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

The description clearly states the tool's purpose: ask a natural-language factual question and route it to one of 5,798 tools across 1,517 verified sources, returning a structured answer with pipeworx:// citation URIs. It also distinguishes the tool from siblings such as deep_research and ask_pipeworx_grounded, so an agent can tell them apart without opening schemas.

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

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

The description explicitly says to prefer this tool over web search for current/historical factual data, lists trigger phrases and concrete examples, and gives clear conditions for when to use deep_research, ask_pipeworx_grounded, bet_research, or plain web search. It also states what the tool is NOT designed for, such as why/explain multi-hop reasoning or citation-free questions.

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 read-only/idempotent annotations, the description reveals the experimental live-candidate mechanism, the current inactive-candidate state, the specific date of the last retirement, and the fact that this is a full working router with no fallback. This is valuable behavioral context an agent needs to assess risk and expectations.

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

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

The description is dense but efficient: each sentence contributes new information about beta status, current state, usage policy, or fallback behavior. It is front-loaded with the most important identity statement and contains no filler or repetition.

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

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

The definition covers operational state, usage intent, safety profile, and parameter schema well. The only gap is that the response shape is referenced by comparison to ask_pipeworx rather than described directly, which is a minor omission given that the tool is explicitly identical to a known sibling.

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 every parameter is already documented as an alias for 'question.' The description adds no extra parameter-level semantics beyond saying 'same arguments,' so the schema carries the full explanatory burden and the baseline 3 applies.

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 over 5,798 tools, and explicitly distinguishes it from the stable ask_pipeworx by describing its experimental routing candidates. This makes its purpose and relationship to siblings 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?

It explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing,' naming both the stable alternative and the condition for selecting this variant. It also explains that results are compared against the stable router, which tells the agent what this tool is for and why it matters.

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

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

Despite readOnly/idempotent annotations already covering safety, the description adds materially: exact success return shape, refusal payload with enumerated refusal_reason values, evidence as verbatim quote, and refusal-on-uncertainty behavior. It also warns about the extra LLM call, which annotations cannot express. 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 first sentence front-loads the core purpose, and every subsequent clause adds concrete value: routing behavior, return/refusal contract, use cases, and cost comparison. It is longer than two sentences but carries a dense payload with no redundant filler.

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

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

Given there is no output schema, the description compensates by specifying the full success and refusal response shapes. It covers when to use, how it behaves, what it returns, and what it costs relative to its sibling, so an agent has everything needed to invoke and interpret it correctly.

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

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

Schema description coverage is 100%: the schema fully documents 'question' and lists all aliases. The description adds no parameter-level detail, so baseline 3 is appropriate; it does not need to repeat what the schema already provides.

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

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

Description states a specific verb+mode: 'Hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It names the sibling 'ask_pipeworx' and marks this as the grounded variant, so an agent can distinguish it from ask_pipeworx and ask_pipeworx_beta.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' This gives both positive and negative selection criteria, and the cost tradeoff ('Costs one extra LLM call') reinforces the choice.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description richly details behavioral traits: market resolution, classification, parallel fan-outs, response shapes, resolver contract, parent event extraction, news fallback handling, safety short-circuits for low-confidence and closed markets, tradeability warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is comprehensive but quite long (over 2000 characters). It front-loads the core purpose and uses section keywords (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) to structure dense technical details. While every sentence adds value, the length may reduce scannability for an AI agent, earning a mid-range score.

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 lack of output schema, the description provides exhaustive detail about response fields (market, analysis, evidence, parent event, news fields), edge cases (low-confidence matches, closed markets, wide spreads), and resolution risk (cancellation rules). It covers all necessary context for an agent to interpret and safely use the tool.

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

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

Schema description coverage is 100%, and the description adds extra context: examples of market input (slug, URL, question text), explanation of depth with examples 'quick' vs 'thorough', and the purpose of include_raw with its typical size implications. This adds value beyond the schema while the schema already covers parameter types and defaults.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and action (pull Pipeworx data). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on data research for bet evaluation, not arbitrage or edge tracking.

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

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

The description explicitly states usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-outs per category and warns about checking market match confidence and cancellation rules. While it does not explicitly state when not to use it, the alternative sibling tools imply other use cases, and the cautionary notes guide appropriate 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 indicate readOnly, idempotent, not destructive. Description adds fiscal year handling (AAPL Sep, NVDA Jan), data sources (EDGAR/XBRL, FAERS/FDA), and return format (paired data + citation URIs). No contradictions.

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

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

Single block but dense with examples and specifics. Front-loaded with query patterns. Could use slight structuring (e.g., broken by type) but remains 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 full schema coverage and annotations, description explains return format and sorting. Omits error handling or edge cases, but sufficient for typical 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%. Description clarifies values for each type (tickers/CIKs for companies, drug names for drugs) and specifies min/max items and sorting behavior. Adds meaning beyond enum labels.

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

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

Description states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' with concrete examples like 'compare X and Y', and differentiates from 'sequential single-pack lookups'. It specifies data sources for each type and mentions sorting by primary metric.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides query patterns (head-to-head, rank, vs). Does not explicitly list when to avoid, but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior, and the description adds substantial detail beyond that: decomposition into facets, parallel routing, gap reporting, contradictions scanning, citation URIs that are always fetchable, semantic excerpting, latency, and authentication requirements. No annotation contradiction exists.

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

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

The description is dense but every sentence carries decision-relevant information: the account gate and sibling alternative are front-loaded, then output structure, depth behavior, latency, and edge-case handling follow in a logical order. It is long because the tool is complex, not because of repetition or filler.

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

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

There is no output schema, so the description carries the full burden of explaining return behavior; it does so thoroughly with fields, gaps[], contradictions[], hop, citation_uri, and fetchability guarantees. It also covers authentication, cost, alternatives, depth tiers, and expected latency, making it complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds helpful meaning by explaining the behavioral effect of depth values — standard re-angles gaps, thorough chases leads from the first pass — and by framing the question parameter as naturally multi-part, which aids correct invocation.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources in one call. It explicitly contrasts with open-web search and with ask_pipeworx, making sibling differentiation immediate 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?

Usage guidance is explicit: use this for broad/multi-part questions over structured data, and use ask_pipeworx for single lookups or when not signed in. It also names the paid tier requirement for depth:thorough, so an agent can route decisions correctly.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds beyond that: it discloses the output format ('returns top-N most relevant tools with names, descriptions, and full input schemas with curated examples') and that results are 'ready to call directly, no second schema lookup needed,' which is valuable behavioral context.

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

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

The description is front-loaded with the core purpose. It lists many domains, which is helpful but slightly verbose. Every sentence adds value; there is no fluff. It could be trimmed slightly, but it is well-structured and informative.

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

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

Given the complexity (6 parameters, no output schema), the description fully compensates by explaining the output: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It also addresses the tool's role in the overall workflow. No gaps remain.

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 mentions 'query' and 'task' but does not add semantics beyond what the schema provides for each parameter. However, it clarifies that multiple aliases exist, which is a minor addition. No significant extra meaning.

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

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

The description begins with 'Find tools by describing the data or task,' clearly identifying the tool's purpose. It lists numerous specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by emphasizing 'Call this FIRST when you have many tools' and that it returns tools ready to call—differences from direct answer tools like deep_research or search_within.

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: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It provides examples but does not explicitly mention when not to use it or alternatives, though the 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 read-only, open-world, and idempotent behavior, and the description adds substantial context: parallel fanout across sources, sources_used/sources_failed semantics, empty sections meaning genuine 'no data,' expected empty fda_products for small-molecule-only companies, GDELT→GNews fallback, and private companies returning resolved:false with a notes line. This goes well beyond the structured 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 information-dense and front-loaded with examples and the core purpose, but it quickly becomes a sprawling, semicolon-heavy paragraph. Breaking the return categories and source behaviors into a structured list would substantially improve scannability. Every entry has value, but the structural delivery hurts readability.

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

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

For a complex multi-source tool with only two parameters and no output schema, the description is remarkably complete. It covers accepted input forms, resolution edge cases, expected empty results, per-source data categories, fallback behavior, and even URIs for filings. An agent has enough context to invoke the tool correctly and interpret non-standard 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?

The input schema already covers the two parameters at 100% and documents ticker/CIK/name formats. The description adds extra semantic value by explaining name resolution via SEC EDGAR, the 'resolved_from/resolved_to' behavior when a name is passed, and how private companies are handled. It goes above the schema baseline without being redundant.

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

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

The description opens with concrete user phrasings and immediately identifies the tool as a 'full cross-source profile of a US public company in ONE parallel call.' It names the resources fanned out across and the types of returned data, clearly distinguishing it from chained single-pack lookups. The verb-resource pair 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?

The description explicitly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving clear when-to-use guidance. It does not explicitly exclude sibling tools like compare_entities or deep_research, but it provides enough context for an agent to route holistic company-profile requests here.

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 destructiveHint=true and idempotentHint=true, which cover the behavioral traits. The description adds usage context (clearing stale or sensitive data) but does not contradict the annotations. No additional behavioral detail beyond the annotations is needed.

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, with the first defining the action and the second providing usage guidance. Every sentence is essential and front-loaded, making it efficient and easy to parse.

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 delete operation with a single required parameter and no output schema, the description is fully complete. It covers the action, usage context, and relationship with sibling tools, leaving 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?

The input schema has 100% coverage for the single 'key' parameter, which already describes it as 'Memory key to delete'. The description does not add new semantic information about the parameter, so a baseline score of 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key', using a specific verb and resource. It also mentions pairing with sibling tools 'remember' and 'recall', clearly distinguishing its role.

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

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

The description provides clear when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It suggests pairing with siblings but doesn't explicitly state when not to use or alternatives beyond the immediate family.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds behavioral detail: fetches page, extracts title/description/key links, emits standard markdown format. This provides useful context 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 a single, well-structured paragraph with front-loaded main action. Every sentence adds value: purpose, process, output format, use cases.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description is complete. It covers purpose, process, output format, and use cases. No missing information needed for agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds some context (e.g., what the tool does with the URL) but mostly repeats schema info for max_links. The output format hint is helpful, but not directly about parameters.

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

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

Description clearly states the tool generates a llms.txt file for any URL, specifying the output format and use cases. It distinguishes from sibling tools which are mostly research or game-related, none of which perform this function.

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

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

Description lists explicit use cases (client indexing, personal project drafting, competitor auditing). Does not explicitly state when not to use or mention alternatives, but the context is clear enough given the sibling list.

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) already declare safety. The description adds value by listing the specific fields returned (description, ratings, Metacritic score, etc.) and providing an example, but does not contradict annotations.

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

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

The description is two sentences, front-loads the purpose, and includes an example. Every sentence is useful and concise with no wasted words.

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

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

Given the annotations cover safety and idempotency, and the schema covers parameters, the description adds the list of return fields and an example. No output schema exists, but the description compensates adequately. However, it could mention expected data size or rate limits.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description's example adds a concrete id value but does not add meaning beyond the schema's description of the id 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?

The description uses specific verb 'Get' and resource 'single video game', lists fields (description, ratings, Metacritic score, etc.), and provides an example. This clearly distinguishes it from sibling tools like search_games.

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 for retrieving full details of a single game but does not explicitly state when to use this tool over siblings (e.g., search_games). No when-not or alternative guidance is given.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover the main behavioral traits. The description adds that the tool returns game counts per genre, but does not elaborate on other behavioral aspects like rate limits or response structure. The description is consistent with annotations and adds minor context.

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

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

The description is a single, well-structured sentence that front-loads the main action and includes concrete examples. Every word contributes value, with no wasted text.

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

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

Given the simplicity of the tool (no required parameters, no output schema), the description provides sufficient context: what it lists, from where, and what additional info is included. It could be slightly more complete by describing the return format (e.g., a list of objects), but the examples partially address that. No output schema exists, so the description carries the burden adequately.

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

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

The single parameter _apiKey is fully described in the input schema (100% coverage), so the description adds no additional meaning. Baseline score of 3 applies because the schema already handles parameter documentation 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 uses a specific verb ('List') and clearly identifies the resource ('all video game genres in the RAWG database') and additional detail ('with game counts per genre'), with concrete examples. It distinguishes this tool from sibling tools like list_platforms, which lists a different resource.

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 implicitly indicates when to use the tool (when listing genres), but provides no explicit guidance on when not to use it or alternatives. For a simple listing tool this is adequate, but it does not reach the standard of explicitly stating use cases or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the output includes game counts per platform, but does not detail other behaviors (e.g., pagination, ordering).

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, concise sentence with no fluff, front-loading the key information (list all platforms with game counts) directly.

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 read-only list tool with rich annotations, the description adequately covers what the tool does and returns. Minor missing details like pagination are acceptable given the 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 description coverage is 100% for the single optional parameter _apiKey, which already has a good description. The tool description adds no further parameter insight, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists all gaming platforms in the RAWG database with game counts per platform, and provides concrete examples (PC, PlayStation 5, etc.), making the purpose unambiguous.

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

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

No guidance on when to use this tool versus sibling tools like list_genres or search_games. The description only states its function without usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns specific fields and pertains to the caller's subscriptions, providing moderate additional context without contradiction.

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

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

The description consists of two efficient sentences. The first sentence states the core purpose, and the second provides usage guidance. No extraneous content.

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

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

For a simple read tool with one optional parameter and no output schema, the description adequately covers functionality, returned fields, and usage context. 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?

The input schema covers the single optional parameter (include_inactive) with a complete description. The tool description adds no additional parameter information, so baseline 3 applies.

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', the resource 'subscriptions', and the scope 'caller's active'. It also enumerates the returned fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

The description provides explicit usage context: 'use this to review what you're monitoring before adding more or to find an id to cancel.' It implies when not to use it (when not needing to review), but does not name alternatives directly.

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 annotations (readOnly=false, destructive=false, idempotent=false), the description discloses meaningful behavior: filing without an account returns a claim_token, rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the fact that the team reads digests daily with direct roadmap impact. It also warns against pasting the end-user's prompt, clarifying what should not be sent. No contradiction with annotations.

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

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

The description is long but packed with non-redundant, actionable content. It front-loads the core purpose, then systematically covers when-to-use, exclusions, param behavior, and constraints. Every sentence adds distinct value (e.g., the rate-limit sentence, the free/quota sentence). This is appropriately sized for a tool with nuanced feedback workflows.

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 no output schema, 4 params, and a nested object, the description fully compensates: it explains return behavior (claim_token, status, changes), the no-account needed flow, and the daily digest signal. It also clarifies the boundary of responsibility (only this Pipeworx connection's tools). The description leaves no critical operational question unanswered.

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?

Though the schema already provides 100% coverage, the description adds substantial param-level guidance: it explains how to use claim_token in a follow-up call, instructs to 'describe the issue in terms of Pipeworx tools/packs' (refining context/message), and clarifies which tool-prefixed names qualify. It even gives a concrete syntax example. This elevates parameter understanding beyond the schema.

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

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

The description opens with a crisp, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete use-case types (bug, feature/data_gap, praise) and explicitly distinguishes this tool from sibling MCP tools by stating it is 'ONLY for tools served by this Pipeworx connection' and names the alternative (file with that server). This fully disambiguates it from the many 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 provides explicit when-to-use guidance (bug, feature/data_gap, praise) and a clear exclusion: if the tool came from a different MCP server, do not file here. It even gives a decision heuristic ('Not sure? Pipeworx tool names are the ones this connection lists.') and describes the claim_token round-trip workflow for later status checks. This is exemplary 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?

Discloses data source (CF analytics-engine), privacy (no PII), output structure (pack, tool, count), and caching behavior (5min-1h). These details add value beyond the annotations, which already declare read-only and idempotent hints.

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

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

Single paragraph with no wasted words. Front-loaded with the primary function, followed by structured use cases and technical details. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description fully explains what the tool returns (top tools, packs, call volume), the data source, and caching. No gaps remain.

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

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

The schema covers 100% of parameter documentation, including an enum and description. The tool description does not add new semantic information about the 'window' parameter beyond what the schema provides, meeting 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 returns trending data (top tools, packs, call volume) with a specific verb 'calling on Pipeworx'. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on aggregate trending statistics.

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 three concrete use cases (discovering hot data, confirming canonical tools, aligning with agent needs) but does not explicitly state when not to use it. However, the use cases imply clear context for appropriate 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral detail: partition checks, fill checks, semantic anchor, placeholder filtering, 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 (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose/mode selection. While dense, it is efficient and each part adds value. Could be slightly more concise but still high-quality.

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 thoroughly explains the response structure including opportunities array, partition_check fields, and fill check results. It also references a complementary tool (polymarket_fill_risk). The description is complete for the tool's complexity.

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

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

Schema coverage is 100% and the description adds valuable context beyond schema: examples of valid slugs, acceptance of full URLs, and seed question examples. This helps the agent understand acceptable input formats.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks, with specific modes (no args, event, topic). It effectively distinguishes the purpose from general trading or research tools, though it doesn't explicitly differentiate from sibling tools like polymarket_edges.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It recommends event mode for specific markets and explains the advantage of cross-event mode. However, it doesn't explicitly say when not to use the tool or compare it to alternatives.

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

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

Annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) are consistent and the description adds extensive behavioral context: model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), caching (1h at KV level), response structure with diagnostics, and tradeable-edge knobs. 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 long but well-structured, front-loaded with purpose and then detailed sections. Every sentence adds value, covering model families, response fields, knobs, and diagnostics. Could be slightly more concise but is efficient for the complexity.

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

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

No output schema, so the description thoroughly explains the return format: by_segment groups, edge attributes (edge_pp_net, kelly_fraction, etc.), diagnostics, fed_candidates, and caching behavior. Complete for an agent to understand the response without additional documentation.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The description adds some context (e.g., explanation of 'Tradeable-edge knobs' and min_partition_leg_kelly), but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate given high 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?

Description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The verb 'scan' and resource 'Polymarket markets' are specific. The purpose 'what should I bet on today' is explicit. While sibling tools like polymarket_arbitrage and polymarket_edge_tracker exist, the description uniquely positions this tool for edge discovery using Pipeworx signals, making it distinguishable.

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

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

The description explains what the tool does but does not provide explicit guidance on when to use it versus siblings such as polymarket_arbitrage or polymarket_edge_tracker. There are no when-to-use or when-not-to-use statements. The implied usage is for discovering opportunities, but without explicit alternatives, it scores 3.

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 readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: snapshots have a 60-day TTL, decay is computed from daily closes of edge_pp_net net of default slippage, gaps mean no scan occurred, and it explains the response structure (tracked, expired, snapshot_dates). No contradiction.

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

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

The description is front-loaded with the core question and purpose. It is somewhat verbose but each sentence adds value. The structure flows from purpose to response format to limits, making it easy to follow.

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

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

Given the tool has only two parameters and no output schema, the description is remarkably complete. It details the response structure (tracked, expired, snapshot_dates) and boundary conditions (TTL, history depth), leaving little ambiguity for an agent.

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

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

Input schema has full coverage with clear descriptions. The description restates parameters (days and window) and adds context: days are lookback with default 14 and max 30 (consistent with schema's 'clamp 2-30'), window is described as 'snapshot family' which adds meaning beyond the schema's wording.

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's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes between a fresh wide edge and an old one, which differentiates it from siblings like polymarket_edges.

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

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

The description explicitly states what the tool answers ('how long has this edge existed and is it shrinking?') and provides context for when to use it. It does not, however, explicitly state when not to use it or list alternative tools.

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

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

Description reinforces readOnlyHint and destructiveHint by describing it as a check. Discloses that partial basket fills can convert arb into unhedged directional position. 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?

Dense but well-organized; front-loaded with purpose. Every sentence adds value. Could be more structured with sections, but given complexity, it is 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 no output schema and high complexity (two modes, warnings), description covers inputs, behaviors, risks, and usage context completely. 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?

Despite 100% schema coverage, description adds meaning: explains default values, interpretation of size_usd in both modes, side auto-detection for baskets, and clamping range. Significantly enhances understanding.

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

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

Clearly states it checks realizable-vs-theoretical edge against CLOB order-book depth. Distinguishes between single-market and basket modes. Purpose is immediately clear and distinct from siblings like polymarket_arbitrage.

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

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

Explicitly says when to use (before acting on arbitrage signals or trades above ~$500) and why (theoretical overround not capturable, partial fills cause directional risk). No ambiguity.

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

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

The description is exceptionally transparent, disclosing matching mechanics (token overlap, unverified pairing), safety fields, interpretation of compatibility codes, temporal alignment semantics, and the gross-vs-net fee limitation. It clearly states the tool is read-only, consistent with readOnlyHint=true and destructiveHint=false, and even explains when it cannot compute alignment. It adds substantial behavioral context beyond the annotations rather than 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 long, but every sentence carries operational weight, and the structure is front-loaded: purpose, modes, response, safety fields, then caveats. The density is justified because there is no output schema to carry the field semantics. It could be tightened, but it remains readable and 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?

For a tool with no output schema, the description thoroughly covers return shape (top_spreads_pp, compatibility fields, temporal_alignment, fees_note, skipped counters) and explains edge cases such as null alignment and unknown metric_types. Required-parameter behavior, mode selection, and safety caveats are all specified. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it defines the exact 10 topic shortcuts, explains that kalshi_event_ticker and polymarket_event_slug act as overrides, and clarifies that both modes use the same matcher. This is useful operational meaning that goes beyond the bare schema descriptions. No parameter is left ambiguous.

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?

Opens with a clear definition: cross-venue spread between Kalshi and Polymarket for the same resolving question, and immediately distinguishes it from simple same-venue pricing by noting participant-pool differences and equivalence checks. The two-mode explanation (topic shortcuts vs explicit ticker/slug) further clarifies the tool's exact resource and action. This clearly differentiates it from siblings like polymarket_arbitrage or polymarket_edges.

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

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

Gives explicit mode-selection guidance: use topic shortcuts for pre-mapped macros, or explicit Kalshi/Polymarket identifiers for custom pairings, and notes both modes run the same matcher. It also warns that pre-mapped topics are not automatically tradeable and that spreads are gross, which helps an agent decide when results are actionable. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is unambiguous.

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

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

Adds scoping context (anonymous IP, BYO key hash, account ID) beyond annotations, without contradiction.

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

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

Three sentences, front-loaded with main action, 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?

Sufficient for a single optional parameter tool with good annotations; covers purpose, usage, behavior, and parameter.

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?

Adds meaning beyond schema by explaining that omitting the key lists all saved keys, leveraging 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?

The description clearly states the tool retrieves a previously saved value or lists all keys, distinguishing from sibling tools like remember and forget.

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

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

Provides concrete use cases (e.g., target ticker, address, research notes) and mentions pairing with remember/forget, though could explicitly exclude alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that mark_read flags returned events as read in same call and that polling is fine—useful behavioral detail 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?

Four efficient sentences: purpose, what is returned, filtering options, mark_read, and alternative endpoint. No fluff; each sentence adds distinct 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?

With no output schema, description specifies return fields (source, citation_uri, raw payload). Covers filtering, mark_read, and alternative access. Could mention limit behavior or unread_only, but overall sufficient for a retrieval tool.

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

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

Schema coverage is 100% with schema descriptions. Description adds context: example filter value ('sec_8k'), purpose for mark_read, and mentions ISO timestamp format. Does not explain limit or unread_only further, but schema already does.

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

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

The description clearly states the tool pulls fired events from subscription feed, specifying returned fields (source, citation_uri, raw event payload). This verb+resource description distinguishes it from siblings like list_subscriptions and subscribe.

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 filtering guidance (type, since), mark_read behavior, and notes that polling works fine, plus an alternative REST endpoint. Lacks explicit when-not-to-use or direct sibling comparisons, but overall clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing a safe, idempotent operation. The description adds significant behavioral context: the fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure (changes grouped by source, count, citation URIs). 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 yet thorough, with example queries front-loaded. Every sentence serves a purpose, covering usage, parameters, source details, and alternative tool mention. No filler or repetition.

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

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

Despite having no output schema, the description fully informs the agent about what to expect: changes grouped by source, total_changes count, and citation URIs. It covers all three parameters, source behavior, fallback, and boundaries (only company type). The contrast with 'entity_profile' completes the contextual picture.

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 value by explaining that 'since' accepts ISO dates or relative shorthand, provides examples, and recommends '30d' or '1m'. It also clarifies that 'value' can be a ticker or CIK, and 'type' is limited to 'company'. This goes beyond the schema's own 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 begins with example queries demonstrating the tool's purpose and explicitly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes itself from the sibling tool 'entity_profile' by advising when to use that alternative, ensuring no ambiguity.

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

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

The description provides explicit usage guidance: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO. It also tells when not to use it (use 'entity_profile' for static profiles) and gives specific recommendations for the 'since' parameter, such as using '30d' or '1m' for typical monitoring.

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

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

Adds context beyond annotations: scoped by identifier, persistent vs 24-hour retention. Annotations already indicate idempotentHint=true and destructiveHint=false, and the description aligns 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?

Four sentences, front-loaded with main purpose, no unnecessary words. Each sentence adds distinct information (what, when, scope, pairing).

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

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

Complete for a simple 2-parameter tool: covers purpose, usage context, pairing, scoping, and persistence. No gaps given 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% with descriptions. The description adds value by giving example key formats and clarifying that value can be any text, reinforcing practical usage.

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 'Save data the agent will need to reuse later' with specific examples like resolved ticker, target address, user preference. It distinguishes from sibling tools (recall, forget) by describing its function as storing key-value pairs.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward'. Provides guidance on pairing with recall and forget, and differentiates between authenticated and anonymous sessions.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, `figi_candidates` returned when ambiguity exists, source labeling for identifiers, and internal cascading across lookup endpoints. No contradiction with annotations.

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

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

The description is long but information-dense and well front-loaded with examples and the "Use FIRST" directive. It is organized into SUPPORTED TYPES and value semantics, and nearly every sentence adds context. It loses one point because some details are redundant or could be tightened without losing meaning.

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

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

There is no output schema, so the description carries the full burden of explaining return behavior. It thoroughly covers what identifiers are returned, how ambiguity is handled, what happens when sources fail, and what inputs are acceptable. An agent has enough information to select and invoke this tool correctly across the supported entity types.

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 high-value semantics that the schema alone lacks: the warning to pass the ENTITY NAME ONLY, the explanation that trailing security-class words break matching, the note that an ISIN resolves to the issuing legal entity, and the ticker/CIK/name input variety for company type. This materially improves agent invocation correctness.

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

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

The description opens with a clear, specific verb phrase: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It then enumerates supported entity types (company, drug) and concrete identifier outputs (CIK, LEI, FIGI, RxCUI), which clearly differentiates it from sibling tools like entity_profile or validate_claim.

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

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

The description states an explicit trigger: "Use FIRST whenever you have a name but need an ID," which is strong routing guidance. It also explains that the tool replaces multiple manual lookups, but it does not name alternatives or give explicit when-not-to-use conditions, so it stops short of a full 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 already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds valuable behavioral context: the tool internally calls 'ai_visibility_check' for each entity, ranks results, and returns a ranked list with score, confidence, and signal density. 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 four sentences, front-loaded with the main action, then explains the process, gives a practical use case, and lists return elements. No redundant or unnecessary sentences.

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

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

Despite lacking an output schema, the description adequately summarizes return fields (score, confidence, signal density). Input parameters are fully covered by the schema. It does not address edge cases like error handling or rate limits, but for a comparative tool with comprehensive annotations, it is sufficiently complete.

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

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

Schema coverage is 100% so parameters are well-documented. The description adds a small but useful semantic note: 'First entry treated as the "subject" for narrative; rest are competitors.' This helps the agent understand the role of the 'entities' order.

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 ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishes from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (general comparison). It states exactly what the tool does: probes entities, ranks by score, surfaces most/least recognized.

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 a concrete use case ('competitive AI-marketing audits') and implies when to use this over alternatives (single-entity check vs. multi-entity comparison). It does not explicitly state when not to use or list alternatives, but the 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavioral details: fans out across two services, partial failure handling, bundlephobia timing (5-30s), and listing failed sources. No contradictions.

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

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

The description is a single paragraph but front-loaded with the core purpose. Some verbosity in enumerating return fields, but every sentence adds value. Could be slightly more structured (e.g., bullet points) but remains clear.

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

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

Despite no output schema, the description fully explains return structure (summary block, per-advisory details, links, alternative versions). Covers partial failures, ecosystem scope, and timing. Complete for a tool with rich annotations.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by mentioning scoped packages ('@types/node') and explicitly stating version defaults to latest. While the schema already covers basics, the description reinforces and adds context.

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

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

The description clearly states the tool performs a composite check for npm packages, combining deps.dev and bundlephobia data. It uses specific verbs ('check', 'fans out') and resources ('npm package'), and the function is distinctive among siblings (none other do this composite check).

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 specifies when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', and handles partial failures gracefully.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds behavioral context by listing return fields (ratings, Metacritic scores, release dates, platforms, genres) and a concrete example with ordering. It does not contradict annotations and provides useful detail beyond them.

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

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

The description is two sentences plus an example, front-loading the purpose and providing a concrete usage case. Every sentence adds value; there is no redundancy or fluff.

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

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

Given the tool has 6 parameters, 100% schema coverage, and annotations, the description provides a clear overview of functionality and return data. It could mention pagination behavior or rate limit considerations, but the example and schema compensate. Overall, it is sufficiently complete 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 description coverage is 100%, so the baseline is 3. The description adds an example showing how to use query and ordering, and mentions searching by name, genre, or platform, which loosely maps to parameters. While not necessary, the example aids understanding.

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

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

The description clearly states the tool searches the RAWG video game database by name, genre, or platform, which is a specific verb+resource. It distinguishes from sibling tools like get_game (single game lookup) and list_genres/list_platforms (data enumeration).

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

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

The description implies usage for searching games but does not explicitly state when to use this tool versus alternatives (e.g., get_game for specific details, list_genres for genre lists). The example provides practical guidance but lacks direct comparison to siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), and cap (200K chars with truncation flagging). This provides full behavioral 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?

The description is efficiently structured: first sentence defines core purpose, followed by usage guidance, examples, technical details, and pairing. No wasted words; every sentence contributes meaning. It is front-loaded with the key action.

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

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

Despite no output schema, the description fully describes return values: top-N passages with character offsets and similarity scores. It also covers input constraints (cap, truncation) and pairing with sibling tools. For a well-annotated tool, this is complete and self-sufficient.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The tool description enhances with illustrative examples: 'Pass the text you already pulled (e.g. a SEC 10-K body...)' for 'text', and query examples like 'supply-chain risk'. The limit parameter is clarified with default 5 and range. This adds value beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching. The examples (SEC 10-K, article) make it concrete.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains that it saves context by returning only relevant passages. Also describes pairing with ask_pipeworx_grounded for grounded reasoning.

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

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

Adds important behavioral details beyond annotations (e.g., OAuth requirement, type-specific params, delivery limits) but the idempotent annotation is contradicted by the description implying each call creates a new subscription.

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

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

Well-structured and front-loaded with purpose, each sentence adds value, though slightly verbose for a very detailed 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?

Comprehensively covers all aspects: purpose, requirements, supported types with examples, delivery options with limits and authentication, leaving no obvious gaps despite no output schema.

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

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

With 100% schema coverage, the description enriches parameters with concrete examples and constraints (e.g., phone verification, 10/day cap for SMS), providing significant added value.

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

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

The description clearly states the verb ('Create') and resource ('proactive monitoring subscription'), and distinguishes from sibling tools 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?

Provides explicit context such as requiring a Pipeworx OAuth account and details on supported types and delivery channels, but does not explicitly state when to avoid using this tool or mention alternatives.

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

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

The description discloses that the tool is read-only, returns example questions with tool invocation details drawn from a live catalog, and has no side effects. This complements the annotations (readOnlyHint, idempotentHint) by adding context about the output format and the fact it's an onboarding aid. 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 informative but somewhat verbose. It lists many example queries and topics, which is helpful but could be trimmed without losing clarity. However, the structure is logical (purpose, when to use, argument explanation, typical use case) and front-loaded with the key intent.

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

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

Given there is no output schema, the description adequately explains what is returned (category-bucketed example questions). It also covers the single parameter, the tool's role among many siblings, and the intended use case. No gaps are apparent for an onboarding 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 schema already provides a description for the 'topic' parameter with default values. The tool description adds further meaning by explaining the purpose (focusing results) and giving example values (finance, pharma, etc.). Since schema coverage is 100%, the description provides incremental value beyond the schema.

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

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

The description uses specific verbs ('returns category-bucketed example questions') and clearly identifies the tool as an onboarding entry point. It distinguishes itself from sibling tools like 'ask_pipeworx' by stating it provides suggestions for what to ask, not answering queries directly.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do' and provides scenarios like 'getting started' or 'what can you do?'. Also gives guidance on when to omit or pass the 'topic' argument, and mentions alternative paths like 'ask_pipeworx' for actual questions.

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 (which already indicate non-destructive), the description adds that the row is deactivated not deleted and historical events remain, providing key 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?

Two sentences, front-loaded with action and constraints, with zero wasted words.

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

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

Given the simple tool (one required param, no output schema), the description fully covers behavior, ownership, and lifecycle, referencing sibling tools effectively.

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

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

Schema coverage is 100%, so the description adds minimal param info beyond reinforcing that id is from subscribe, meeting 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 verb 'Cancel' and resource 'subscription by id', distinguishing it from sibling tools like subscribe (create) and list_subscriptions.

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

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

The description states ownership enforcement ('you can only cancel your own subscriptions') and implies the id comes from subscribe, but does not explicitly list when-not to use 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?

The description goes well beyond the annotations by explaining the routing logic (SEC EDGAR path vs. grounded pipeline), the meaning of each verdict (including the crucial distinction between 'could_not_verify' meaning the check did not happen and 'unsupported' meaning no source exists), and the presence of verification_error{stage,detail}. This adds significant operational context that annotations do not cover.

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

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

Although the description is long, every sentence carries critical information: examples, routing, return values, verdict semantics, and error handling. It is front-loaded with the purpose and remains tightly organized with no redundant phrases. The length is justified by the tool's complexity.

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

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

The description fully explains the tool's behavior without an output schema: it covers what it takes as input, how it processes different claim types, what it returns (verdicts with specific meanings), and how to interpret special cases. It also notes the tool's efficiency over sequential calls, making it self-contained enough for an agent to use correctly.

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

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

The input schema already provides 100% coverage with detailed descriptions for both parameters, including tolerance_pct range and default behavior. The description reinforces this by mentioning 'exact percent-delta math' and the tolerance override concept, but adds minimal new information beyond the schema. The baseline of 3 is exceeded due to the schema's exceptional detail and the description's integration of parameter meaning into the overall behavior.

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 natural-language claim verification tool against authoritative sources, with concrete example phrasings. It distinguishes two modes (company-financial vs. any other claim) and explicitly states the output (verdict + value + citation), making the purpose highly specific and distinguishable 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?

It explicitly states when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct.' It also covers the two routing scenarios and notes it replaces 4–6 sequential calls, but does not name specific alternatives or exclusions. Clear context without explicit sibling differentiation.

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