Oqmd

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the default free model, the requirement to pass an _apiKey for Anthropic, direct cost implications, and the return structure with per-model fields and a combined view. This goes beyond the safety profile.

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 focused sentences, front-loaded with the primary action and output. It covers default behavior, optional external calls, return format, and use cases without excess. Every sentence adds value.

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

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

With no output schema, the description adequately explains the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers parameters, defaults, costs, and use cases. Minor missing details like what 'confidence' or 'signals' mean are not essential for invocation, so a 4 is appropriate.

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

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

Schema description coverage is 100% (all 4 parameters described in the input schema). The description repeats some parameter details (e.g., default model, _apiKey requirement) but does not add much new semantic information beyond what the schema already provides, hence the baseline score.

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 action ('Probe one or more LLMs'), the target ('business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes from siblings like scan_competitor_ai_presence by covering any entity, not just competitors, and by explicitly returning per-model scores.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default versus optional Anthropic probing behavior. It does not mention exclusions or explicitly compare to sibling tools, but the context is clear enough for an agent to decide when to use it.

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

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

Annotations already establish it as read-only, open-world, idempotent, and non-destructive. The description goes beyond this by disclosing the routing behavior, argument-filling, and the stable pipeworx:// citation URIs, which is valuable transparency for an agent deciding to invoke it.

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 and informative but bloated: it repeats the same example list and 'START HERE' guidance nearly verbatim, and ends with a garbled sentence about news feeds that adds little. Several sentences could be removed without losing meaning.

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

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

The description explains the data domains, usage triggers, routing behavior, and return format, which is enough for most invocation decisions. The main gap is the lack of mention of related sibling tools and when those might be more appropriate.

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

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

Schema coverage is 100%, with the 'question' parameter and all aliases already fully described in the schema. The description adds example queries but no additional parameter semantics 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 identifies the tool as a factual-question router that delegates to Pipeworx's 5,798 tools and returns structured answers with citation URIs. It is distinguishable from web search and general research, though it does not explicitly differentiate itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

The description gives explicit guidance: prefer over web search, use for factual queries, and START HERE for most questions, with concrete examples. It does not state when not to use this tool or mention alternatives among the 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?

This goes well beyond the readOnly/idempotent annotations by disclosing that the tool's routing behavior is variable: a candidate routing improvement may be live, or it may not be (currently none is). It also states that it currently matches ask_pipeworx exactly and that it falls back to nothing, meaning it is fully functional despite being experimental. This is precisely the kind of contextual behavioral nuance an agent needs.

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

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

The description is longer than average but nearly every sentence carries signal: beta status, exact equivalence, candidate testing behavior, current inactive state, and how to use it. The date is a minor detail that could be trimmed, but the overall structure is front-loaded and purposeful.

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 that is deliberately a byte-for-byte equivalent of ask_pipeworx, the description covers all relevant context: identical behavior, current exact match to stable, experimental variability, and full functionality. It also describes the response shape by reference to ask_pipeworx, which compensates for the lack of an output schema.

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

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

The schema description coverage is 100% per the context signals, so the schema already documents the parameters. The description says 'same arguments' as ask_pipeworx, which adds cross-tool context but does not provide per-parameter meaning. Baseline 3 is appropriate since the schema carries the load.

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, a universal router with identical tool coverage, arguments, and response shape. It differentiates it from the stable ask_pipeworx sibling by framing it as the 'experimental edge' with candidate routing improvements. This is a specific verb-plus-resource statement an agent can act on.

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

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

It explicitly says to use it exactly like ask_pipeworx when the agent wants the newest routing, and explains that results are compared against the stable router. It does not fully spell out 'use ask_pipeworx for stable production' as an exclusion, but the beta-vs-stable framing makes the intended selection context clear.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the exact success return shape, the explicit refusal shape, the possible refusal_reason values, the extra LLM call cost, and the guarantee that answers are derived only from the tool result. This is rich, actionable behavioral context.

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

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

Three dense sentences capture purpose, behavior, return/refusal shapes, usage rules, and the alternative tool. The main value is front-loaded, and every clause contributes necessary decision-making information.

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

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

Although there is no output schema, the description fully compensates by specifying the return object fields and refusal_reason enumeration. It also covers cost, routing behavior, and when to prefer the sibling tool, making the tool effectively self-contained for an agent.

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

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

Parameter schema coverage is 100%, and the schema already describes the question parameter, its natural-language form, and accepts aliases. The description adds no parameter-specific details beyond mentioning that routing fills arguments, so it meets the schema-heavy baseline without adding extra value.

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

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

The description states a specific verb and resource: it is a grounded, hallucination-resistant answer mode that fetches data and extracts answers only from tool results. It explicitly distinguishes itself from the sibling ask_pipeworx, easily separating its role from other research and lookup 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 gives explicit when-to-use guidance: use when answers will be quoted, cited, or acted on, and facts must not be invented, with examples. It also names the cheaper alternative, ask_pipeworx, and tells the agent to prefer it for casual lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial transparency: fan-out behavior, resolver contract with match confidence and alternatives, safety mechanisms (low-confidence short-circuit, closed-market status), parent-event extraction, news fallback details, and resolution-rule risk. This goes well beyond the annotations without contradicting them.

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

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

The description is long but well-organized with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. Some redundancy exists (e.g., repeated closed-market handling), but every section provides concrete value for a complex tool, so it earns a 4 rather than a 5.

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

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

Given no output schema, the description comprehensively explains return shapes (market, analysis, evidence), resolver contract, parent_event, news field fallbacks, and status codes. It even covers edge cases like illiquid spreads and cancellation rules, making it highly complete for the tool's complexity.

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

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

Schema description coverage is 100% for all 3 parameters, so the baseline is 3. The description provides contextual examples (slug, URL, question text) and explains how include_raw affects response size, but these largely mirror the schema's own parameter descriptions. No significant extra meaning is added beyond the schema, so it stays at baseline.

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

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

The description clearly states the tool's verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the scope (Polymarket bets) and differentiates from siblings by focusing on research/fan-out rather than arbitrage or edge tracking.

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

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

The description explicitly gives usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly mention when-not-to-use or name alternative sibling tools, but the guidance is clear and sufficient for most selection scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavior context: pulls from SEC EDGAR/XBRL and FAERS, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is longer but every sentence adds indispensable context. It front-loads user-intent examples then explains scope, data sources, and output, with no redundant or filler content.

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

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

Despite lacking an output schema, the description adequately explains return contents ('paired data + pipeworx:// citation URIs per entity'), data sources, and edge-case handling (off-calendar fiscal years). This is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and both parameters have descriptions. The description enriches 'type' and 'values' with concrete examples (AAPL, MSFT, ozempic), clarifies that company values are tickers/CIKs and drug values are names, and explains how results are sorted by primary metric, adding value beyond the schema.

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

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

The description clearly states it performs 'side-by-side comparison of 2–5 companies or drugs' with a specific verb and resource. It distinguishes itself from sequential lookups and aligns with the 'compare' trigger phrases, making its purpose 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 says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a direct when-to-use directive and naming the alternative. It also lists multiple query formulations that should invoke 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 mark the tool read-only, open-world, idempotent, and non-destructive, and the description adds high-value behavioral context: account and paid-tier requirements, parallel routing to 5,798 tools, verbatim evidence with citations, explicit gaps[], contradictions[] behavior, semantic excerpting, and expected latency. 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 every sentence earns its place: access requirements, the fallback to ask_pipeworx, the scope boundary, the research mechanism, the return packet, use cases, and latency. Important constraints are front-loaded before deeper 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?

There is no output schema, so the description carries the burden of explaining return values. It names the findings packet fields, gap and contradiction behavior, citation resolvability, excerpting, and latency — enough for an agent to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description mostly reinforces what the schema already says about 'question' and 'depth', adding only the account-tier note for 'thorough'. It does not introduce substantial new parameter-level semantics 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call — this is NOT open-web search.' It clearly explains the tool's decomposition-and-parallel-routing behavior and distinguishes it from a generic search or a single-lookup tool.

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

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

It explicitly says 'Best for broad/multi-part questions over structured data' and gives example queries. It also provides two clear exclusion rules: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.'

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses the behavior of returning top-N relevant tools with names, descriptions, and full input schemas, plus curated examples, and that each result is directly callable without a second schema lookup. This adds concrete behavioral context beyond the annotations.

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

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

The description is moderately sized but well-structured, starting with the core purpose, then usage scenarios, then return details, and ending with when to call it. Every sentence provides useful information, though it could be tightened slightly without losing meaning.

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

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

With no output schema, the description adequately explains the return value: it returns top-N tools with names, descriptions, full input schemas, and curated examples. It also explains the 'call first' behavior. For a simple discovery tool with one required parameter, this is 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%, and each parameter already has a detailed description with examples. The tool description adds little beyond what the schema provides, but it does reinforce the natural-language nature of the query and mentions the limit parameter's role in returning 'top-N'. This matches the baseline of 3 for high coverage.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('Find') and resource ('tools'), and distinguishes itself from sibling tools by framing it as a discovery tool that returns the option set, with the explicit instruction to 'Call this FIRST when you have many tools available.'

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 says when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and explicitly instructs to 'Call this FIRST when you have many tools available and want to see the option set.' It does not mention when not to use it, but the 'FIRST' guidance implies it is preliminary to direct tool use.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds substantial behavior beyond that: fan-out mechanics, soft-fail behavior for USPTO patents, the expectation that missing FDA products is normal, private-company resolved:false semantics, resolved_from/resolved_to behavior, and what sources_used/sources_failed mean.

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

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

The description is long but every clause carries important behavioral or routing information. It is front-loaded with purpose and examples, then systematically covers return fields and edge cases. It could be more structured with bullets, but the density is justified for a tool with this much output complexity.

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

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

With no output schema and only two simple params, the description carries the full burden of explaining what the agent will receive: every major response section is named, failure semantics are described, and expected empty results are distinguished from bugs. Nothing needed to call this tool correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description enriches parameter meaning by explaining that type 'company' and 'ticker' are interchangeable despite different enum values, that value may be a ticker, CIK, or company name, and that names resolve via SEC EDGAR. This reduces ambiguity 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 states a specific action — build a 'full cross-source profile of a US public company in ONE parallel call' — with concrete user-phrase examples ('brief me on Tesla', 'company profile for Microsoft'). It clearly identifies the resource (SEC, XBRL, patents, contracts, FDA, H-1B, news, GLEIF) and distinguishes itself from narrower single-source lookups.

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

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

It explicitly says to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This gives strong selection guidance. It does not name sibling tools like resolve_entity or compare_entities for narrower needs, but the holistic-view condition is clear enough for most routing.

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

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

Annotations already declare destructiveHint and readOnlyHint, so the bar is lower. The description adds the memory context and sensitive data nuance, consistent with annotations, but doesn't reveal additional behavior beyond what is already known.

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, action first, zero filler. Every word earns its place.

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

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

With a single parameter, complete schema, and clear annotations, the description covers all necessary selection and invocation context. It could mention irreversibility, but the destructiveHint annotation already covers 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?

Schema coverage is 100%, so baseline is 3. The description only says 'by key' and adds no extra meaning beyond the schema's 'Memory key to delete'.

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 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself from siblings by explicitly mentioning pairing with remember and recall.

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

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

The description gives explicit when-to-use guidance: stale context, task done, or clearing sensitive data. It also references companion tools, providing context, though it lacks when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety traits. The description adds valuable process context: fetching the page, extracting content, and emitting markdown. It also clarifies the output is a single text blob. It does not discuss edge cases (e.g., inaccessible URLs) but adds meaningful transparency beyond annotations.

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

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

The description is three sentences, front-loaded with the core action, and contains no fluff. Every sentence contributes purpose, process, or context.

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

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

For a simple 2-parameter tool with no output schema, the description explains inputs, process, output format, and use cases. It does not mention error handling or limitations, but it covers the essential information needed to use the tool effectively.

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

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

Schema description coverage is 100%, with both parameters clearly documented. The description does not add extra parameter-specific details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It explains the process (fetches, extracts, emits) and distinguishes itself from all sibling tools by describing a unique function. The use cases further reinforce its purpose.

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 'Useful for' scenarios, which give clear context on when to use the tool. However, it does not mention alternative tools or when NOT to use it, so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds useful behavioral context such as 'Keyless' (no auth needed) and enumerates the return fields, which goes beyond the annotations. No contradictions.

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

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

Two sentences, with the purpose front-loaded, followed by a compact list of return fields and a keyless note. Every word earns its place with zero 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 single-parameter, read-only material fetch, the description covers what it returns, the key type, and authentication status. The absence of an output schema is mitigated by the enumerated return fields, making it complete for this low-complexity tool.

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

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

Schema coverage is 100%, so the schema already documents entry_id thoroughly with an example and source guidance. The description's example (16525) adds a tiny bit of context but largely duplicates the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool 'Fetch a single OQMD material by its entry_id' with a concrete example, distinguishing it from search-like siblings such as search_materials. The verb+resource+key is specific and unambiguous.

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

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

The description and schema together imply usage context: you need an entry_id from previous search results, as stated in the parameter description ('Get ids from search_materials results'). However, it doesn't explicitly contrast with alternatives like stable_phases, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond these by noting it lists the caller's own subscriptions and specifying the default behavior (active only). This is useful behavioral information not present in 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 exactly two sentences: the first states the action, resource, and return fields; the second gives usage guidance. Every sentence contributes value, and the structure is front-loaded with the most important information.

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

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

The tool is simple, with one optional parameter and no output schema. The description covers the action, scope, return fields, and practical usage scenarios. Combined with the annotations, it gives an agent everything needed to select and invoke the tool correctly.

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

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

The schema has 100% coverage for the single include_inactive parameter, including its default value. The description does not add extra meaning beyond the schema; it only implies the default behavior. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions.' It distinguishes the tool from sibling actions like subscribe/unsubscribe and enumerates the returned fields, 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?

It explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' giving concrete scenarios for usage. However, it does not explicitly state when not to use it or name alternatives like subscribe/unsubscribe, so it falls just 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?

Even though annotations provide no hints (all false), the description discloses key behaviors: returns a claim_token when filing without an account, allows later lookup with that token, and includes 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' This goes 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 packed with necessary information and front-loaded with the core purpose. However, sentences like 'The team reads digests daily and signal directly affects roadmap' are motivational rather than essential for tool invocation, keeping it from a 5.

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

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

For a tool with no output schema and moderate complexity (4 params, nested object), the description covers all necessary guidance: what to report, how to scope feedback, the token mechanism, rate limits, and exclusions. It is fully self-contained and leaves no significant gaps for an agent to misuse it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how claim_token is used ('Filing without an account returns a claim_token; pass it back later...') and by instructing on message content ('don't paste the end-user's prompt'). This raises it to a 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the verb and resource. It also distinguishes itself from siblings by specifying it is for feedback about Pipeworx tools only, not other MCP servers.

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

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

Provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (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 an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description goes further by revealing it is a self-aggregating signal derived from CF analytics-engine, guaranteein no PII (only pack, tool, count), and explaining caching behavior (5min-1h). This adds meaningful context about data provenance, privacy, and freshness beyond the structured annotations.

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

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

The description is compact and efficient: a clear hook, explicit outputs, a numbered list of use cases, and a final sentence on data source, privacy, and caching. Every sentence earns its place, and the structure makes it easy to scan.

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 only one optional parameter, no output schema, and comprehensive annotations, the description covers core behavior, use cases, data provenance, privacy, and freshness. The agent receives enough context to decide when and how to invoke the tool without needing additional 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?

The single 'window' parameter is fully documented in the schema with enum values and a description of the trade-off between short and long windows. The main description only repeats '24h, 7d, or 30d' without adding extra semantic meaning, so the schema carries the weight, and 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 a clear question ('What other AI agents are calling on Pipeworx right now') and then specifies the returned content (top tools, top packs, total call volume) over selectable windows. This clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx by focusing on aggregated agent call trends.

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 'Useful for' list provides three concrete scenarios (discovering hot data sources, confirming a canonical tool, aligning with agent demand), giving clear context on when to use it. However, it does not explicitly mention when not to use it or name alternative tools, 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?

Despite annotations already indicating readOnlyHint=true and idempotentHint=true, the description goes far beyond by detailing internal checks (semantic anchor requiring ≥0.30 Jaccard similarity, partition filter dropping placeholder slugs), response structure, and the fill check caveat: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' This is rich behavioral context that is not present in annotations.

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

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

The description is long but well-structured with explicit section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every section adds necessary detail. It could be slightly tighter without losing critical caveats, so it earns a 4 rather than 5.

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

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

Given the tool's complexity (three modes, multiple filters, and a fill check) and the absence of an output schema, the description fully compensates by detailing response fields, the partition_check object, and the fill-check pricing logic. It also directs users to polymarket_fill_risk for custom sizing, covering the full usage context.

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

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

Schema coverage is 100%: both 'event' and 'topic' have descriptions in the schema. The tool description adds value by explaining the mode selection rationale (which to use when), providing example slugs and seed questions, and clarifying that full URLs are accepted. This goes beyond the schema's brief descriptions, earning a 4.

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

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

The description opens with a specific, non-tautological statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by naming the arbitrage focus and three distinct modes (trending_scan, event, topic), and even references polymarket_fill_risk for custom sizing, which separates it from that 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?

Provides explicit when-to-use guidance: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)', along with concrete examples. It also states when NOT to use the tool: 'For custom sizing use polymarket_fill_risk.' Additionally, it explains why cross-event mode is valuable and what it catches that single-event misses.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial context: the three-segment output structure, the five model families and their assumptions, the 24h-move warning ('your edge may already be in the price'), caching behavior, and the diagnostics funnel. This goes far beyond what annotations convey.

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

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

The description is long but front-loaded with a clear purpose. It uses structured segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and logically organizes knobs and response fields. While dense and containing long parenthetical asides, it is appropriately sized for a tool with 9 parameters and complex output semantics.

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

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

There is no output schema, so the description must explain return values. It does so thoroughly: the by_segment structure, opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp), diagnostics funnel, and cache keying. It also explains the rationale behind exclusions and design decisions, making it a complete description 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%, so the baseline is 3. The description adds semantic value by grouping knobs as 'TRADEABLE-EDGE KNOBS', explaining how min_partition_leg_kelly applies per-leg while parent-level Kelly is zero, and contextualizing slippage_pp with Polymarket fee information. This enriches understanding 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and even names the intended use case ('what should I bet on today'). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, even though alternatives are not explicitly named.

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 'Built for "what should I bet on today"' and explains the benefit of discovering opportunities without paging hundreds of markets. It also provides exclusion reasoning for Fed bets and detailed guidance on when to adjust knobs like min_liquidity and max_spread_pp. It lacks an explicit 'use this instead of X' statement but the contextual guidance is strong.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds meaningful behavior details beyond annotations: 60-day snapshot TTL, snapshot gaps on cache-miss, computation on daily closes rather than intraday, and lifespan as a competition clock. 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 long but highly structured with labeled sections (Args, RESPONSE, LIMITS) and no filler or repetition. Each sentence adds unique information about purpose, parameters, response structure, or limitations, making the length justified.

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 compensates by detailing the response shape (tracked[], expired[], snapshot_dates[]) and field meanings. It also covers edge cases like snapshot gaps, TTL constraints, and computation methodology, making the tool predictable for an agent.

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

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

Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description adds value by explaining the practical role of 'days' (lookback) and 'window' (snapshot family) and clarifying defaults ('default 14', 'default 1wk'), slightly extending the schema's clamp range detail.

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' and answers a specific question about edge age and shrinkage. It distinguishes itself from sibling polymarket_edges by emphasizing historical tracking across snapshots rather than current edges.

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

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

The description gives strong contextual guidance ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains when the tool is relevant for evaluating opportunities. It references polymarket_edges as the source but does not explicitly name alternative tools or state when not to use this tracker.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond by disclosing exactly how the tool simulates fills: walking the order book ladder, returning fill metrics (top_of_book, vwap_fill_price, slippage_pp), computing basket-level capture_ratio, and explicitly warning about thin_legs and forced_directional_risk. It explains partial-fill risks and why the tool exists, which is meaningful 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 information-dense but well-structured, with the core purpose in the first sentence, followed by REQUIRES, then clear SINGLE-MARKET and BASKET sections, and ending with a prescriptive 'USE THIS' rule. Every sentence earns its place; no filler. Despite its length, the complexity of two modes justifies the detail.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly lists single-market returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket returns (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers edge cases like thin legs and partial fills, making it complete for a complex dual-mode 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?

Even though schema coverage is 100%, the description enriches every parameter with mode-specific meaning. For example, size_usd is detailed as 'max spend on buys, target proceeds on sells' in single-market mode, and as 'settlement notional — shares per leg' in basket mode. It also clarifies side defaults (buy_yes or auto-detect from partition sum) and the interpretation of market vs event. This adds real semantic depth beyond the schema.

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

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

The description opens with a precise, specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and references sibling tools (polymarket_arbitrage, polymarket_edges), so an agent can immediately understand what this tool does and how it differs.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create unhedged positions), covering the 'when' clearly and implicitly defining the 'when not' (small trades or where full execution is guaranteed).

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations, explaining matching limitations, compatibility warning semantics, fee treatment (gross spread not net), null temporal_alignment meaning, and which leg types are never paired. This is substantial behavioral disclosure that helps an agent interpret results correctly.

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

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

The description is long but information-dense, covering response fields, safety codes, fee caveats, and counter semantics without fluff. It is front-loaded with the core concept and mode selection, though a bit of visual structure (section breaks for SAFETY FIELDS, RESPONSE, MODES) would improve scannability.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It covers raw probabilities, top_spreads_pp, compatibility codes, per-entry flags, skipped counters, fees_note, and temporal_alignment semantics. An agent has enough information to correctly invoke the tool and interpret ambiguous results.

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

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

Input schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful context beyond that: topic mode uses pre-mapped shortcuts, kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, and both modes run the same matcher. This elevates it above the baseline.

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

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

Description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself by naming both venues, the comparison outcome, and the two distinct modes of operation. This is sufficient to differentiate it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Gives explicit instructions for the two modes (topic shortcuts vs explicit ticker+slug) and warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not explicitly name alternatives among sibling tools, but the mode guidance and caveats make appropriate usage clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving vs. listing all keys. It does not detail edge cases like missing key behavior, but annotations cover the safety profile.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value: function, use case, scoping, and relationship to sibling tools. No redundant or filler content.

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

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

The tool is simple (1 optional parameter, no output schema). The description sufficiently covers behavior, scoping, and usage. While the exact return format is not specified, for a memory retrieval tool it is implicitly whatever was saved, and the list behavior is mentioned. Overall adequate and 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 the key parameter clearly described as 'omit to list all keys'. The description reinforces this behavior and adds concrete examples of typical key values (target ticker, address, research notes), providing semantic context beyond the schema.

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

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

The description clearly states the tool's function: retrieve a previously saved value or list all saved keys. It uses specific verbs and identifies the resource (saved memory via remember). It also distinguishes itself from siblings by explicitly referencing remember and forget.

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

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

It provides explicit context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also notes the alternative of omitting the key to list all keys and mentions pairing with remember (save) and forget (delete).

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

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

Annotations declare readOnlyHint:true, but the description explicitly says mark_read:true 'flag[s] returned events read so the next call only shows newer ones'—a persistent side effect. This directly contradicts the read-only annotation, so despite rich behavioral detail, the contradiction forces a score of 1.

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

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

The description is front-loaded with the purpose and uses a few well-structured sentences. Each sentence contributes useful details (return fields, filtering, mark_read behavior, HTTP alternative), though the last sentence about the registry URL could be seen as slightly tangential for the tool's core use.

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 5 optional parameters and no output schema, the description adequately explains the return items, filtering options, mark_read side effect, and even provides an external endpoint. It doesn't cover limit or unread_only, but the schema fills those gaps; the contradiction with annotations keeps it from a 5.

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 covers all 5 parameters with descriptions, so baseline is 3. The description adds value by giving an example type ('sec_8k'), explaining the since parameter as an ISO timestamp, and clarifying that mark_read causes the next call to return only newer events—semantic nuance beyond the schema.

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

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

The description opens with a specific verb ('Pull') and resource ('fired events from your subscription feed'), and clearly states the return payload. It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired alerts from the evaluator's feed.

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

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

The description gives clear context: it's for pulling recent alerts, supports polling, and mentions an HTTP alternative for scripts/dashboards. However, it doesn't explicitly contrast with sibling tools or state when not to use this tool, so it falls just short of full guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO with a soft-fail note), and specifies the return structure (changes[] grouped by source + total_changes + citation URIs). It also explains the fallback conditions (rate-limited or 5xx) and the API sunset, which are important behavioral traits not captured in annotations.

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

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

The description is dense but well-organized, front-loading with query examples before the core definition. The middle section packs source details, fallback behavior, and date formats, and the final sentence provides the sibling-tool pointer. While the initial example list is somewhat redundant, every sentence earns its place given the tool's complexity; a 4 reflects minor excess but strong structure.

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

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

Given there is no output schema, the description compensates by specifying the return payload (structured changes[], total_changes, pipeworx:// citation URIs). It also covers edge cases (GDELT→GNews fallback, USPTO soft-fail until reactivated) and clarifies the `since` window formats. For a tool with three required parameters and this complexity, the description is complete enough to guide correct invocation and expectation-setting.

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

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

Schema coverage is 100% with descriptions for all three params. The description adds substantial extra meaning for `since` by giving concrete formats (ISO date or '7d', '30d', '3m', '1y') and a recommendation ('Use 30d or 1m for typical monitoring'), which goes beyond the schema's phrasing. The other parameters are already well-described in the schema, so the description adds marginal but useful 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 opens with a list of natural-language query examples and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly differentiates from the sibling entity_profile by directing users to that tool for static profiles, making the purpose 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?

The description explicitly gives when-to-use cues (queries like 'what's new with X', 'latest on Y') and provides an explicit alternative: 'Use entity_profile instead when you want the static profile...'. It also offers parameter-level guidance, recommending '30d' or '1m' for typical monitoring. This is clear usage guidance with exclusions.

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

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

Descriptions adds significant behavioral context beyond annotations: storage is 'scoped by your identifier', authenticated users get persistent memory, anonymous sessions retain for 24 hours. This exceeds the safety flags and gives the agent critical persistence semantics.

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?

Five sentences, each earning its place: opening purpose, when to use, storage model, persistence details, and sibling pairing. Front-loaded with the verb and resource, no fluff or repetition.

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

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

For a simple two-parameter tool with no output schema, the description fully covers purpose, usage, storage behavior, and related tools. No gaps remain for the agent to safely invoke this tool.

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

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

Input schema already covers 100% of parameters with descriptions and examples. The description reinforces these with additional use-case examples but does not add new semantic meaning beyond the schema. 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 clearly states the action: 'Save data the agent will need to reuse later' and identifies the resource as key-value memory scoped by identifier. It also distinguishes from siblings by explicitly pairing with 'recall to retrieve' and 'forget to delete', making the tool's role 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?

Provides explicit when-to-use context with concrete examples ('a resolved ticker, a target address, a user preference') and explains the benefit ('so you don't have to look it up again'). It names alternatives (recall, forget) but lacks explicit when-not-to-use exclusions, preventing 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?

Despite the annotations already declaring readOnlyHint and idempotentHint, the description adds substantial behavioral detail: it asserts nothing when a name matches multiple instruments and instead returns figi_candidates; it explicitly reports unresolved identifiers rather than omitting them; and it degrades gracefully when GLEIF or OpenFIGI is unavailable. These are meaningful, non-obvious behaviors beyond what annotations convey.

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

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

The description is long but tightly structured: it opens with examples, states the primary directive, then organizes the remaining detail under 'SUPPORTED TYPES' with practical caveats. Every sentence adds operational value—matching behavior, unresolved handling, graceful degradation, and input formatting warnings all earn their place.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains what identifiers will be returned, how ambiguous matches are handled, what appears in the unresolved field, how ISINs map to legal entities, and how failures degrade. An agent has enough context to invoke resolve_entity correctly without additional discovery.

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?

Although schema coverage is 100%, the description adds significant semantic value beyond the schema: it documents accepted value forms with concrete examples (AAPL, 0000320193, ozempic), explains the bond-issuer phrasing pitfall ('never the question's full noun phrase'), and clarifies how the type parameter changes the resolution path. It goes well beyond the baseline schema coverage.

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

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

The description leads with user-phrase examples and immediately states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly differentiates this from siblings by framing it as the first-step lookup tool ('Use FIRST whenever you have a name but need an ID'), and it enumerates the exact entity types it handles.

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: 'Use FIRST whenever you have a name but need an ID' and notes that each call internally cascades through multiple lookups, replacing 2-3 manual steps. It does not name alternative tools to use when this one is not appropriate, so it stops short of full when-not/alternatives coverage.

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

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

With annotations already declaring the tool as read-only, idempotent, and non-destructive, the description adds meaningful behavioral context: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and gives insight into the tool's internal methodology and output, though it doesn't disclose potential rate limits or error behavior.

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

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

The description is three sentences, front-loaded with the core action, and includes a concrete example. Every sentence adds value—stating the function, the underlying mechanism, a use case, and the return format—with no redundancy or filler.

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

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

Despite having no output schema, the description covers the return format (ranked list with score, confidence, signal density). Combined with the schema's full parameter documentation and annotations covering safety, the description provides a complete picture for an agent to invoke the tool correctly. It doesn't mention edge cases like rate limits or failure handling, but these are less critical given the tool's read-only nature and the provided context.

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

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

Schema description coverage is 100%, with detailed parameter descriptions (e.g., 'First entry treated as the subject...' for entities). The description adds minor semantic reinforcement by framing entities as 'your brand + N competitors' and mentioning the probe mechanism, but it doesn't significantly augment what the schema already provides. 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 clearly states the tool compares AI visibility across multiple entities, with a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It distinguishes itself from the sibling ai_visibility_check by explicitly saying it probes each entity with that tool and ranks results, making the purpose 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?

The description provides a clear use case ('competitive AI-marketing audits') and an example query, effectively conveying when to use the tool. It indirectly references the alternative ai_visibility_check by explaining this tool probes each entity with it, but it doesn't explicitly state when not to use it or name other alternatives like compare_entities, so it falls 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?

Beyond the annotations (readOnly, idempotent), the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and the sources_failed field will indicate timeouts. This is important operational 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 dense but well-structured: purpose, usage, return value summary, ecosystem scope, and failure behavior each get a sentence. No wasted words; all information earns its place.

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

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

Given the tool's complexity (composite of two external APIs) and no output schema, the description covers the key return fields, per-advisory details, links, version alternatives, ecosystem limits, and partial failure semantics. This is sufficient for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add much beyond the schema: it reiterates npm package name and default version behavior, but adds no new parameter-specific semantics. The latency note for new versions is a minor addition.

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

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

The description clearly states the tool's purpose: a composite check for 'should I add this npm package to my project', combining deps.dev and bundlephobia data. It uses a specific verb ('scan'), names the resource (npm package), and distinguishes from siblings like scan_competitor_ai_presence.

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

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

Explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides an exclusion: for non-NPM ecosystems, it directs to use deps.dev:version directly, giving clear 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context by listing specific returned fields (formation energy, hull distance, band gap, space group, prototype), clarifying keyless access, and specifying the input constraint. 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?

Three tight sentences: purpose, return fields, and key constraint. No filler, front-loaded with the most important information.

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

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

For a search tool with no output schema, the description covers what is returned, how to filter, and input requirements. Minor gaps like sort order or default limits are not critical since limit is in the schema.

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

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

Schema coverage is 100% and each parameter is well described. The description adds the decisive 'at least one of composition or element_set' rule and explains the meaning of the stability filter in terms of convex hull distance, which enriches the schema's flat 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 uses a specific verb 'Search' with an explicit resource (Open Quantum Materials Database) and identifies query dimensions (composition, elements) and filters. This clearly distinguishes it from siblings like get_material (likely retrieving by ID) and stable_phases.

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

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

States a clear prerequisite: 'Provide at least composition or element_set', and notes keyless access. It doesn't explicitly name alternative tools, but the usage context is clear from the description.

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/idempotent hints, the description discloses technical specifics: 'BGE-base-en embeddings + cosine over 500-char overlapping windows', a 200K-char limit with truncation flagging, and that the output includes 'character offsets and similarity scores' so the agent can verify verbatim quotes. These details add significant transparency and 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 dense but well-structured: main purpose first, then usage context, then implementation details. Every sentence adds value, though the length is slightly more than necessary. The section on embedding/window mechanics could arguably be condensed, but it's relevant for behavioral transparency.

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

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

With no output schema, the description compensates by explaining what is returned (passages with offsets and similarity scores), the constraints (character cap), and how it fits into a larger workflow. It is complete for an agent to use effectively without further documentation.

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

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

The schema covers 100% of parameters with detailed descriptions (e.g., query examples and limit range). The description adds marginal context (e.g., 'text you already pulled') but largely repeats schema information. It does not meaningfully enrich parameter understanding beyond the baseline.

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

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

The description uses a specific verb ('Semantic search INSIDE a fetched record') and clearly identifies the resource (a record's text). It distinguishes from sibling tools by emphasizing the 'already pulled' text and the search-within behavior, contrasting with global tools like search_materials.

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

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

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt' and it names an alternative/complement (ask_pipeworx_grounded) with a concrete pattern: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This clearly tells the agent when to use it and how it pairs with a sibling.

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

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

Despite annotations already marking readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral context: the stability criterion (<= ~0), the exclusivity of elements, and the 'Keyless' access. This goes well beyond the annotations and informs the agent about filtering behavior and authentication needs.

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: the first states the purpose and gives an example, the second adds constraints. Every sentence earns its place, and it is perfectly front-loaded. 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?

The tool has no output schema, but the description provides a concrete example of return values (FeO, Fe2O3, Fe3O4), states the selection criteria, and mentions 'Keyless'. Combined with strong annotations, this is fully complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'elements' parameter meaning with an example and emphasizes 'ONLY', but it does not add new syntax, formatting details, or limit constraints beyond what the schema already provides.

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

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

The description clearly states the tool lists ground-state (on-hull) phases of a chemical system, with a specific verb ('List'), resource ('phases'), and scope ('thermodynamically stable compounds in OQMD'). The example ('Fe-O' returns FeO, Fe2O3, Fe3O4) solidifies understanding and distinguishes this from sibling tools like search_materials.

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

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

The description implies when to use this tool: to retrieve stable phases for a given element set. It adds the key constraint 'materials made ONLY of the given elements' and notes 'Keyless' (no auth). However, it does not explicitly name alternatives or state when not to use it, so it falls 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?

Goes well beyond the annotations by disclosing auth requirements, delivery channel behavior, SMS caps, phone verification, webhook HMAC signing, one-time secret return, and auto-disable after 10 consecutive failing runs. 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?

Although lengthy, every sentence contributes necessary information. The description front-loads the core action and return value, then organizes types, delivery, and requirements in a logical, scannable manner.

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, optional delivery channels), the description covers all critical aspects: use cases, prerequisites, parameter examples, delivery details, error conditions, and return value. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing real-world examples (e.g., items:["5.02"] for officer change, series_id:"UNRATE") and explaining the semantics of each type and delivery option beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation, and it enumerates the supported subscription types.

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

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

Provides strong context for when to use the tool (proactive monitoring) and prerequisites (OAuth account, verified phone for SMS), but does not explicitly contrast it with alternatives like list_subscriptions or recent_alerts. The differentiation is implied rather than stated.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds behavior beyond that: it returns category-bucketed examples 'drawn from the live catalog of thousands of tools' and notes that each example includes the exact tool + argument shape. This immediately communicates the tool's open-world, advisory nature without contradicting the annotations.

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

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

The description is long but every sentence carries meaningful information: entry-point purpose, example queries, return structure, parameter options, and explicit first-use guidance. It is front-loaded with example user questions, making the tool's intent instantly recognizable, and remains dense 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?

Given the tool's open-ended onboarding role and lack of an output schema, the description is fully complete: it explains what output to expect (category-bucketed examples with tool+argument shape), how to adjust scope (topic vs. no args), and when to use it (first contact, meta-tool learning). No critical use-case information is missing.

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

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

Schema description coverage is 100%, and the schema already explains `topic` as an optional focus area with a list of values and the omit-for-spread behavior. The description's mention of 'e.g. finance, pharma, betting' adds small illustrative value but does not fundamentally extend the schema semantics; the description and schema essentially say the same thing.

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

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

The description clearly identifies the tool as the onboarding entry point for a newly connected agent, with specific verbs ('Returns category-bucketed example questions') and resource ('example questions... with the exact tool + argument shape'). It distinguishes itself from siblings by stating 'Use this FIRST' and by focusing on the discovery of what Pipeworx can do, rather than executing a specific query.

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 when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides usage variants: 'Call with no arguments for the full spread, or pass `topic`... to focus'. It names alternative meta-tools (ask_pipeworx, entity_profile, compare_entities), giving clear guidance on this tool's role.

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 detail beyond the annotations: ownership enforcement, deactivation instead of deletion, and the link to historical events via 'recent_alerts'. This complements the annotations (destructiveHint=false, idempotentHint=true) without contradicting them, giving the agent a clear picture of side effects.

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

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

The description is two sentences, front-loaded with the core action ('Cancel a subscription by id'), followed by two high-value behavioral notes. Every sentence earns its place; there is no fluff or repetition.

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

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

For a single-parameter tool with no output schema, the description covers the essential aspects: what it does, who can use it, and what happens to the data. It also references 'recent_alerts' for post-cancellation visibility, making the behavior predictable. The annotations enrich this further, so the tool is fully specified for an agent.

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

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

The schema already describes the 'id' parameter completely ('Subscription id (uuid) returned by subscribe'), achieving 100% coverage. The description only says 'by id', adding no new meaning. Per the rubric, high schema coverage yields a baseline of 3, and no extra parameter insight is provided.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Cancel a subscription by id.' This distinguishes it from sibling tools like 'subscribe' (create) and 'list_subscriptions' (query). The action is unambiguous and directly tied to the tool name.

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

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

The description implies the usage context: use when you need to cancel a subscription, and clarifies ownership constraints ('you can only cancel your own subscriptions'). It also indicates a key consequence (deactivation, not deletion). However, it does not explicitly name alternatives or exclusions, 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?

Extensive behavioral disclosure goes far beyond the annotations: it explains the verdict types, the meaning of 'could_not_verify' (with verification_error and that it is not evidence), and 'unsupported'. This adds critical context for interpreting results, which the readOnlyHint/openWorldHint annotations do not convey.

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

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

The description is long but densely packed with essential information: query examples, the financial-vs-other path, verdict meanings, and caveats. It is well-structured and front-loaded with usage triggers, though it could be slightly tightened without losing value.

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

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

For a tool with no output schema, the description thoroughly explains the return values (verdicts, actual value, citation, reasoning) and error states (could_not_verify vs unsupported). It also notes the efficiency gain over multiple sequential calls, making it fully contextual for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic value by explaining how tolerance_pct overrides the claim's implied tolerance and suggesting specific values for hallucination detection, which is not fully captured in the schema's parameter description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with examples of query phrasing. It distinguishes itself from siblings like deep_research or bet_research by focusing on fact-checking, and explicitly differentiates between company-financial claims (via SEC EDGAR) and other factual claims.

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 whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. It also explains that non-financial claims fall through to a grounded pipeline, but it does not name alternative sibling tools or explicitly state when not to use this tool, earning a 4 rather than a 5.

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