Coinmarketcap

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by explaining default model, cost of Anthropic calls, and return structure. No contradictions; it provides helpful behavioral context beyond annotations.

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

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

Three sentences, front-loaded with purpose, no fluff. Efficiently covers behavior, parameters, and use cases.

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

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

Given good annotations and full schema coverage, the description covers purpose, return shape, and use cases. Lacks error handling or rate limits but is reasonably complete for the complexity level.

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

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

Schema coverage is 100%, baseline is 3. The description enhances parameter understanding by explaining model defaults, API key cost implications, and return shape (per-model {score, confidence, signals, raw_response}). Adds moderate value over schema.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. The verb 'probe', resource 'LLMs', and scope are specific. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring across models.

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 use cases (AI-marketing audits, pre-launch brand checks) but does not explicitly state when not to use or compare to sibling tools. Usage is implied but lacks clear guidance on alternatives.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, and the description adds meaningful context: it routes to a massive verified tool/source network, fills arguments, and returns structured answers with citation URIs. No contradiction exists between the description and annotations.

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

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

The description is front-loaded with the key preference rule and is dense with useful routing information and examples. It is longer than necessary in places, and the compressed '1 entity: ask_pipeworx_grounded' fragment is awkwardly phrased, but the structure still emphasizes the most important guidance first.

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 tells the agent what to expect: a structured answer with stable pipeworx:// citation URIs. It covers covered domains, trigger phrasing, example queries, and routing decisions for siblings, making it complete enough for a high-complexity router 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%, and the schema already documents the main `question` parameter plus all aliases. The description reinforces that input is a natural-language question and gives useful examples, but it does not add per-parameter semantics beyond what the schema provides, so the 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 what the tool does: it takes a natural-language question, routes it to the right tool among 5,767 options, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It also differentiates from siblings by naming ask_pipeworx_grounded for single-entity cases and deep_research for broad/multi-part questions.

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

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

The description gives explicit when-to-use guidance: prefer over web search for specified domains and trigger phrases like 'what is', 'look up', 'get the latest'. It also provides alternatives and exclusions, telling the agent to use deep_research for multi-part questions that should fan out across sources, and clarifying that breaking-news questions are already routed to live news by ask_pipeworx.

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

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

Annotations already mark the tool read-only and idempotent, and the description adds meaningful live behavior: no candidate is currently active, the last was retired on 2026-07-26, and this currently matches ask_pipeworx exactly. It also discloses that there is no fallback and that this is a full working router, not a thin wrapper. There is no contradiction with the readOnlyHint, openWorldHint, or idempotentHint annotations.

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

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

The description is dense and front-loaded with the beta identity and current parity statement. It is slightly redundant—'currently matches ask_pipeworx exactly' is reinforced by the no-active-candidate explanation and the fallback sentence—but each clause contributes a distinct fact, such as candidate status, usage condition, and full-router assurance.

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

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

For a tool with one required string parameter and no output schema, this description is nearly complete: it states what the tool is, how to invoke it, the current experimental state, the comparison purpose, and response-shape parity with ask_pipeworx. It does not spell out the response format, but it explicitly ties it to ask_pipeworx's shape, which is sufficient given the sibling context. The description leaves no critical gap for correct invocation.

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

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

Schema coverage is complete at 100%: question is documented as accepting natural language with aliases q, text, input, query, and prompt, and all other properties are described as aliases. The description adds only that arguments are the same as ask_pipeworx, which is helpful for transfer but does not materially expand parameter understanding. Baseline 3 applies because the schema already carries the parameter 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 identifies this as the beta variant of ask_pipeworx: an identical universal router over 5,767 tools, with the same arguments and response shape. It distinguishes the tool from stable ask_pipeworx and from the 'grounded' sibling by framing it as the experimental routing edge. It is not tautological; it names the tool's exact role and current behavior.

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 an explicit use condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the evaluation context—results are compared against the stable router to decide what merges—which helps an agent understand the experimental tradeoff. However, it does not explicitly say when not to use it or compare it to ask_pipeworx_grounded, so it stops just short of full alternative routing guidance.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by revealing critical behavioral traits: it only extracts answers from tool results, it returns an explicit refusal with specific refusal_reason enums when data doesn't answer, and it costs an extra LLM call. This gives the agent precise expectations about success and failure modes.

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 two sentences but each part earns its place: purpose, mechanism, output contract, refusal contract, usage guidance, and cost tradeoff. It is well-structured with clear punctuation and front-loads the distinctive groundedness behavior before the routing mechanics.

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

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

With no output schema, the description fully documents the return shape on both success and refusal, including all refusal_reason values. It also covers the performance tradeoff and usage context, leaving no gap an agent would need to infer.

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

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

The input schema already provides 100% coverage, documenting the single logical parameter 'question' and all its aliases (query, q, prompt, text, input). The description does not add parameter-specific semantics, but 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' which names a specific verb (answer) and resource (Pipeworx) with a clear differentiator—groundedness. It also contrasts with ask_pipeworx by noting the same routing but a stricter extraction behavior, so the agent can distinguish it from the sibling.

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

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

It explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a concrete exclusion: 'prefer ask_pipeworx for casual lookups,' which names the alternative and the condition for selecting 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?

Disclosures far exceed annotations: includes market resolution, fan-out logic, safety short-circuits, closed market handling, spread warnings, cancellation rule risk, and response shapes. 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?

Front-loaded with core purpose, but very lengthy with extensive detail (classifiers, fan-out examples, edge cases). Could be trimmed for agent efficiency without losing critical info.

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

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

Given no output schema, description fully explains return values (evidence packet, market fields, analysis, resolver contract, parent event, news fields, safety behaviors). Covers all complex behaviors comprehensively.

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

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

Adds substantial value beyond schema: explains how market input can be slug/URL/question, depth examples, include_raw usage with size trade-offs. Schema already covers basics, so description enriches with context.

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

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

The description explicitly states it researches Polymarket bets by pulling Pipeworx data, resolving, classifying, fanning out, and returning evidence. It gives specific use cases and examples of input formats, making the purpose very clear and distinct from sibling tools.

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

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

Provides clear usage scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') but does not explicitly exclude cases or compare to alternatives like ask_pipeworx or 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description does not add behavioral details beyond what annotations state, but it is consistent and does not contradict them.

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

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

The description is extremely concise—one sentence with front-loaded verb and examples. Every word is meaningful, and there is no waste.

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 and the presence of an output schema (which documents return values) and annotations (which cover behavior), the description is nearly complete. It could mention that the list returns all meta-categories, but the examples imply that.

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

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

With only 50% schema description coverage, the description should compensate for undocumented parameters (e.g., 'start'), but it mentions no parameters at all, offering no additional meaning beyond the schema.

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

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

The description clearly states the verb 'List' and the resource 'meta-categories', and provides illustrative examples (DeFi, L1, NFTs, Memes), which distinguishes it from the sibling tool 'category'.

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

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

No explicit guidance on when to use or alternatives is provided, but the simple list operation implies usage is straightforward; however, the description does not address exclusions or comparison with sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by detailing the return output (price, market cap, 24h change per coin), which goes 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, well-structured sentence that front-loads the action and outcome without any superfluous words.

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

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

Given the presence of an output schema and annotations, the description adequately covers the tool's purpose and return values. It does not discuss pagination or ordering, but for a simple fetch with two params, this is sufficient.

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

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

The description explains the required 'id' parameter (obtained from 'categories') but does not elaborate on the optional 'convert' parameter. With 50% schema coverage, the description partially compensates but could clarify 'convert' (likely a currency conversion, like 'EUR' in example).

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 fetches coins belonging to a CoinMarketCap category, specifies the return fields (price, market cap, 24h change), and distinguishes from the sibling 'categories' tool by referencing it for obtaining IDs.

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 guides the user to obtain IDs from the 'categories' tool, which is a clear prerequisite. However, it does not provide explicit exclusions or alternative use cases, which is acceptable for a focused fetch 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 indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. It also notes efficiency gains. No contradictions with annotations. Score 5.

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

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

The description is concise and front-loaded with query patterns, but it is a single dense paragraph without bullet points or clear sections. While every sentence adds value, slightly better structure (e.g., separating input format from behavior) could improve readability. Score 4.

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 provides adequate insight into return format ('paired data + citation URIs') and sorting behavior. However, it does not describe the exact output structure (e.g., JSON fields), which could be helpful. The sibling tools don't compete, so context is sufficient overall. Score 4.

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 significantly enhances understanding by explaining what each enum value does and providing examples for the values array. It clarifies that 'company' pulls financials and 'drug' pulls adverse event data, and gives input format suggestions like tickers vs drug names. This adds meaning beyond the schema, earning a 5.

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: side-by-side comparison of 2-5 companies or drugs. It provides example query patterns like 'compare X and Y' and 'rank these companies', and explicitly distinguishes from sibling tools by stating 'ALWAYS PREFER over sequential single-pack lookups'. This high specificity and differentiation justify a score of 5.

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

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

The description provides explicit when-to-use guidance, listing multiple trigger phrases and a strong recommendation to prefer over sequential lookups. It also explains what data each entity type retrieves, giving clear context for correct invocation. This comprehensive guidance merits a score of 5.

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

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

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations already set, the description adds rich behavioral context: it explains parallel decomposition across 5,767 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[]), the hop system for different depth tiers, contradictions[] scanning, semantic excerpting behavior, and expected latency. It also explicitly states it never invents data (gaps[] are returned when data can't answer), which goes beyond what annotations declare.

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

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

The description is information-dense but quite long, with several parenthetical comments and a slight typo in the depth enum values ('thorough' vs 'thorough' appearing in one place). It front-loads the critical auth requirement and alternative tool routing, which is good, but the density makes it harder to parse in one pass. Every sentence does earn its place, but it could be restructured for readability.

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

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

Despite having no output schema, the description fully documents what the return format looks like (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[] for standard/thorough). It also covers prerequisites (account needed), time expectations, depth tier differences, and edge behaviors like how large records are handled. For a complex tool of this scope, this is exceptional coverage.

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

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

The schema already has 100% coverage, describing both parameters thoroughly. The description adds significant value by explaining what the depth levels actually do at runtime (quick=3 facets single hop, standard=3 with gap recovery + contradictions, thorough=6 paid with iterative hop), and provides concrete examples of the question format, but it doesn't add much about the 'question' parameter beyond what the schema already states.

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: grounded multi-source research across Pipeworx's structured data sources in one call, explicitly distinguishing it from open-web search. It provides specific examples of use cases and names concrete data source categories, making it immediately clear what this tool does and how it differs from 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 explicit usage guidance: it says to use ask_pipeworx instead when not signed in, and instructs to prefer ask_pipeworx for breaking/current-news topics. It also specifies when deep_research is best (broad/multi-part questions over structured data) versus alternatives (single lookup, current news), and details the depth tiers with exact behaviors.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns the top-N most relevant tools with names, descriptions, and full input schemas with curated examples, ready to call directly. This goes beyond what annotations provide, enhancing 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?

The description is comprehensive but not overly verbose. It front-loads the core purpose and then provides additional details. It could be slightly more concise, but each sentence adds value, so it earns a 4.

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 exactly what the tool returns (top-N tools with names, descriptions, schemas, examples). It also covers aliases for the query parameter. The description is complete for a discovery tool, leaving no significant gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the 'query' parameter accepts natural language descriptions and mentions aliases (task, q, description, search), plus provides two examples. This improves clarity beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous specific domains and explicitly states that it is for browsing/searching/discovering tools, distinguishing it from siblings by noting it should be called first to see the option set.

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates when to use the tool and implies when not to (e.g., when you already know the tool to call).

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description richly discloses behavior: parallel fan-out across multiple sources, soft-failure for the USPTO patents source, empty sections as real 'no data' rather than bugs, and explicit resolved:false semantics for private companies. 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 densely structured and front-loaded with usage examples and the core directive. Each sentence contributes behavioral or output semantics, though some output-field detail could be trimmed if an output schema existed.

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 carries full responsibility for explaining return values, and it does so thoroughly: it enumerates every output section, explains semantics for empty results, and documents failure behavior. Nothing an agent needs to correctly invoke and interpret this tool 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?

The schema already describes both parameters at 100% coverage, so the baseline is adequate. The description adds meaningful semantics beyond the schema—type accepts 'company' or 'ticker' interchangeably, value can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR—making parameter usage clearer.

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: it builds a 'full cross-source profile of a US public company' in one parallel call. It distinguishes itself from chaining single-pack SEC/XBRL/news lookups and includes concrete user-phrase examples, making its scope unmistakable.

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

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

It explicitly tells the agent to 'ALWAYS PREFER' this tool over chaining single-pack lookups when the user asks for a holistic view. It also covers edge-case routing—private companies return resolved:false with notes—so the agent knows what to expect and how to respond.

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 destructive and idempotent behavior; description adds little beyond stating the action. Could clarify behavior if key does not exist.

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

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

Two sentences with no wasted words. Purpose and usage are front-loaded.

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

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

For a simple tool with one required parameter and annotations covering destructive behavior, the description covers essential context. Minor gap: no mention of return value or idempotency details.

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

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

Schema coverage is 100%, and the description does not add additional meaning beyond what the schema 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?

Describes the action (delete), the resource (memory by key), and references siblings (remember, recall) for differentiation.

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

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

Explicitly states when to use (stale context, task done, clear sensitive data) but doesn't explicitly exclude scenarios like confirmation requirements.

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, so the safety profile is clear. The description adds that the tool 'Fetches the page' (network access aligning with openWorldHint) and 'emits the standard llms.txt markdown format.' This provides useful behavioral context beyond annotations.

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

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

The description is concise, with three sentences that front-load the core action and then add context. No wasted words; every sentence serves a purpose.

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

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

Given the tool has 2 parameters, no output schema, and annotations present, the description covers purpose, output format, and use cases adequately. It could mention potential errors for invalid URLs, but for a simple generation tool it is sufficiently complete.

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

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

Schema coverage is 100% with descriptions for both 'url' and 'max_links'. The description mentions 'for any URL' and 'default 25, max 50' implicitly but does not add meaning beyond the schema. Baseline score 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 'Generate a production-ready llms.txt file for any URL', specifying the verb (generate), resource (llms.txt file), and scope (any URL). It also describes the process and output format. This distinguishes it from siblings like 'ai_visibility_check' or '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?

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' While it doesn't state when not to use the tool, the given scenarios cover the main intents.

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 the tool as read-only, idempotent, and non-destructive. The description adds no behavioral details beyond the listed metrics, but the annotations sufficiently cover safety. 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 a single, front-loaded sentence that efficiently conveys the tool's output. No wasted words.

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

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

Given the tool's simplicity (one optional parameter, clear output via output schema, and comprehensive annotations), the description is complete. It lists all key return metrics.

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

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

Schema description coverage is 100% for the single parameter 'convert'. The description does not add meaning beyond the schema's 'Default USD' note, so 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 lists specific metrics (market cap, volume, dominance, active cryptos) that the tool returns, making the purpose clear. However, it does not explicitly distinguish this tool from siblings like 'listings_latest' or 'quotes', which also provide market data.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not specify context, prerequisites, or exclude cases where another tool would be more appropriate.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds sortability, pagination limit, and returned fields, providing full behavioral transparency beyond annotations.

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

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

Single sentence front-loaded with key information; every part adds value. No fluff.

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

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

With output schema present, description covers purpose, parameters, and results adequately. Annotations provide safety profile. Complete for a list 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 detailed parameter descriptions. The description reiterates some info (sortability, limit) but does not add substantial new meaning beyond the schema.

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

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

Explicitly states it returns a paginated list of cryptocurrencies ranked by market cap or other metrics, with specific fields. Distinguishes from sibling tools like 'categories' or 'global_metrics'.

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?

Clear context for use (ranking, sorting, pagination) but no explicit when-not-to-use or direct sibling comparison.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral details: it returns specific fields and includes an optional parameter for inactive subscriptions, which goes beyond the annotations.

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

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

The description is two sentences long, starts with the core action and returned data, and then provides usage guidance. 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?

For a simple list tool with one optional parameter and no output schema, the description adequately covers the returned fields and the parameter. It is sufficiently complete for the agent to use the tool correctly.

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

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

Schema coverage is 100% with a description for the only parameter (include_inactive). The description does not add additional param semantics beyond the schema, 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 explicitly states 'List the caller's active subscriptions' and enumerates the returned fields (id, type, etc.), making the purpose clear. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description advises to 'review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use the tool. It does not explicitly state when not to use it, but the use case is well-defined.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description's mention of 'static' adds marginal context. No contradictions. The description could elaborate on response format or edge cases (e.g., missing parameters), but the presence of an output schema mitigates this.

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, no wasted words. Front-loaded with the key idea ('Static coin metadata') and immediately specifies what it includes. Perfectly 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 the rich annotations and presence of an output schema, the description adequately covers the tool's functionality. It could mention that both parameters are optional (returning all coins), but the schema's lack of required params implies this, and the description is otherwise complete for a simple data retrieval tool.

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

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

Schema coverage is 100%, with clear descriptions for both parameters (comma-separated IDs/tickers). The description adds no additional meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly identifies the tool's purpose: retrieving static coin metadata such as logo, description, website, and social links. It distinguishes from sibling tools like quotes or categories, but could be more explicit about the action (e.g., 'get'). The verb 'metadata' is implied by context.

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

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

The description provides no guidance on when to use this tool over alternatives (e.g., quotes, categories, global_metrics). It does not specify when not to use it or mention use cases. The agent must infer usage from the tool name and description alone.

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 are all false and offer little, so the description carries the full burden. It discloses several non-obvious behaviors: rate-limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow ('returns a claim_token; pass it back later...to read whether it was fixed'), and that it is free and doesn't count against the quota. It also explains the human process ('team reads digests daily') and provides content constraints ('don't paste the end-user's prompt'). This is rich behavioral context well beyond the annotations.

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

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

The description is a dense paragraph, but every sentence earns its place: purpose, usage cases, exclusion, claim_token mechanics, rate limit, quota. It is front-loaded with the primary action and then logically flows to edge cases. While longer than typical, the complexity of the tool (claim_token reading, cross-server exclusion) justifies the length. A slight structure improvement would be bullet points, but current form is acceptable.

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 covers the essential return behavior ('returns a claim_token' when no account) and the later read workflow. It explains the type enum implicitly through bug/feature/data_gap/praise examples. It addresses prerequisites (filing without an account), limitations (rate limit), and integration with the broader Pipeworx ecosystem. For a feedback tool with nested context and four parameters, this description 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 description coverage is 100%, so baseline is 3. The description adds meaningful value beyond the schema: it explains the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...'), which is not clear from the schema alone. It also advises 'Describe the issue in terms of Pipeworx tools/packs' for the message/context parameters. This elevates parameter understanding without repeating schema text.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling research/query tools by framing its scope as feedback about Pipeworx tools. It further clarifies boundaries with 'ONLY for tools served by this Pipeworx connection', making the purpose unambiguous.

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

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

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a concrete when-not-to-use exclusion: if the tool came from another MCP server, 'file it with that server instead.' This surpasses typical usage guidance and directly addresses alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destruction. The description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII), cache duration (5min-1h), and the nature of the signal (self-aggregating). No contradiction with annotations.

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

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

The description is a single, well-organized paragraph. It starts with purpose, lists use cases in a readable way, and adds supporting details. Every sentence provides value, but it could be more concise or use bullet points for the use cases.

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

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

With no output schema, the description explains return content (top tools, top packs, call volume) but not the exact structure. However, the tool is simple (single optional param, read-only) and the description covers key aspects, making it sufficiently complete for an AI agent.

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

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

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

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 what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb-resource pair and distinguishes itself from siblings like ask_pipeworx, discover_tools, and others by focusing on aggregated trending data.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming popular tools, and seeing alignment with common agent needs. It provides clear context but does not explicitly exclude alternatives or state when not to use this tool.

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

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

Discloses detailed behavioral traits beyond annotations: fill check logic (realizable_edge_pp <= 0 means don't trade), semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder slugs, >20% placeholder returns null), and response fields. No contradiction with annotations (readOnly, idempotent, openWorld, non-destructive).

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

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

The description is lengthy but well-structured with bolded sub-sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that aid readability. Every sentence provides necessary detail; it could be slightly trimmed but remains 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?

Comprehensively covers the tool's functionality: explains default behavior, two modes, output format, filters, fill check, and cross-event matching criteria. Despite no output schema, the description sufficiently describes the response structure and conditions for use.

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

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

Schema description coverage is 100%, and the description adds context by explaining the purpose of each parameter, providing example values, and describing the behavioral differences between event and topic modes, which goes beyond the schema's brief 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, and explicitly distinguishes three modes (no args, event, topic) which differentiates it 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?

Provides explicit guidance on when to use each parameter ('Call with NO args for trending_scan... pass event for per-event partition_check, or topic for cross-event scan'), explains what each mode does, and mentions that fill check should be used before trading, with alternative tool 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, openWorldHint, idempotentHint, and destructiveHint. Description goes far beyond, explaining three model families, edge computation, tradeable-edge knobs, response structure, diagnostics, and caching behavior.

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

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

Description is well-structured with sections: purpose, model families, knobs, response, caching. Front-loaded with purpose. Though dense, every sentence provides value. Could be slightly more concise but still effective.

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

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

Given 9 parameters, no output schema, and annotations, the description is extremely complete: explains output structure (by_segment, diagnostics), edge metrics, filter rationale, and special cases like Fed bets and caching.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds context for min_liquidity and max_spread_pp by explaining they are tradeable-edge filters. This provides value beyond the schema.

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

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

Clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific verb and resource. Distinguishes from sibling 'polymarket_arbitrage' by focusing on Pipeworx data disagreement.

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 'Built for what should I bet on today' and provides when-to-use guidance. Notes Fed bets are excluded from ranking and why. Does not directly compare to siblings but implies it's for opportunity discovery.

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

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

The description adds significant behavioral context beyond the read-only annotation: it explains data sourcing from snapshots, gap handling, and limitations (60-day TTL, decay from daily closes). 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 and front-loaded, starting with the core purpose then detailing args, response, and limitations. Every sentence adds value without waste.

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

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

Given the complexity, lack of output schema, and rich annotations, the description is complete. It fully explains the response structure, data sources, and constraints, enabling effective tool use.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description repeats defaults and limits but does not add substantial new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current snapshots.

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

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

The description gives context on when to use (analyzing edge age and decay) and explains the key insight about fresh vs old edges. It provides default values and limits but does not explicitly state when not to use or mention alternatives.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: it checks depth, walks the order book, returns specific fields, and warns about partial basket fills creating unhedged positions. No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear sections (CAPS for requirements, bullet-style for modes). Every sentence adds value, though some redundancy could be trimmed. Front-loaded with purpose and requirement.

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

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

Given 4 parameters, no output schema, and complexity (basket vs single-market, risk warnings), the description is thorough: explains all parameters, return fields, default behaviors, and critical warnings about partial fills and directional risk.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining single-market vs basket modes, default sides, and size interpretation (e.g., 'shares per leg; each share pays $1') beyond the schema descriptions.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly mentions using this tool before acting on 'polymarket_arbitrage SELL/BUY-EVERY-LEG signal' or 'polymarket_edges trade above ~$500', differentiating from sibling tools.

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

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

The description provides explicit guidance on when to use the tool (before acting on arbitrage signals or trades above ~$500) and why (theoretical overround not capturable on thin books, partial fills convert arb to directional position). It also states the requirement of one of 'market' or 'event' parameters.

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

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

Annotations already mark this read-only/idempotent, and the description goes far beyond them: it discloses the matching method (keyword and word overlap, 'not a shared resolution source'), that warnings can appear even with matched_pairs>0, that unclassified legs are never paired and land in skipped_unclassified/low_confidence_pairs, the null-vs-false semantics of temporal_alignment, and the fee-modeling gap (gross spread, not net tradeable edge). It even flags that the tool cannot verify pairing. This is exceptional behavioral disclosure for a complex matcher.

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

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

The description is dense and information-rich, with useful CAPS-LABELED sections (TWO MODES, RESPONSE, SAFETY FIELDS) and the purpose front-loaded. However, it is a long wall of text with redundancy — the 'not the same as aligned / not that the two sides align' point is made three times, and the parenthetical asides accumulate. It earns most of its length, but tighter organization would serve agents better.

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

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

For a complex tool with no output schema, the description carries the full burden of explaining return values, and it largely succeeds: it covers spread[].top_spreads_pp, per-entry flags[], skipped_unclassified, low_confidence_pairs[], temporal_alignment{}, fees_note, and the skipped_cross_type/subtype counters. Given the tool's genuine complexity — two modes, matching heuristics, and multiple warning channels — the coverage is thorough. Minor gaps (e.g., exact entry structure of top_spreads_pp) are acceptable at this complexity level.

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% — each of the three params already has a description and examples. The description adds value beyond that by framing the mode relationship: topic auto-fetches matching events on both venues while the explicit params override each side, and by stating that both modes run the identical token-overlap matcher so the same disclosures apply. It ties the three params into a coherent two-mode model the schema alone does not convey.

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

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

Opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It precisely defines the deliverable (spread in percentage points, Kalshi − Polymarket) and scopes it to matched outcomes on both venues. The two-mode structure and the return components are all described, leaving no ambiguity about what the tool computes or how it distinguishes itself from single-venue siblings like polymarket_edges.

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

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

Provides explicit mode-selection guidance: topic shortcuts for 10 pre-mapped macros versus explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, including the override semantics. It also gives a clear when-not expectation ('most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable') and tells the agent to verify resolution dates itself when temporal_alignment_unknown. However, it never names sibling alternatives (e.g., polymarket_arbitrage) or states when to prefer them, so the 'alternatives' half of a 5 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds 'latest' implying freshness and covers parameter requirements, which aligns and slightly extends transparency. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence that communicates the core purpose and key differentiators (by symbol or id). It is optimally concise with no wasted words.

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

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

Given the presence of an output schema and complete parameter descriptions, the description sufficiently outlines what the tool returns ('latest market quotes'). No additional context needed for this simple query tool.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description repeats the two identification methods but adds no new semantic meaning beyond the schema. The examples in schema already illustrate usage.

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

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

The description clearly states the tool provides 'latest market quotes' for cryptocurrencies and specifies two identification methods (symbol or id). The verb and resource are explicit, and the description distinguishes the tool from siblings like 'listings_latest' or 'global_metrics' covering different data.

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

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

The description implies usage when needing up-to-date quotes but provides no when-not or alternative guidance. With many sibling tools, explicit usage context would help, but the current phrasing is minimally adequate.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds value by disclosing the scoping mechanism (anonymous IP, BYO key hash, account ID) and the pairing with remember/forget for lifecycle management. No contradictions detected; the description complements annotations well.

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

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

The description is four sentences long with no redundancy. It front-loads the core action ('Retrieve a value... or list all saved keys'), then provides usage context, scoping, and pairing information. Every sentence contributes essential information without waste.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers all necessary context: what it does, when to use it, who the data is scoped to, and how it relates to sibling tools. It is fully adequate for agent decision-making without requiring additional information from the schema or annotations.

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

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

The input schema covers 100% of the parameter documentation, with 'key' described as 'Memory key to retrieve (omit to list all keys).' The tool description primarily reiterates this information without adding new semantic detail beyond the schema. Since the schema already provides adequate meaning, the description adds marginal value here.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It provides concrete examples of usage (target ticker, address, research notes) and explicitly distinguishes between the two modes. The mention of pairing with 'remember' and 'forget' differentiates it from sibling tools.

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

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

The description explains when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' It also instructs when to omit the key argument to list all keys. It mentions scoping to the agent's identifier, which is useful context. However, it does not explicitly state when not to use or suggest alternative tools for similar tasks, but the pairing with remember/forget provides implicit 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?

Description contradicts readOnlyHint annotation: setting mark_read:true modifies state (flags events as read), but annotation declares no modifications. This is a critical inconsistency.

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 pack all necessary information with no waste, front-loading the core action and returning specifics.

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

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

Despite no output schema, the description explains what each event carries, covers all parameters, and provides an alternative access method, making it fully complete for its complexity.

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

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

With 100% schema coverage, the description adds significant value by explaining parameter usage with examples (e.g., type filter 'sec_8k', ISO timestamp for since, effect of mark_read) beyond the schema definitions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, returns specific fields, and allows filtering. It distinguishes itself from siblings like list_subscriptions by focusing on event data.

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

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

The description provides clear context for use, mentions polling is fine, and gives an alternative access method via URL. However, it does not explicitly contrast with sibling tools or state when not to use, but the purpose is well-defined.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals the fan-out behavior, fallback logic (GDELT→GNews), USPTO soft-fail, and structured return format, adding significant behavioral context.

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

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

The description is concise and front-loaded with example queries. It efficiently covers sources, parameters, return format, and alternative tool 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?

Without an output schema, the description details the return structure (changes[] grouped by source, total_changes, citation URIs). All necessary context for proper invocation is present.

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

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

Schema coverage is 100%, but the description adds value by explaining 'since' accepts ISO dates or relative shorthand ('7d', '30d', '1y') with a recommendation ('30d' or '1m'). It also clarifies 'value' accepts ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company, fanning out to SEC EDGAR, GDELT→GNews, and USPTO. It explicitly distinguishes from the sibling tool entity_profile, which covers static profiles.

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

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

The description gives explicit usage examples ('What's new with X', 'latest on Y') and directs to use entity_profile for static profiles, providing clear guidance on when not to use this tool.

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

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

Annotations already indicate idempotent and non-destructive. The description adds valuable context: persistence varies by auth (persistent for authenticated users, 24-hour for anonymous), and data is scoped by identifier. 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?

Concise and well-structured: front-loaded with purpose, then usage context, then behavioral details. Every sentence adds value, no fluff.

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

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

Given the simplicity (2 parameters, no output schema), the description fully covers what the tool does, when to use, persistence behavior, and how it relates to siblings. Complete.

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

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

Schema coverage is 100%, so baseline 3. The description adds context that it's a key-value pair scoped by identifier but doesn't enhance meaning of individual parameters beyond schema examples. Adequate.

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

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

The description clearly states the verb 'save' and resource 'data', specifying the tool's purpose: to store data for reuse across conversations or sessions. It provides concrete examples like resolved ticker, target address, user preference, research subject, distinguishing it from siblings 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 states when to use: 'when you discover something worth carrying forward'. It pairs with recall and forget, providing clear guidance on usage context and alternatives. No ambiguity.

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

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

The description richly discloses behavior beyond the annotations: it degrades gracefully when GLEIF/OpenFIGI are unavailable, returns figi_candidates rather than asserting on ambiguous matches, lists unresolved identifiers explicitly under `unresolved`, labels every identifier with its source, and cascades through multiple lookup endpoints. This goes far beyond the read-only/idempotent hints already provided.

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 query examples and a clear 'use first' directive, and it is well structured by SUPPORTED TYPES. It is long, but most sentences carry useful operational detail; minor redundancy exists where the description restates schema-covered facts like accepted company input forms, so it is excellent but not perfectly lean.

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 carries full responsibility for explaining return behavior. It specifies the identifiers returned per type, how ambiguity is handled via figi_candidates, how unresolved identifiers are surfaced, how enrichment failures degrade, and even the internal cascade cost. Nothing essential for correct invocation or interpretation 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?

Even though schema coverage is 100%, the description adds valuable parameter-level semantics: accepted input forms for each type, the warning to pass the ENTITY NAME ONLY, and the crucial FIGI lookup caveat that trailing security-class words match nothing. This materially improves an agent's ability to construct a correct call.

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 action: resolving a user-spoken name to canonical/official identifiers that other tools require. It enumerates supported entity types (company, drug) and the exact identifiers each returns (CIK, ticker, LEI, FIGI, RxCUI), which clearly distinguishes it from sibling lookup/profile tools like entity_profile or validate_claim.

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

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

The description gives explicit guidance: "Use FIRST whenever you have a name but need an ID" and frames the tool as the entry point for identifier lookups required by other tools. It also covers edge cases like bond issuers and ambiguous matches. However, it does not name specific alternative sibling tools or provide explicit when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds behavioral details like probing with ai_visibility_check, ranking, and returning score/confidence/signal density, but these are consistent with annotations and do not reveal surprising traits 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 two sentences long, with the main action front-loaded. Every sentence adds essential information: what it does, how it works, and its use case. 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 tool's complexity (multiple entities, ranking, reliance on another tool) and the absence of an output schema, the description covers the key aspects: it probes each entity, ranks by score, and returns score/confidence/signal density. It also provides a concrete use case and does not omit critical behavioral details.

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

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

Schema coverage is 100% with each parameter described. The description adds meaning beyond schema: it explains that the first entity is treated as the subject and the rest as competitors, and that context disambiguates common names. This enriches the parameter understanding significantly.

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 compares AI visibility across multiple entities side-by-side, probes each entity, ranks by score, and surfaces most/least recognized. It distinguishes itself from sibling tool ai_visibility_check by aggregating multiple probes and adding ranking.

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

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

The description provides clear context for when to use: for competitive AI-marketing audits, illustrated with an example question. However, it does not explicitly state when not to use or mention alternatives, though the sibling tool ai_visibility_check is implied for single-entity checks.

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

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

Annotations already indicate read-only, non-destructive, idempotent. Description adds critical behavioral details: composite call fans out to two external services, bundlephobia can take 5-30s on first measurement, and sources_failed lists timeouts, with graceful degradation.

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 detailed but well-structured, front-loading purpose and usage. Every sentence adds value, though slightly long. Could be trimmed slightly but remains clear.

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

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

Without output schema, description fully explains the return structure (summary block, per-advisory detail, links, alternative versions) and error handling (partial failures, sources_failed). Complete for a composite tool with two 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% with both parameters described. Description adds minor context (scoped packages accepted, version defaults to latest) but largely repeats schema descriptions. No significant added meaning beyond schema.

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

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

The description clearly states the tool is a composite check for deciding whether to add an npm package, specifying the resources checked (deps.dev, bundlephobia) and the return fields. It distinguishes itself from unrelated 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?

Explicitly says when to use (e.g., 'is X safe/popular/small' or 'what does adding lodash cost me') and provides exclusions for other ecosystems (PyPI, Maven, Cargo, Go) that should use deps.dev 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?

Discloses technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. 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?

Front-loaded with core action, then provides usage guidance and technical details. 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?

Completely covers input, output (passages with offsets and scores), technical behavior, cap, truncation, and pairing with another tool. No output schema, but description compensates fully.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value with concrete examples (e.g., SEC 10-K body for text, natural-language query examples) and clarifies limit's range and default, 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?

Clearly states semantic search inside a fetched record, specifies output (top-N passages with offsets and scores), and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and the use case of avoiding large prompts.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes pairing with ask_pipeworx_grounded, providing clear context for when to use this vs. alternative approaches.

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

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

The description adds significant behavioral context beyond annotations: requires OAuth account, returns subscription ID, explains always-on feed and optional delivery channels, rate limits (SMS 10/day), webhook auto-disable after 10 failures, and HMAC signing. No contradiction with annotations.

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

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

The description is well-structured: starts with purpose, then returns, requirements, type details with examples, and delivery channels. Every sentence adds value without redundancy. Length is appropriate 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?

Given the tool's complexity (multiple types, nested params, delivery options), the description covers all essential aspects: type semantics, filter structures, delivery behaviors, error conditions, and prerequisites. There is no output schema, but the description mentions return value.

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 substantially enriches parameter understanding by providing concrete examples for each type and clarifying constraints (e.g., SMS must match verified phone, webhook must be HTTPS). 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 new subscription ID. It specifies the verb 'create', the resource 'subscription', and differentiates from siblings like 'unsubscribe' and 'list_subscriptions' by detailing supported types and delivery channels.

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 this tool: requires OAuth account, explains each subscription type with examples, and covers delivery channels and their limitations (e.g., SMS 10/day cap, webhook auto-disable). However, it lacks explicit 'when not to use' statements, though context strongly implies appropriate uses.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds context about returning example questions and tool+argument shapes, but does not add significant behavioral details beyond the annotations.

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

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

The description is a single paragraph but packs essential information: common questions, output summary, argument options, and usage priority. It is front-loaded with typical user queries. Could be slightly more structured, but it is efficient and not verbose.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It fully explains the purpose, output content, calling conventions, and when to use it. There are no gaps given the tool's complexity.

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

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

Schema coverage is 100% with a description of the 'topic' parameter. The description adds examples of topics (e.g., 'finance', 'pharma') and explains that omitting it gives a full spread, but this does not add much beyond the schema's description. Baseline 3 is appropriate.

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

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

The description clearly states it is the onboarding entry point, returning category-bucketed example questions with exact tool+argument shapes. It explicitly distinguishes itself by being the first tool to use when the agent doesn't know what Pipeworx can do, setting it apart from siblings like ask_pipeworx or deep_research.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' giving clear when-to-use guidance. It also explains optional topic filtering. While it doesn't provide explicit when-not-to-use or alternatives, the context is strong 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?

Adds detail beyond annotations: mentions deactivation (not deletion) and that historical events remain available via recent_alerts. Annotations already indicate idempotency and non-destructiveness, so this supplements well.

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

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

Two succinct sentences, front-loaded with action and resource, followed by key constraints. 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?

For a simple one-parameter tool with no output schema, the description explains the effect and side effect sufficiently. Could mention error handling (e.g., unknown id) but not required for basic completeness.

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

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

Schema covers the only parameter (id) with full description ('Subscription id (uuid) returned by subscribe'). Description merely references 'by id', adding no new semantics. 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?

States 'Cancel a subscription by id' clearly. Distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the action and the deactivation behavior.

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

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

Explicitly states ownership enforcement ('only cancel your own subscriptions'), which guides when to use. Does not list alternatives but context from sibling names implies clear boundaries.

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

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description adds crucial behavioral context: could_not_verify means the check did not happen and must not be treated as evidence, unsupported means no source was covered, and it replaces a 4-6 step pipeline. No contradiction with annotations; external source access aligns with openWorldHint.

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

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

The description is dense but well-organized: it begins with trigger phrases, then covers usage, routing logic, return value semantics, critical caveats, and pipeline efficiency. Every sentence adds distinct, necessary information, and the structure is front-loaded with purpose.

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

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

Even without an output schema, the description fully explains what callers receive (verdict list, actual value with citation, reasoning) and how to interpret failure states (could_not_verify vs. unsupported). It also covers the internal routing and edge cases, making it 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% with rich, detailed descriptions for both the claim and tolerance_pct parameters, including default behavior and hallucination-detection usage. The tool description itself adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description uses specific verbs ('verify', 'fact check', 'check whether') and clearly identifies the resource: natural-language claims verified against authoritative sources. It further distinguishes itself by describing the financial vs. grounded pipelines and enumerating verdict types, making it distinct from generic QA 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?

Provides an explicit when-to-use instruction: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains routing for financial vs. other claims. However, it does not name sibling tools (e.g., ask_pipeworx_grounded) as alternatives or exclusions, so there is no explicit when-not-to-use.

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