Numbers

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

Discloses default model is free, Anthropic requires separate API key with pass-through, and return format (per-model and combined view). Annotations already indicate read-only, idempotent, non-destructive; description adds cost implications and data flow details 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 covering purpose, parameter usage, and use cases. No extraneous information. Front-loaded with the core function. Each sentence adds value.

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

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

With 4 parameters and no output schema, the description fully explains all parameters and the return structure (per-model score, confidence, signals, raw_response + combined view). It also addresses the cost model for Anthropic. 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?

All 4 parameters have descriptions in the schema (100% coverage). The tool description adds meaningful context: default model, free usage, API key pass-through, and disambiguation purpose for 'context'. This goes beyond the schema descriptions.

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

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

Clearly states the action (probe LLMs), resource (business/brand/product/topic), and output (visibility score 0-100). Distinguishes from sibling tools by focusing on visibility scoring rather than general Q&A or scanning. Includes specific use cases (AI-marketing audits, pre-launch checks, competitive monitoring).

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

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

Provides context on when to use (brand audits, competitive monitoring) and how to set parameters (default model, BYO key for Anthropic, context disambiguation). Does not explicitly contrast with sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence', but the description itself gives sufficient guidance.

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

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

Annotations already communicate read-only, open-world, idempotent behavior. The description adds valuable behavioral context: it is a router that fills arguments across thousands of tools, returns a structured answer, and emits stable pipeworx:// citation URIs. This goes beyond the annotations and clarifies what the agent should expect from the call.

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 important guidance, but it is overlong and repetitive. Phrases like 'Need exact verification and citations?' and 'Need 100% no wrong answer?' restate the same ask_pipeworx_grounded guidance, and the 'Short answer no citations needed?' sentence is confusing. The redundancy buries useful 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?

Even without an output schema, the description provides the essential contract: structured answer, stable citation URIs, broad domain coverage, and which siblings to use instead. It gives concrete examples and routes the agent appropriately. Minor gaps remain around failure behavior and exact answer shape, but the description is sufficient for correct invocation.

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

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

The schema covers all six parameters at 100% and describes each as an alias for the natural-language question. The description reinforces this with examples but does not add format or syntax details beyond the schema. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description names a specific action — routing a natural-language question to one of 5,798 verified-source tools — and clearly scopes it to factual, real-world, current or historical questions. It also distinguishes itself from close siblings like deep_research and ask_pipeworx_grounded, so there is no ambiguity about what this tool does.

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

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

The description is explicit about when to use this tool: prefer it over web search for factual questions, use it whenever the user asks 'what is', 'look up', 'find', 'get the latest', etc. It also names exclusions and alternatives — open-ended exploration should use deep_research, exam-grade verification should use ask_pipeworx_grounded, and broad multi-part questions should use deep_research.

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 that candidate routing improvements may be enabled live, that none is currently active (retired 2026-07-26), and that it currently matches ask_pipeworx exactly. It clarifies there is no fallback to the stable router by stating 'this IS a full working router, just the experimental edge.' This meaningfully goes beyond the read-only/idempotent annotations with experimental-context transparency.

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

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

Three sentences with the key beta status and usage instruction front-loaded. Details like the 5,798 tool count and the retirement date support the 'identical' and 'currently inactive' claims without bloating. Could be trimmed slightly, but every sentence earns its place.

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

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

Covers what the tool is, its current behavior, and how to use it relative to ask_pipeworx, which supplies the response-shape context via the 'same response shape' statement. There is no output schema, but referencing the identical shape of the sibling fills that gap. It does lack an explicit caveat about potential output differences when a candidate is active, but the current status is clearly stated.

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

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

The input schema fully documents the question parameter and its five aliases with 100% coverage, so the description carries little parameter burden. The description only mentions 'same arguments' without adding details, but the schema already provides sufficient meaning. Baseline 3 is appropriate given the high schema coverage.

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

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

Description explicitly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It clearly distinguishes from the stable ask_pipeworx by its experimental routing and current inactive candidate status. This is a specific, well-scoped definition.

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

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

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing,' giving a clear condition for selection. It also implies the stable ask_pipeworx is the alternative for non-experimental use by noting results are compared against it. Does not list all exclusions, but the routing intent 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 cover the safety profile (readOnlyHint, openWorldHint, idempotentHint, non-destructive), and the description adds substantial behavior beyond that: refusal rather than fabrication, the full refusal_reason taxonomy (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the structured success contract with verbatim evidence, and the extra LLM call cost. Nothing contradicts 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 dense but every sentence earns its place. The opening sentence front-loads the core differentiator, and the return-contract and refusal-reason enumeration justify their length because there is no output schema to carry that information. It is on the longer side, but contains no filler.

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

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

This is a complex tool with no output schema, and the description carries the full return contract for both success ({answer, evidence, confidence, source, fetched_at}) and refusal ({answer:null, refusal_reason}) paths, exhaustively enumerates refusal reasons, and states the cost tradeoff versus the sibling. An agent can decide whether to invoke, know what to expect, and handle failure modes without additional queries.

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 'question' parameter and its five aliases (query, q, prompt, text, input) are fully documented in the schema, setting the baseline at 3. The description adds context that the question is routed internally to fill arguments for other tools, but gives no phrasing, formatting, or syntax guidance beyond 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?

The description states a specific verb and resource: a 'hallucination-resistant answer mode' that fetches data via tool routing and 'EXTRACTS the answer using ONLY what the tool result contains.' It clearly distinguishes itself from the sibling ask_pipeworx by the grounded-evidence contract and refusal behavior, so an agent can tell them apart without inspecting 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?

Explicit when-to-use guidance is present: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). The when-not-to-use is equally explicit: 'prefer ask_pipeworx for casual lookups,' backed by the cost tradeoff of one extra LLM call. The alternative sibling is named 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?

Extremely detailed beyond annotations: describes low-confidence resolution short-circuit, closed/dead market handling, wide-spread illiquidity note, cancellation rule parsing, fan-out examples, resolver contract with confidence levels, parent event extraction, news fallback mechanisms, and safety checks. Annotations already indicate readOnly and idempotent; the description adds critical edge-case behaviors.

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

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

Long but well-structured: front-loaded with core purpose, then organized into clear sections (input, usage, classifiers, fan-out, response shape, resolver, parent event, news, safety). Every sentence adds value; could be more concise but 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?

Comprehensive coverage given the tool's complexity: input flexibility, classification, fan-out logic, response structure, resolver confidence handling, parent event extraction, news fallback, safety mechanisms, and market state handling. No output schema exists, but the description fully compensates.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context on parameter usage: explains 'quick' vs 'thorough' depth, 'include_raw' purpose, and input formats (slug, URL, question text). This enriches the schema definitions slightly, justifying a 4.

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

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

Clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and contrasts with similar tools like polymarket_edges, polymarket_arbitrage, etc., by focusing on general research. Sibling differentiation is implicit but effective.

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

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

Explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides context but does not explicitly mention when not to use or compare with siblings; however, the examples and structure guide the agent adequately.

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 the tool is read-only, open-world, and idempotent. The description adds significant behavioral details: it reveals data sources (SEC EDGAR/XBRL with off-calendar fiscal year handling, FAERS), mentions result sorting by primary metric, and specifies that it returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is well-structured, starting with common query examples, then stating the core function, followed by details on data sources and output. It is somewhat verbose but each sentence provides valuable information. Front-loading with examples aids quick understanding.

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?

Without an output schema, the description explains that it returns 'paired data + pipeworx:// citation URIs per entity,' which is sufficient for an agent to understand the return format. It also covers input constraints (2-5 entities) and data sources. Could mention if there are limits on the number of metrics returned, but overall complete for the tool's purpose.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches these by explaining what data is pulled for each entity type (e.g., revenue, net income for companies; adverse-event counts for drugs) and provides examples of valid inputs (e.g., tickers, drug names). This adds meaningful context beyond the schema alone.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2–5 companies or drugs, citing specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and examples of queries it handles (e.g., 'Compare X and Y', 'X vs Y'). It effectively distinguishes itself from sibling tools like 'entity_profile' by emphasizing its multi-entity parallel nature.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear directive for when to use this tool versus making multiple calls to single-entity lookups. It also guides the user on the 'type' parameter for choosing between company and drug comparisons.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds value by disclosing that the operation is keyless and offline, and that it works on integers. These behavioral traits are not present in the annotations and help the agent understand autonomy and data flow.

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 sentence followed by an inline example. It is front-loaded with the core action and constraints (numeral bases 2-36, keyless, offline). Every word serves a purpose, and the example is illustrative without redundancy.

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

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

The example clearly shows the output format (a string), compensating for the lack of an output schema. However, it does not mention error handling (e.g., invalid input, out-of-range bases) or explicitly state that the output is a string. Given the tool's simplicity, the description is mostly complete but could be slightly more explicit about return value type.

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 covers all three parameters with descriptions and examples. The description does not add additional semantic detail beyond the schema, but the example usage reinforces the parameter relationships. Given 100% schema coverage, a score of 3 is appropriate.

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

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

The description clearly states it converts integers between bases 2-36 with a concrete example. The verb 'convert' and resource 'integer between numeral bases' make the purpose unambiguous, and the example reinforces the operation. It distinguishes from sibling tools like 'from_roman' and 'to_roman' by specifying the base range.

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

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

The description mentions 'keyless, offline', which indicates no authentication or network required, but it does not explicitly state when to use this tool versus alternatives like 'number_to_words' or Roman numeral converters. The usage context is implied but not directly addressed.

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=true, and the description adds substantial behavioral context beyond that: account/auth requirements and paid-tier gating for 'thorough', parallel decomposition across 5,798 internal tools, gap[] never-invented policy, contradictions[] scanning, semantic excerpting rather than head-truncation, resolvable citation_uri guarantees, and timing expectations (15-90s). 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 tightly organized and front-loaded: the most critical operational constraint (account required + alternative) comes first, followed by purpose, mechanism, best-use, and depth details. Every sentence carries unique information for a complex tool with three depth modes, auth nuances, and a rich response contract; the minor redundancy with the schema's depth description prevents a 5.

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

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

No output schema exists, but the description thoroughly covers the return contract: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, hop field, gaps[], contradictions[], and large-record excerpting behavior. It also covers timing, auth, and depth differences — nothing an agent needs to invoke or interpret the result 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 description coverage is 100%, so baseline is 3. The description adds marginal value: it links the 'thorough' enum value to the paid plan, explains the hop/citation_uri mechanics behind depth levels, and ties the question parameter to the recommended use case ('Broad/multi-part is fine — decomposition is the point'). It mostly re-narrates the schema's already-detailed depth enum, so the increment is real but modest.

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 and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' — clearly stating what the tool does in one call. It also distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and naming ask_pipeworx as the alternative for signed-out users, so an agent can tell it apart without inspecting other 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?

Gives explicit when-to-use guidance with concrete examples ('compare X and Y's regulatory + financial exposure'), explicit when-not-to-use ('For a single lookup use ask_pipeworx'), and a conditional routing rule ('If you are not signed in, use ask_pipeworx instead — it works on every tier'). This leaves no ambiguity about choice of tool.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds that results include full schemas and are 'ready to call directly, no second schema lookup needed,' which is useful behavioral info beyond safety.

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 purpose, list of domains, return value, and usage guidance. It is informative but could be slightly more concise without losing value.

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

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

Given no output schema, the description fully explains the return format (top-N tools with names, descriptions, schemas). It covers all necessary aspects for a discovery tool with clear guidance.

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 each parameter is described. The description adds mentions of aliases and examples, but this is not a significant addition beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and distinguishes it from siblings by indicating it's for browsing/discovery before selecting a specific tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance and implying when not to use it.

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

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

It discloses substantial behavior beyond the annotations: parallel fan-out across multiple sources, resolved_from/resolved_to behavior, source failure semantics, empty sections meaning real no-data, private-company handling, and interchangeability of type values. Annotations already mark it read-only/idempotent, and the description adds rich operational context without contradicting them.

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

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

The description is long but information-dense; nearly every sentence carries useful selection or invocation guidance. The example-query list is front-loaded, and the output/edge-case details are grouped logically. It would benefit from light restructuring to reduce run-on feel, but there is minimal 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?

With no output schema, the description does the necessary work of explaining return components: cik/company_name, resolved_from/resolved_to, recent_filings with URIs, fundamentals fields, source list and failure reporting. It also covers accepted input forms and the private-company edge case, making it complete enough for an agent to invoke confidently.

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 schema already documents ticker/CIK/name and type interchangeability. The description adds meaningful nuance beyond the schema by describing resolution behavior, resolved:false for private companies, and the explicit notes line, so it earns credit above baseline.

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

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

The description states a concrete function: build a full cross-source profile of a US public company in one parallel call. It opens with many natural-language trigger examples and explicitly contrasts itself with single-pack SEC/XBRL/news lookups, making its identity and differentiation clear.

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

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

The description explicitly says to prefer this tool over chaining single-pack lookups when the user wants a holistic view. It does not name specific sibling tools or state when-not-to-use cases, so it is slightly less complete than a definition with explicit exclusions and named 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 destructiveHint=true and readOnlyHint=false; description adds context about clearing sensitive data but does not expand beyond that.

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

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

Two concise sentences, front-loaded with main purpose, 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?

Sufficiently complete for a simple tool with one required parameter, no output schema; covers purpose and usage guidance.

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 no extra meaning beyond what the schema already provides for the 'key' parameter.

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

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

Clearly states verb 'delete' and resource 'memory by key', distinguishing from siblings like 'remember' and 'recall'.

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

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

Provides explicit usage contexts: stale context, task done, clear sensitive data. But lacks explicit 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that the tool 'rejects malformed numerals', which is a behavioral trait beyond annotations.

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

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

Single sentence that is concise and front-loaded with the core action. No unnecessary words.

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

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

Given the simple parameter and the presence of annotations, the description covers the main function and validation. Lacks details on return value or error handling, but acceptable for a low-complexity 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 clear parameter description. The description does not add additional meaning beyond 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?

The description clearly states the tool converts a Roman numeral to an integer and mentions rejection of malformed numerals. However, it does not explicitly distinguish from the sibling tool 'to_roman'.

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

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

No guidance on when to use this tool versus alternatives. No mention of context, prerequisites, or when not to use.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description goes beyond by explaining the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This covers behavioral traits without contradicting annotations.

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

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

The description is two sentences: first sentence states the core function and output format, second lists use cases. Every sentence adds value, no fluff, and critical information is front-loaded (generates llms.txt, for AI crawlers).

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

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

Given no output schema, the description explicitly states the return value ('single text blob ready to drop at site-root/llms.txt') and mentions the standard format. For a simple tool with two parameters and clear annotations, the description covers all necessary context.

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

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

Schema coverage is 100% with descriptions for both url and max_links. The description adds no additional meaning beyond the schema; it only mentions extraction of 'title/description/key links,' which is implied by the url parameter. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool generates an llms.txt file, specifies the verb 'generate' and the resource, and lists concrete use cases (e.g., getting a client's site indexed, drafting for own project, auditing competitors). This distinguishes it from sibling tools like scan_competitor_ai_presence, which focus on auditing rather than generating.

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 scenarios ('Useful for: getting a client's site indexed...') but does not discuss when not to use the tool or mention alternatives. It gives clear context but lacks exclusions or comparisons to related tools like ai_visibility_check.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the list of returned fields, which supplements behavioral understanding without contradicting annotations.

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

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

The description is two sentences, front-loading the core action and followed by usage guidance. Every sentence adds value without fluff, making it highly efficient.

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

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

For a simple list tool with one optional parameter, strong annotations, and no output schema, the description covers purpose, output fields, and usage scenario completely.

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

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

Schema coverage is 100% and the description for the only parameter ('include_inactive') exactly matches the schema description. The description adds no new meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions, specifying returned fields. While the purpose is clear, it does not explicitly differentiate from sibling tools like subscribe or unsubscribe, but the verb and resource are distinct enough.

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

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

The description provides explicit guidance on when to use the tool: to review subscriptions before adding more or to find an id to cancel. It doesn't mention when not to use or alternatives, but the given context is helpful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, fully covering the safety and idempotence profile. The description adds no additional behavioral traits (e.g., supported range, handling of negatives, large numbers). Contributes minimal value beyond annotations.

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

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

The description is a single sentence with an immediate purpose statement and an illustrative example. No extraneous words or fluff. Perfectly front-loaded and efficient.

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

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

For a simple tool with one parameter and good annotations, the description covers the core functionality with an example. Minor gaps: does not specify numeric range, behavior for zero or negative numbers, or output format for edge cases. Still, it is largely complete given the tool's simplicity. Missing output schema is acceptable as the return value is implicit from the example.

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

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

Schema coverage is 100% with a single parameter 'number' described as 'An integer.' The description adds an example but no further semantic detail or formatting constraints. Baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Spell an integer in English words'. The example differentiates it from siblings like to_roman and convert_base by showing the English word output. It 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 implies the tool is for converting numbers to words but does not explicitly state when to use it versus alternatives (e.g., to_roman, convert_base). No when-not guidance is provided. Usage is inferred from the example, but explicit guidance is missing.

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 having no annotations, the description discloses key behavioral details: filing without an account returns a claim_token for later status checks, rate-limited to 5 per identifier per day, and free. This adds significant value beyond the schema.

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

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

The description is longer than average but front-loaded with purpose and usage. Every sentence contributes relevant information, though it could be slightly more concise.

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

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

Given no output schema and a relatively complex feedback workflow, the description covers return behavior, rate limits, scoping to Pipeworx tools, and how to follow up with claim_token. 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?

The input schema already covers all parameters (100% coverage), but the description adds important context: how to phrase feedback in terms of Pipeworx tools/packs, and the purpose of claim_token for retrieving previous reports. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools like ask_pipeworx by focusing on reporting issues with Pipeworx tools specifically.

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

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

Provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data...' and when not to use: 'if the tool came from a different MCP server... file it with that server instead.' This is excellent guidance with clear exclusions and alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds further behavioral context: data is derived from Cloudflare analytics, no PII, only aggregated counts, and caching intervals (5min-1h). No contradictions.

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

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

Description is concise (4 sentences) with front-loaded key information. Every sentence adds value: purpose, use cases, data source, caching. No redundancy.

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

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

Given the single optional parameter and no output schema, the description adequately covers what is returned (top tools, packs, call volume) and the time windows. Could mention if the list is ordered but not required.

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

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

Schema coverage is 100% with a description for the only parameter 'window'. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose.

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 'returns' and the resource: top tools, top packs, and total call volume over a configurable time window. It distinguishes from sibling tools by focusing on trending/popularity data, which is unique among the listed siblings.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming popular canonical tool, and aligning use case with demand). However, it does not exclusions or alternatives when not to use, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: fill checks against live CLOB depth, semantic filters (Jaccard similarity, placeholder fraction), and conditions under which signals should be ignored. 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 thorough and well-structured, with clear sections for modes and additional details (semantic anchor, partition filter, fill check). It front-loads the core purpose. While somewhat verbose, every sentence serves a purpose given the tool's complexity.

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

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

Despite no output schema, the description fully explains the return structure (opportunities[] fields, partition_check details) and edge cases (realizable_edge_pp ≤ 0, placeholder filtering). Covers all necessary context for a complex tool with 2 optional parameters.

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

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

Schema coverage is 100% (both parameters described). The description adds substantial meaning: explains that event accepts slugs or full URLs, topic accepts seed questions, and the behavior with no args (trending scan). It also explains what each parameter triggers in terms of internal checks.

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 via monotonicity violations and partition-sum checks. It distinguishes between two explicit modes (trending scan with no args, event for specific market, topic for cross-event), making its purpose specific and distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit when-to-use guidance: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. It also explains when not to trade (realizable_edge_pp ≤ 0) and mentions an alternative tool (polymarket_fill_risk) for custom sizing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: caching at KV level, detailed model families and their formulas, response structure (by_segment, fed_candidates, diagnostics), and special handling of Fed bets. 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 quite lengthy but well-structured, with clear sections and definitions. Every sentence adds value, but there is some verbosity (e.g., detailed formula explanations). It remains front-loaded with the core purpose.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and caching behavior. It covers all parameter semantics and use cases, making it complete for an agent to effectively invoke and interpret results.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains default values, the role of each knob (e.g., min_kelly as half-Kelly fraction, min_partition_leg_kelly applying to per-leg Kelly), and practical context like 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade.'

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and distinguishes it from sibling tools by detailing its specific models and segments (e.g., crypto_price, news_momentum, partition_overround). It uses a specific verb ('scan... and return') and resource ('top Polymarket markets').

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 ('what should I bet on today' discovery) and describes various filtering knobs (min_liquidity, max_spread_pp, etc.). However, it does not explicitly state when not to use it or provide alternatives, though the sibling tools list implies separation of concerns.

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

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

Annotations indicate readOnly, openWorld, and idempotent. The description adds behavioral details like snapshot TTL, decay computation from daily closes, and data gaps. 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 comprehensive but could be slightly more concise. It is well-structured with a clear opening, detailed response fields, and limitations.

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

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

No output schema exists, so the description fully explains the response structure (tracked, expired, snapshot_dates) and limitations (TTL, decay computation). This is highly complete for a complex tool.

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

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

Schema descriptions cover 100% of parameters. The description adds context for 'days' (default 14, max 30) and 'window' (snapshot family, default '1wk'), enhancing the schema's meaning.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry, answering how long an edge has existed and if it is shrinking. It distinguishes from sibling tools like polymarket_edges by focusing on historical 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 implicitly tells when to use the tool by explaining the value of distinguishing fresh vs. old edges. However, it does not explicitly mention when not to use 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?

Discloses detailed behavior: walks ladder, returns fills, slippage, verdict, and per-leg details. Warns about forced directional risk. Annotations (readOnlyHint, idempotentHint) align with read-only nature, 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?

Structured with bold headings for modes and usage, front-loaded with purpose. Slightly verbose but justified given complexity; no wasted 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?

No output schema, but description fully documents return values for both modes. Covers parameters, usage, risks, and edge cases (thin_legs, forced directional risk). Complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds context (e.g., size_usd as settlement notional for basket, default side auto-detection). Adds value beyond 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 it checks realizable-vs-theoretical edge against live order book depth, with specific single-market and basket modes. Distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk/feasibility.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns about partial basket fills converting arbs into unhedged positions. Provides clear when-to-use and risks.

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 readOnly/idempotent/non-destructive, and the description goes far beyond them. It discloses that pairs are matched by keyword and word overlap rather than a shared resolution source (pairing_unverified), that Kalshi fees are not modeled so spreads are gross not net, and that unknown metric types are never paired. This is exemplary behavioral disclosure.

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 purpose is front-loaded and the structure is logical, but the description is very long and repeats the topic list that already appears in the schema. Several sentences, while informative, could be tightened without losing meaning, so it is not genuinely concise.

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

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

Even with no output schema, the description documents the response shape (leg prices, top_spreads_pp), every safety field, compatibility code, counter, and the gross-fee limitation. For a complex read-only comparison tool, nothing an agent needs to invoke or interpret the result 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 semantics by explaining the two modes and the override relationship: topic auto-fetches matching events, while the explicit tickers override the mapped sides. It clarifies the intended relationship between the three optional parameters beyond the schema's field-level 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 opening sentence states a precise analytical target: the cross-venue spread between Kalshi and Polymarket for the same resolving question. The description then expands with two modes and response content, clearly distinguishing this tool from sibling Polygon/Kalshi tools by naming both venues and the spread concept.

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

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

The description gives clear context for when the output is meaningful: it explains when the delta is a real signal versus when bet shapes differ, and warns that most pre-mapped topics are currently non-tradeable. It stops short of naming sibling alternatives or explicit exclusions, so it is not a full routing guide.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and pairing with remember/forget, which provides useful context beyond annotations.

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

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

Two sentences with no waste. Front-loaded with action, efficiently conveys purpose and guidelines.

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

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

Description is complete for the tool's simplicity. No output schema needed as return type is implied (value or list). Could mention data type of stored values but not critical.

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 schema's property description already explains omitting key lists all keys. Description adds no additional semantic value beyond schema.

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

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

Clearly states it retrieves a saved value or lists all keys. Distinguishes from sibling tools '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?

Explicitly says when to use (look up stored context) and not to re-derive from scratch. Mentions pairing with remember/forget and scope.

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=true, but the description reveals that mark_read:true can flag events as read, modifying state. This creates a contradiction. The description does disclose return fields and optional side-effects, but the contradictory annotation reduces clarity.

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

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

The description is front-loaded with the main purpose and efficiently covers parameters in four sentences. There is no fluff, and every sentence adds value. Minor improvement could be more structured formatting.

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

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

Given no output schema, the description explains return fields (source, citation_uri, payload) and covers parameter behavior. It also mentions polling and an alternative access method. It lacks pagination details and error handling, but overall is sufficient for the 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?

The schema covers all 5 parameters, and the description adds value by providing examples (e.g., type='sec_8k'), explaining the effect of mark_read, and clarifying the behavior of since. This goes beyond the schema's minimal 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 it pulls fired events from a subscription feed, specifies return fields, and mentions filtering options. It distinguishes from siblings like list_subscriptions by focusing on events rather than subscriptions. However, it doesn't explicitly differentiate from other possible alert-related tools.

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

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

The description mentions that polling works fine and provides an alternative GET endpoint, giving some usage context. However, it doesn't specify when not to use this tool or compare it directly to siblings, leaving some ambiguity for the agent.

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

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

Discloses multi-source fan-out, fallback behavior (GDELT→GNews), soft-fail for USPTO, and return format. Annotations already indicate safety, and description adds valuable 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?

Well-structured with example queries up front, then source details, parameter guidance, and sibling differentiation. Every sentence adds value; no redundancy.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail) and no output schema, the description fully covers behavior, parameters, and use cases. Agent can confidently select and invoke.

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 description adds context for 'since' with examples, clarifies 'value' accepts ticker or CIK, and notes 'type' limited to company. Provides recommended default for 'since'.

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

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

Description clearly states it's a change feed for a company in a time window, listing specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and example queries. Distinguishes from sibling entity_profile.

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

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

Explicitly says when to use this tool (latest changes) and when to use alternative (entity_profile for static profile). Provides example query patterns and date format recommendations.

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 include idempotentHint: true and destructiveHint: false. The description adds critical context: scoped by identifier, 24-hour retention for anonymous sessions, and persistent for authenticated users.

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 with no fluff. Purpose is front-loaded, and each sentence adds value: purpose, usage context, storage details, and sibling references.

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

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

For a simple write tool with full schema annotations, the description covers scope, persistence, and relationships with recall/forget. No output schema is needed.

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

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

Schema coverage is 100% for both parameters. The description adds examples of value types ('findings, addresses, preferences, notes'), providing extra context beyond schema.

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

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

The description clearly states the verb 'Save data' and the resource 'data the agent will need to reuse later', with specific examples (resolved ticker, target address). It distinguishes from sibling tools by naming recall and forget.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). Also notes session vs persistent memory.

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, the description discloses important behaviors: ambiguous matches return figi_candidates and assert nothing, unresolved identifiers are explicitly listed, enrichment degrades gracefully when GLEIF/OpenFIGI is unavailable, and one call cascades through multiple lookup endpoints. This adds meaningful behavioral context and does not contradict the read-only/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?

The description is long and dense, with heavy parentheticals, but it is front-loaded with purpose and trigger examples, and each section adds necessary behavioral or parameter detail. A tighter structure would improve scannability, but the content earns its place for a multi-source 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?

Even without an output schema, the description covers return behavior well: source-labelled identifiers, an explicit unresolved field, figi_candidates for ambiguous matches, and the drug citation format. For a complex tool with multiple backends, this is remarkably 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 already 100%, but the description goes well beyond it with the crucial 'Pass the ENTITY NAME ONLY' rule, issuer-as-printed guidance for bonds, concrete input examples (AAPL, 0000320193, ozempic), and type-specific resolution mechanics. This materially increases the chance of 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 clearly states a specific verb and resource: resolving a user-spoken name to canonical/official identifiers, listing concrete ID types (CIK, ticker, LEI, RxCUI, FIGI). The trigger phrasings and supported types make it easy to distinguish from siblings like entity_profile or compare_entities, which are about richer profiles/comparisons rather than name-to-ID resolution.

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

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

The description gives explicit invocation guidance: 'Use FIRST whenever you have a name but need an ID,' plus concrete example phrasings that tell an agent when this tool is appropriate. It does not name sibling alternatives or state explicit when-not-to-use conditions, but the contextual guidance is strong enough to route an agent 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?

Beyond annotations (readOnly=true, idempotent=true), the description reveals it internally calls ai_visibility_check for each entity and returns score, confidence, signal density. This adds behavioral detail without contradicting annotations.

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

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

Three sentences: core action, internal mechanism, use case + output. Every sentence adds value. No redundancy, perfectly front-loaded.

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

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

Lacks an output schema but describes output format (ranked list with score, confidence, signal density). Covers multiple probes, ranking, and competitive context. Minor omission: no mention of error handling or dependency on ai_visibility_check, but overall sufficient for a composite 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%, so baseline 3. Description adds minimal value: mentions 'first entity treated as subject' and 'optional shared context', but schema already describes both. No additional parameter semantics beyond what schema provides.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and returns a ranked list. Distinguishes from sibling ai_visibility_check (single entity) by explicitly mentioning it uses it and compares.

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 a concrete use case ('competitive AI-marketing audits') and an example question. Implies when to use (multiple entities) but does not explicitly state when not to use or list alternatives besides the implied single-entity sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: it fans out across deps.dev and bundlephobia, bundlephobia's first measurement can take 5-30s, and partial failures report sources_failed. This goes well 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 dense but informative, front-loading the core purpose. It could be slightly shorter, but each sentence adds value given the tool's complexity. Only minor excess like 'Composite' at start.

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 comprehensively lists return fields (summary block with specific metrics, per-advisory detail, links, alternative versions). It also covers performance caveats and partial failure behavior, making it nearly complete for an agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package name and optional version). The description adds minor value by restating that the default version is latest and scoped packages are accepted, but doesn't significantly enhance 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 clearly states it performs a composite check for adding an npm package, covering license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. The verb 'scan' and resource 'dependency' are specific, and it naturally distinguishes itself from siblings like scan_competitor_ai_presence.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies NPM-only scope in v1, and describes graceful degradation with partial failures, which guides when to use alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable details: max input size (200K chars), truncation warning, embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and output features (character offsets, similarity scores). 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 compact paragraph that front-loads the core purpose, then efficiently adds usage context, pairing suggestion, and technical details. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description fully covers return values (top N passages with offsets and scores), constraints (200K char limit, truncation flag), and use cases. All three parameters are explained comprehensively. The tool's moderate complexity is well addressed.

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

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

Schema coverage is 100% with all three parameters described. The description adds concrete examples for 'query' (e.g., 'supply-chain risk'), specifies default for 'limit' (5), and clarifies the max length for 'text'. This goes beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, provides concrete examples (SEC 10-K body, article), and explains the input-output behavior. It indirectly distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

The description explicitly says 'use when the record is too big to cram into the prompt' and notes it saves context. It also suggests pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use it or list alternatives beyond the sibling pairing.

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 write operation (readOnlyHint=false) with idempotentHint=true and openWorldHint=true. The description adds behavioral context: requires OAuth, delivery channels (feed always on, optional email/sms/webhook with constraints like 10 SMS/day limit, webhook auto-disable after 10 failures, signing secret returned once). No contradiction.

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

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

The description is relatively long but front-loaded with the core purpose. Every sentence adds value, though some technical details (e.g., webhook HMAC signing) could be abbreviated. Still, it remains clear and well-structured.

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

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

Given the tool's complexity (3 params including nested objects, no output schema) and the presence of sibling management tools, this description provides complete context: subscription creation, types, delivery, OAuth requirement, and constraints. No missing critical information.

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

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

Schema coverage is 100% so baseline is 3. The description adds significant value by explaining each enum option for type, providing detailed examples for params per type, and clarifying delivery fields including verification and caps. This goes well beyond the schema's minimal 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

The description explains when to use the tool (for proactive monitoring), requires Pipeworx OAuth account, and lists supported subscription types with parameter examples. It does not explicitly state when not to use it or name alternatives, 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 cover read-only, open-world, idempotent, non-destructive traits. Description adds valuable context about return content (category-bucketed with exact tool+argument shape) and behavior with/without topic. 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?

Description is informative and well-structured, front-loading the primary purpose. Slightly verbose but every sentence adds value; could be tightened slightly without loss.

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 one optional parameter and no output schema, the description thoroughly explains tool output format, coverage, and usage scenarios, making it complete for agent understanding.

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

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

Schema coverage is 100% for the one parameter, but description adds extra meaning by listing possible topic values ('finance, pharma, ...'), explaining effect of omission, and clarifying output customization.

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

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

Clearly states the tool returns category-bucketed example questions for onboarding, listing specific categories and distinguishing it as the first-use entry point for learning about Pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools like ask_pipeworx, providing clear when-to-use guidance and alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the range constraint but no additional behavioral disclosure (e.g., no mention of error handling or output format). Description 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?

A single, front-loaded sentence that efficiently communicates the core purpose without unnecessary words. Every word earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema, clear name), the description is sufficiently complete. It covers the input range and purpose. The output type (Roman numeral string) is implied by the tool name and description.

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

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

Schema coverage is 100% with a clear parameter description. The description repeats the range from the schema but adds no new semantics beyond 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?

The description clearly states the verb 'Convert' and the resource 'integer to Roman numerals' with a specific range '1-3999'. It distinguishes itself from the sibling tool 'from_roman', which does the opposite conversion.

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

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

The description implies when to use (converting to Roman) but lacks explicit guidance on when not to use or mention of the alternative sibling 'from_roman'. Usage context is implied through purpose clarity.

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=false, destructiveHint=false, idempotentHint=true), description adds that row is deactivated (not deleted) and historical events remain, providing critical 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?

Three concise sentences with no waste: action, ownership constraint, and side effects all efficiently communicated.

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, description fully covers action, constraint, and outcome, making it complete.

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

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

Schema coverage is 100% with parameter description 'Subscription id (uuid) returned by subscribe.' Description adds minimal extra meaning beyond confirming 'by id'.

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 'Cancel a subscription by id' with specific verb and resource, distinguishing from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Ownership enforcement is explicitly stated ('you can only cancel your own subscriptions'), clarifying when to use. No explicit alternatives mentioned, but context is clear.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description adds critical behavioral context: the distinction between 'could_not_verify' (a pipeline failure that is NOT evidence) and 'unsupported' (no source covers it), the two routing paths, and the return format. This significantly enriches the agent's understanding of expected behavior. No contradiction with annotations.

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

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

The description is dense and front-loaded with call patterns, but it is somewhat long and includes some repetition (e.g., explaining the grounded pipeline multiple times). It could be slightly more structured, but every sentence carries meaningful information for this complex tool, so it earns a high 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 (two routing paths, five verdict types, error cases), the description is remarkably complete. It explains return values (verdict, value, citation, reasoning), clarifies the meanings of the most ambiguous verdicts ('could_not_verify' and 'unsupported'), and states when the tool should be used. With no output schema provided, this description carries the full burden and does so well.

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 both parameters (claim, tolerance_pct), so the baseline is 3. The description adds some context about percent-delta math and hallucination detection tolerance, but mostly reinforces schema details rather than introducing new parameter semantics. It does not compensate for any gaps, but none are needed.

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

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

The description clearly states a specific verb+resource: 'validate_claim' with natural-language claim verification, and provides clear examples of user intents ('Is it true that…', 'fact check'). It differentiates itself by explaining its claim-verification output (verdict) and the routing of financial vs non-financial claims, which sets it apart from the broader research tools in its sibling list.

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

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

Explicit usage guidance is provided: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies sub-routing for company-financial claims via SEC EDGAR and any other claim via a grounded pipeline, plus notes that it replaces 4–6 sequential calls. This is clear when-to-use direction.

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