holidays

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

Beyond the readOnly/idempotent annotations, the description discloses cost implications (BYO key, pay Anthropic directly), default model selection, and the fact that _apiKey is passed through to api.anthropic.com. No contradiction with annotations.

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

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

Front-loaded with the core purpose, then adds essential details in a compact 3-sentence format. Every sentence contributes meaning, and there is no redundant verbiage.

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 summarizing the return structure (per-model object + combined view) and enumerating typical use cases. It could mention potential rate limits or error behavior, but for a read-only probe the coverage is strong.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model for 'models', the necessity of '_apiKey' only when 'anthropic' is included, and the semantic effect of 'context' (disambiguation). This goes beyond the schema field 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 ('probe') and resource ('LLMs') with a clear deliverable (visibility score 0-100 per model). It distinguishes itself from sibling tools by focusing on probing multiple AI models for brand/business awareness, which is distinct from generic ask 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?

Explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs optional model invocation. However, it does not provide when-not-to-use guidance or name alternative tools, leaving some ambiguity for selection among similar siblings.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful behavior beyond those annotations: it routes to one of 5,596 tools, fills arguments, and returns structured answer with stable pipeworx:// citation URIs. This tells the agent what kind of output to expect and why results are citable.

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

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

The description is dense but well-organized: it leads with the most important directive, explains mechanism, gives concrete examples, and closes with a caveat about alternatives. Every sentence earns its place; the length is justified by the tool's large scope.

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 a single meaningful input parameter and no output schema, the description is complete. It tells the agent when to use it, what it does internally, what kind of answer to expect, and which other tools to consider. No critical information appears missing.

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

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

Schema description coverage is 100%, so the schema already documents the single natural-language question parameter and its aliases. The description provides helpful examples of valid questions, but it adds little new semantic meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly identifies ask_pipeworx as a natural-language factual-data router that should be preferred over web search for current or historical data. It enumerates domains, gives concrete question examples, and distinguishes itself from alternatives like deep_research and ask_pipeworx_beta. An agent can tell exactly what this tool is for.

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

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

The description provides explicit when-to-use guidance: prefer over web search for factual questions, even when web search could answer. It lists trigger phrases and examples, and it names the alternatives to consider instead (deep_research, ask_pipeworx_beta). This is unusually actionable usage 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 readOnly/openWorld/idempotent/destructive annotations, the description discloses the experimental, variable nature of the tool: candidate routing improvements may be enabled live, results are compared against the stable router to inform merging, and there is no fallback because it is a full working router. This gives essential behavioral context an agent needs to understand the high-precision experimental state.

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 cover identity, current state, usage, comparison purpose, and fallback behavior without padding. The length is justified by the need to explain an experimental beta routing. It is not overly verbose, and every sentence increases understanding.

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

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

The description provides critical context about the beta nature, current equivalence to ask_pipe_concord, and comparison behavior. Since there is no output schema, it references the same response shape as ask_pipeworx, which is a useful pointer. The main gap is that it does not independently describe what the returned response looks like, relying on the sibling tool's definition, but the overall context is still adequate for a comparable task.

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

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

Schema coverage is 100% and every parameter is documented as an alias for 'question'. The description adds no parameter-specific semantics beyond saying the same arguments as ask_pipeworx are accepted. Since the schema already fully describes each parameter, this meets the baseline but provides no additional 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 identifies the tool as a beta version of ask_pipeworx with the same universal router, same arguments, and same response shape, making its role and relationship to siblings clear. It specifies its experimental edge and that it currently matches ask_pipeworx exactly. It does not define the underlying 'universal router' behavior from scratch, but that is acceptable given the explicit sibling reference.

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 directs the user to 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that no candidate is active, so current behavior matches the stable router. This gives clear selection context. It does not mention ask_pipeworx_grounded or any non-use cases, but the beta-vs-stable positioning sufficiently guides typical usage.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the description adds valuable context: refusal behavior, refusal_reason enums, evidence formatting, source and confidence fields, and the extra LLM call cost. It fully explains behavioral edge cases 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 dense but every sentence earns its place: purpose, routing mechanism, response shape, refusal shape, high-stakes use case, and cost-based routing guidance. No filler words or tautological 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?

There is no output schema, so the description carries the full burden of explaining return values — and it does, including success and refusal variants, example refusal_reason strings, evidence quoting, and source metadata. It also explains the cost trade-off relative to a sibling tool, making guidance complete for autonomous selection.

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 all six parameters are simply aliases for the 'question' string. The description doesn't add parameter-level detail beyond what the schema provides, but the schema itself is already sufficient.

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

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

The description clearly defines what the tool does: a hallucination-resistant answer mode that extracts answers strictly from tool results. It explicitly distinguishes itself from ask_pipeworx by describing the same routing but with evidence and refusal behavior.

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

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

Provides explicit when-to-use guidance: whenever answers will be quoted, cited, or acted on in high-stakes scenarios. It also states when not to use it — prefer ask_pipeworx for casual lookups — and cites the cost difference of one extra LLM call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral detail beyond this: low-confidence matches short-circuit with 'low_confidence_match', closed markets return 'market_closed_or_inactive', wide-spread markets are flagged, and the resolution-rule risk section explains cancellation/void settlement nuances. This is 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 well-structured and front-loaded: it starts with purpose, then classifiers, fan-out examples, response shapes, safety, and resolution rules. Each section is dense with actionable info, but some details (e.g., 'audited arb-bot ledgers') could be trimmed without losing essential guidance. It earns a 4 because the length is justified by tool complexity, but it's not '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?

There is no output schema, so the description fully carries the burden of explaining return values. It details result.market fields, result.analysis with edge calculations, result.evidence, the resolver contract including match confidence and alternatives, parent_event extraction, news fallback behavior, and statuses. This is comprehensive for a high-complexity tool with 3 parameters and rich response behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much parameter-specific meaning beyond the schema—it repeats the market input formats but doesn't deepen the semantics for depth or include_raw. The fan-out examples are about behavior, not parameter semantics, so no bonus is warranted.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on researching a single bet with data fan-out. It also provides concrete use-case phrasings ('should I bet on X').

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: for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It gives clear context about acceptable inputs (slug, URL, question text) and mentions depth options. However, it does not explicitly contrast with alternatives or provide when-not-to-use exclusions, so it misses the top criterion for 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?

The description adds substantial behavioral context beyond the annotations: it pulls LATEST 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. These details are not in annotations and set correct expectations. No contradiction with the read-only, idempotent, non-destructive annotations.

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

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

The description is front-loaded with the core purpose and uses trigger phrases to signal usage. It is longer than minimal, but each sentence provides useful information about data sources, sorting, and output. The trigger phrase list adds a bit of length but improves usability.

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

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

With no output schema, the description explains return values (paired data, citation URIs) and sorting behavior. It is complete enough for effective use, though it could mention how the primary metric is chosen from the query and edge cases like missing entities. Overall, it covers the essential operational aspects.

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

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

The schema already provides full coverage of both parameters with descriptions and examples. The description adds meaning by detailing what data each type pulls and reiterating value formats (tickers/CIKs vs drug names). This goes beyond the baseline for high schema coverage, so a 4 is appropriate.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one call, with a specific verb+resource. It lists natural language trigger phrases and distinguishes from sequential single-entity lookups, making it distinct from sibling tools like entity_profile.

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

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

The description explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities, and provides clear trigger examples. It also defines scope (2-5 entities) and type-specific use cases, giving clear context for when to use.

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

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

Beyond the readOnly and idempotent annotations, the description discloses non-obvious behavior: account requirements, parallel tool routing, never-invented gaps[], citation_uri only when fetchable, contradictions[] on deeper passes, semantic excerpting, and expected latency. This gives the agent an accurate operational contract, and nothing contradicts the annotations.

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

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

The description is long, but it is dense and purposeful; nearly every clause adds a distinct decision-relevant fact. It is reasonably front-loaded with the access constraint and the most important differentiation, though the volume of detail means it requires more than a quick skim to absorb.

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

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

With no output schema, the description carries the return-value expectation and does thoroughly: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and citations are guaranteed resolvable. Combined with auth constraints, depth options, latency expectations, and alternatives, there is no major missing context for selecting and invoking the tool.

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

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

The schema already covers both parameters fully, so the baseline is 3. The description adds extra meaning by explaining how depth values behave operationally — gap recovery, lead chasing, contradiction scans, paywall restrictions, and multi-step resolution — and by reinforcing that the question should be broad and natural-language.

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

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

The description names a specific action and resource: grounded multi-source research across Pipeworx's structured data sources in one call, with facet decomposition, parallel tool routing, and a findings packet with citations and gaps. It clearly distinguishes itself from open-web search and from ask_pipeworx, so it stands apart from its sibling tools.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, current events, or when not signed in, and thorough depth requires a paid plan. It names concrete alternative tools and conditions rather than leaving selection to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description goes beyond by detailing the return format (top-N tools with names, descriptions, and full input schemas ready to call) and the meta-guidance to use it first. This adds valuable 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 front-loaded with the core purpose ('Find tools by describing the data or task') and includes a long but useful enumeration of domains. Each sentence contributes value, though the domain list is somewhat lengthy—still acceptable for setting expectations.

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, but the description fully explains the return value: top-N relevant tools with names, descriptions, and full input schemas ready to call. It also covers usage context and the limit parameter implicitly via 'top-N'. For a moderate-complexity tool, 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%, with all six parameters (including aliases) documented. The description does not add substantial meaning beyond the schema—it simply reinforces that query is a natural language description. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'Find' with the resource 'tools' and clearly states the tool's role as a discovery mechanism. It distinguishes itself from siblings by framing itself as the first step when many tools are available, which is unique among the sibling list.

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

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

It explicitly states 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST' when the agent wants to see the option set. This provides clear context for when to use it, though it does not explicitly name alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral detail: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; specific return fields; USPTO PatentsView API sunset with soft-fail; GDELT→GNews fallback; and zero-padded CIK requirement. 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 front-loaded with trigger phrases and organized with a clear progression: examples → purpose → preference → sources/returns → limitations. It is more verbose than ideal, but each section adds useful information for a complex tool.

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

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

For a complex multi-source tool with no output schema, the description is remarkably complete. It covers input constraints, how to use it, expected outputs (e.g., up to 5 filings, fundamentals from latest 10-K), and caveats (USPTO sunset, soft-fail, fallback). An agent has enough context 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%, and the schema already documents both parameters with examples and constraints. The description restates the zero-padded CIK and name limitation but does not materially add beyond the schema. Thus the baseline of 3 for high schema coverage 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 tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple concrete usage examples ('Tell me about X', 'research Acme', 'brief me on Tesla') and explicitly differentiates from sibling tools by recommending it over 'chaining single-pack SEC/XBRL/news lookups' for holistic views.

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

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

The description explicitly tells when to use this tool: 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' It also names a direct alternative: 'names not supported (use resolve_entity first if you only have a name).' This provides clear context and exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate these. It adds the motivation of 'clear sensitive data' but does not disclose additional behavioral traits such as error handling when the key doesn't exist or whether deletion is permanent. Given the annotations cover the safety profile, this is adequate but not rich.

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, starting with the action verb, and contains no redundant words. Every sentence adds value: the first states what it does, the second gives usage guidance and sibling 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 one-parameter tool with no output schema, the description covers the essential aspects: what it does, when to use it, and complementary tools. Annotations provide the destructive/idempotent profile, so no further behavioral description is needed.

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

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

Schema description coverage is 100% with a single 'key' parameter described as 'Memory key to delete.' The tool description's 'by key' aligns with this. No additional semantics are needed beyond the schema, so the baseline of 3 applies.

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

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

The description opens with 'Delete a previously stored memory by key,' which clearly states a specific verb (delete), resource (memory), and scope (by key). It explicitly distinguishes this from the sibling tools 'remember' and 'recall' by indicating it is the removal counterpart.

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 concrete when-to-use conditions: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember and recall,' showing awareness of the tool ecosystem and guiding appropriate use.

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

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

Annotations already establish the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context by describing the fetch-and-extract process and the specific output format (single text blob in standard llms.txt markdown), which goes beyond what annotations provide.

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

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

The description is succinct and well-structured: it opens with the core purpose, explains the process in the second sentence, and closes with a list of use cases. Every sentence contributes meaningful information without any redundancy or unnecessary 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?

For a tool with only 2 parameters, useful annotations, and no output schema, the description adequately conveys the output format and practical applications. It could mention error handling or edge cases, but it is sufficiently complete for an agent to invoke the tool correctly in most scenarios.

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 both parameters with clear descriptions (url and max_links), achieving 100% coverage. The description adds no new parameter-level semantics beyond what the schema already provides, so a 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's purpose: generating a production-ready llms.txt file for any URL. It specifies the exact resource (llms.txt), the process (fetch page, extract title/description/key links), and the output format, making it distinct from the sibling tools even without naming alternatives.

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

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

The description provides clear use cases for when the tool is useful, such as getting a client's site indexed, drafting llms.txt for a project, or auditing competitors. It does not explicitly mention when not to use it or name alternative tools, but the given context is sufficient for appropriate selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is well covered. The description adds that it returns all holidays and includes names/dates, but doesn't discuss edge cases, errors, or rate limits. This is adequate but minimal beyond annotational safety.

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

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

The description is two sentences long and front-loads the core purpose ('Get all public holidays for a country and year') before noting the return value and required inputs. Every word earns its place, and there is no redundancy.

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

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

For a simple read-only tool with only two parameters, complete schema descriptions, a strong annotation set, and an output schema present, the description adequately covers the core behavior and return summary. It doesn't need to explain return structure in detail.

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

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

The input schema already fully documents both parameters with descriptions and examples, giving 100% coverage. The description merely restates the need for country code and year without adding new meaning, so it earns 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 uses a specific verb ('Get') and resource ('all public holidays for a country and year'), clearly distinguishing it from siblings like next_holidays or is_today_holiday by scope. It also states the return content (holiday names and dates), making the tool's 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?

The description provides clear context for when to use the tool: to retrieve all public holidays for a specific country and year. However, it doesn't explicitly mention alternatives or exclusions, such as 'for upcoming holidays use next_holidays', so it falls short of explicit 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds that it returns whether it's a holiday and the name, but this is minimal and does not disclose additional behavioral traits beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the main purpose, and includes a concrete example. No unnecessary words or redundancy beyond the schema repetition, making it highly concise and well-structured.

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

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

This is a simple tool with one parameter, full schema coverage, and an output schema. The description covers the essential purpose and input format. It does not clarify differences from sibling holiday tools, but given the simplicity and rich structured data, it is sufficiently complete.

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

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

The schema fully describes the country_code parameter with ISO 3166-1 alpha-2 format and examples. The description repeats this with 'Provide country code (e.g., "US", "GB")', adding no new meaning beyond the schema. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: checking if today is a public holiday in a given country, with a specific verb (check) and resource (holiday). It does not explicitly distinguish from sibling tools like get_holidays or next_holidays, but the 'today' scope provides implicit distinction.

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

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

The description specifies the usage context ('Check if today is a public holiday') and provides an example of the input. However, it does not mention when not to use this tool or suggest alternatives, leaving the usage guidance implied rather than explicit.

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. The description adds value by enumerating the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the default behavior of only listing active subscriptions. This goes 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?

Two sentences, front-loaded with the core purpose and return fields, followed by a practical usage note. Every word earns its place; no filler or redundancy. This is an exemplar of concise, well-structured tool documentation.

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

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

For a simple list tool with one optional parameter, rich annotations, and no output schema, the description is complete. It states the default scope, lists return fields, and explains the use case. Nothing essential is missing given the tool's low complexity.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, whose description ('Include cancelled subscriptions in the response (default false)') already explains semantics. The description does not mention the parameter, so it adds no additional meaning beyond the schema. Baseline 3 is appropriate for high schema coverage.

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

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

The description uses a specific verb+resource ('List the caller's active subscriptions') and clearly defines scope (caller's active subscriptions, with optional include_inactive). It distinguishes itself from siblings like subscribe and unsubscribe by focusing on listing rather than mutation.

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 to review what you're monitoring before adding more or to find an id to cancel.' This implies alternatives (subscribe for adding, unsubscribe for canceling) but doesn't name them explicitly. It provides clear context but could be more explicit about when not to use it.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by specifying the temporal window ('from today onward') and that it returns names and dates, which helps the agent understand the exact output scope.

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

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

Two concise sentences that are front-loaded with the core purpose and immediately provide the required parameter format. No wasted words 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 one-parameter tool with a complete output schema and comprehensive annotations, the description is fully sufficient. It covers what the tool does, the specific time scope, and the required input format, making it complete 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?

The schema has 100% coverage for the single parameter 'country_code' with a clear description. The description repeats the parameter instruction ('Provide country code') without adding new semantics beyond what the schema already provides, 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 a specific verb ('Get'), a resource ('upcoming public holidays'), and a scope ('from today onward for a country'). This distinguishes it from siblings like 'is_today_holiday' (single day) and 'get_holidays' (likely broader range) by emphasizing the future time window.

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 by specifying 'from today onward', which signals it is for future holidays. However, it does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to choose this over a general holiday list tool.

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

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

Beyond the annotations (which only indicate non-read-only), the description discloses rate limiting (5/day/identifier), that it's free and doesn't count against quota, and the claim_token workflow (filing without an account returns a token; passing it later reads resolution). It also explains how the team processes feedback (daily digests, roadmap influence). This is rich, non-obvious behavioral context.

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

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

The description is long but every sentence earns its place: it covers purpose, usage categories, exclusions, claim-token mechanics, rate limits, and cost. It front-loads the core purpose and flows logically from what to use to how to use, with no filler or 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 four parameters (one nested, one enum) and no output schema, the description fully covers the tool's functionality: how to report, what types of feedback exist, constraints, and the asynchronous follow-up mechanism. It leaves no significant gaps for an agent to invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by explaining the claim_token round-trip flow, the 'don't paste the end-user's prompt' instruction for the message, and the need to describe issues in terms of Pipeworx tools/packs. This adds value beyond the schema, though not exhaustive for every parameter.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes this from sibling tools by explicitly framing it as feedback for the Pipeworx platform, and further differentiates from other MCP servers. The scope is precise and immediately understandable.

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 scenarios ('bug', 'feature/data_gap', 'praise') and a clear when-not-to-use rule with an alternative ('if the tool came from a different MCP server... file it with that server instead'). Also offers a decision aid: 'Not sure? Pipeworx tool names are the ones this connection lists.' This is exemplary usage 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 adds meaningful behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This reveals the data source, privacy guarantees, output shape, and caching behavior, which are not covered by 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 taut and well-structured: the first sentence states the core functionality, the second lists concrete use cases, and the third provides essential behavioral context. Every sentence earns its place, with no fluff or repetition of schema details.

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

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

Given the tool's low complexity (one optional parameter), no output schema, and strong annotations, the description sufficiently covers the return content ('top tools, top packs, and total call volume' plus 'pack, tool, count'), caching, privacy, and use cases. It could include an example result shape, but this is not critical for a read-only aggregation tool.

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

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

Schema description coverage is 100%, and the schema already documents the single parameter 'window' with its enum values and semantic meaning ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now...'). The description merely repeats this information without adding new parameter-level detail, 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 opens with a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This uses a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'), and the focus on aggregate trending usage clearly distinguishes it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides explicit use cases: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' This gives clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools.

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

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

Beyond the read-only/idempotent annotations, the description discloses critical behavior: the >3pp deviation threshold for partition_check, the Jaccard similarity anchor, the placeholder filter, and the fill check warning that realizable_edge_pp ≤ 0 should not be traded. These details materially inform safe usage.

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 fairly long but well-structured with labeled sections like SEMANTIC ANCHOR, PARTITION FILTER, and FILL CHECK. While every sentence adds value, the density of details makes it less concise than the ideal, though nothing appears wasteful.

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

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

Given the tool's complexity—two modes, filters, and return semantics—the description covers the key aspects: call patterns, input formats, output fields, and the fill check caveat. It is complete enough for an agent to use correctly without 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 already describes event and topic, but the description enriches them with concrete use cases, examples, and behavioral consequences (e.g., event walks child markets and computes partition_check; topic flattens related events). This adds substantial meaning beyond the schema's basic field 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further distinguishes three modes (trending_scan, event, topic) and explicitly differentiates from siblings like polymarket_fill_risk, 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?

It provides explicit when-to-use guidance: 'Call with NO args for a trending_scan...' and 'event (recommended for a specific market)' vs 'topic (for cross-event scanning)'. It also points to an alternative: 'For custom sizing use polymarket_fill_risk.' This satisfies both context and exclusion criteria.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds behavioral context beyond these. It discloses caching ('Cached 1h at the KV level keyed on all knobs'), detailed computation methodology (Kelly, slippage, lognormal barrier, GDELT ratio), and response semantics. No contradiction with annotations.

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

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

The description is a long, dense paragraph with specialized details like 'placeholder-slug filter drops will-person-X / will-team-Y...' and 'gates relaxed Run 8 from prior 85%/5%/50:1.' It is front-loaded with the purpose, but several details could be trimmed without losing essential guidance for an agent invoking the tool.

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

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

There is no output schema, so the description fully explains return values. It details the response structure ('by_segment{model_driven,structural_arbitrage,concentrated_longshot}, fed_candidates/fed_note, and _diagnostics{...}') and per-opportunity fields ('edge_pp_net', 'kelly_fraction + kelly_fraction_half', etc.). It also covers filtering knobs and caching, making it complete for a complex tool with 9 parameters and multifaceted output.

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

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

The input schema covers all 9 parameters with descriptions, so the baseline is 3. The description adds extra meaning by explaining how knobs interact, e.g., 'min_partition_leg_kelly filters partitions by best per-leg Kelly' and the note that 'min_kelly never filters them' because partition arbs return kelly_fraction_half=0. It also explains the purpose of tradeable-edge filters, 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states it's 'Built for "what should I bet on today"' and mentions discovering opportunities 'without paging hundreds of markets,' clearly distinguishing itself from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear use context via 'Built for "what should I bet on today"' and explains how knobs like min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable.' It also gives a when-not-to-use caveat for Fed bets ('1m-T vs EFFR signal is unreliable...'). However, it does not explicitly name sibling tools as alternatives, 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?

Despite the readOnly and idempotent annotations, the description goes far beyond them by detailing the response structure (tracked/expired/snapshot_dates), the 60-day TTL limit, and that decay is computed from daily closes rather than intraday. It even explains that snapshot gaps mean no scan occurred and the meaning of negative edge_pp_net.

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

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

The description is dense and quite long, but it is well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loads the core purpose. Every sentence contributes critical detail, though a slight trim would make it more scannable.

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

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

Even without an output schema, the description thoroughly specifies the response format, metric semantics (trend categories, decay_pp_per_day, first_seen), and all relevant limitations (TTL, snapshot start, daily closes). This fully compensates for the lack of a structured output definition.

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

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

Schema coverage is 100% with clear descriptions for both days and window. The description adds a brief summary of defaults (days default 14 max 30, window default '1wk') but does not introduce meaning beyond what the schema already provides, so it stays at the baseline.

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

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

The description clearly states this provides 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, answering when an edge appeared and if it's shrinking. It distinguishes itself from current-edge tools like polymarket_edges by focusing on historical persistence and decay.

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 indirectly conveys usage by posing the question it answers ('how long has this edge existed and is it shrinking?') and explaining the trade significance of edge age. It does not explicitly name alternative tools or provide when-not-to-use exclusions, but the context is clear enough for tool selection.

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

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

Annotations already declare read-only/idempotent behavior, and the description adds substantial detail beyond that: mode-specific behavior, size_usd interpretation (max spend vs settlement notional), default side logic, return fields for both modes, and the risk of partial basket fills creating unhedged directional positions. 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 every sentence carries meaningful information. It is well-structured with mode-specific sections and front-loaded with the core purpose. A slightly more compact presentation (e.g., bullet points) could improve readability, but it remains appropriately detailed for the tool's complexity.

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

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

There is no output schema, so the description is the sole source of return-value information. It enumerates all relevant output fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and includes practical caveats like thin_legs and forced_directional_risk. Combined with thorough parameter descriptions and usage guidance, the description is highly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant semantic value by explaining the mutual exclusion of 'market' and 'event', how 'side' defaults in basket mode, and how 'size_usd' is interpreted differently in each mode. This goes beyond the schema's per-property 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 precise statement of purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between two modes (single-market and basket) and differentiates itself from sibling tools by referencing polymarket_arbitrage and polymarket_edges signals.

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 use conditions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround not capturable on thin books). However, it does not explicitly list when NOT to use or name alternative tools, so it falls short of a perfect score.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the description adds substantial behavioral context: compatibility warnings, temporal alignment, skipped_cross_type/subtype counters, and the honest caveat that most pre-mapped topics aren't tradeable. This far exceeds the annotation baseline.

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 caveats and safety-field explanations. It is well-structured (modes, response, safety fields) and front-loaded with the core purpose. A few sentences could be tightened, but every sentence contributes critical information for safe 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 tool's complexity and absence of an output schema, the description thoroughly explains return values (leg-by-leg prices, top_spreads_pp), safety fields, and edge cases (temporal misalignment, pattern incompatibility). It covers the key decision-relevant behavior without requiring 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?

Schema coverage is 100% with per-parameter descriptions, but the tool description adds meaning beyond that: it explains that 'topic' is a pre-mapped shortcut and that the explicit tickers override the topic-mapped side. This clarifies the relationship between parameters and the two operational modes.

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

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

The description begins with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings like polymarket_arbitrage by focusing on cross-venue comparison and explicitly noting when the spread is a real signal vs. not.

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

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

The description provides clear usage context: two modes (topic shortcuts and explicit tickers) and when they apply. It also warns that pre-mapped topics often return compatibility warnings, so users shouldn't assume tradeability. However, it doesn't directly compare to sibling tools (e.g., polymarket_arbitrage) or state 'use this instead of X'.

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 disclose readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable context: scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)' and the ability to list all keys. This goes beyond the annotations and clarifies privacy/scope behavior, though it omits explicit return value details.

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, each serving a clear purpose: the first states the core functionality, the second provides usage guidance, and the third clarifies scope and relationships. It is front-loaded with the most critical information and contains no filler.

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

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

The tool is simple (one optional parameter, no output schema), and the description explains its purpose, usage, scope, and relationship to sibling tools. It does not explicitly state what the tool returns (e.g., 'returns the saved value'), but 'Retrieve a value' is sufficiently clear for this low-complexity tool. Given no output schema, a note on return format would be slightly beneficial, but the description is otherwise 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?

The schema covers 100% of the parameter, describing 'key' as 'Memory key to retrieve (omit to list all keys).' The description reinforces this by saying 'omit the key argument' to list all keys, adding behavioral meaning to the optionality. Since schema coverage is high, baseline is 3, and the description modestly elevates it by confirming the omit-to-list behavior.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly states the two modes of operation and distinguishes this tool from siblings by naming its counterpart tools (remember, forget). This is unambiguous and immediately actionable.

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

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

The description provides clear usage 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 explicitly mentions pairing with 'remember to save, forget to delete,' giving an alternative for lifecycle management. This effectively guides when to choose this tool over others.

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 annotation readOnlyHint=true is contradicted by the description's statement: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This implies a persistent state change, conflicting with the readOnlyHint annotation. This is a serious annotation contradiction, so the score is 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 three sentences, front-loaded with the core action, and each sentence packs useful information: purpose, payload contents, filtering, mark_read behavior, and an alternative endpoint. There is no waste or redundancy.

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

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

The tool has 5 optional parameters and no output schema, so the description needs to cover return values, which it does (source, citation_uri, raw event payload). It also explains filtering, mark_read effect, and alternative access. However, the readOnlyHint contradiction may mislead an agent, slightly reducing completeness.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds valuable context beyond the schema: it explains type filtering with an example ('sec_8k'), specifies since is an ISO timestamp, and describes the side effect of mark_read. This extra guidance raises the score to 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 uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing it from siblings like list_subscriptions and recent_changes. It also specifies the content of each alert (source, citation_uri, raw payload), which further clarifies its unique 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 gives clear context for when to use this tool: to retrieve recent alerts from a persisted feed, with filtering by type and since. It also mentions that polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, offering an alternative usage path. However, it doesn't explicitly contrast with sibling tools, so a 4 is appropriate.

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

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

The description discloses multi-source fan-out (SEC, GDELT→GNews fallback, USPTO), fallback behavior (GNews when rate-limited or 5xx), and the USPTO sunset caveat with soft-fail behavior. This adds significant context beyond the readOnlyHint/idempotentHint annotations, which are consistent with the read-only nature.

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 intent examples, sources, fallbacks, parameter syntax, return format, and alternative tool. Every sentence serves a purpose for this complex multi-source tool; however, it could be tightened slightly without losing critical details.

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

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

With no output schema, the description explains return structure ('structured changes[] grouped by source + total_changes count + citation URIs'), covers source behavior, and acknowledges limitations (USPTO sunset). Given the tool's complexity, the description is complete enough for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds practical meaning: explains the 'since' format (ISO or relative shorthand), recommends '30d' or '1m', and clarifies that 'value' accepts ticker or CIK. This enhances understanding beyond the schema field 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 explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months' with clear verb+resource. It lists specific query patterns (e.g., 'What's new with X') and differentiates from entity_profile by noting the static profile use case.

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 concrete use-case examples, explains when to prefer this tool over entity_profile ('Use entity_profile instead when you want the static profile...'), and mentions the 'ONE parallel call' efficiency. This gives the agent clear direction on when to select 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?

Beyond annotations (idempotent, not read-only), the description adds valuable context: key-value scoping per identifier, persistent vs anonymous memory (24-hour TTL), and pairing with recall/forget. No contradiction with annotations; the extra behavioral details are substantial.

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

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

Four sentences, each earning its place: purpose, when-to-use, storage format, and persistence/pairing. Front-loaded and succinct with zero 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?

For a simple 2-param tool with no output schema, the description covers purpose, usage, scoping, persistence, and related tools. Annotations cover safety profile. Nothing important 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 covers both parameters with good descriptions (100% coverage), so baseline is 3. The description adds meaning by explaining the key-value pairing is 'scoped by your identifier' and provides real-world examples of keys/values, which is 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?

Description clearly states the tool 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from siblings by explicitly naming recall and forget as complementary tools, and gives concrete use cases (ticker, address, preference).

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 'Use when' guidance ('when you discover something worth carrying forward') and explains alternatives via 'Pair with recall to retrieve later, forget to delete.' This fully satisfies the when/alternative requirement.

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, idempotentHint, and destructiveHint false, so the agent knows it's a safe, repeatable lookup. The description adds value by disclosing graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), cross-source behavior (e.g., ISIN-to-LEI mapping), and that it cascades through multiple endpoints internally. It does not contradict annotations (annotation_contradiction is false). Slight deduction for not detailing rate limits or response format.

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

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

The description is informative yet reasonably concise for the complexity. It front-loads examples and use cases ('What's the ticker for…'). Every sentence adds value, but the detailed breakdown of company resolution (cross-source, multiple identifiers, graceful degradation) could be seen as slightly verbose. Still well-structured overall.

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 compensates by explaining what is returned (e.g., 'every identifier is labelled with the source', 'unresolved identifiers stated explicitly'). It covers edge cases (ISIN for non-US issuers, graceful degradation) and justifies why this tool replaces multiple lookups. Highly complete for a lookup tool.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema. The description adds significant meaning beyond enums (e.g., 'company' resolves to CIK + ticker + LEI + FIGI, 'drug' to RxCUI + ingredient + brand), and for 'value' it clarifies accepted inputs like ticker, CIK, ISIN, or name. This exceeds 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 resolves user-spoken names to canonical/official identifiers required by other tools. It provides specific examples like 'ticker', 'CIK', 'LEI', and 'RxCUI', and distinguishes it from siblings by emphasizing it replaces multiple manual 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?

The description explicitly tells when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also describes supported entity types (company, drug) and input formats (ticker, CIK, ISIN, name). No alternative tools are mentioned, but the context signals include many siblings, and the description's guidance is sufficient for correct selection.

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

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

Annotations already establish safety (readOnlyHint, idempotentHint, non-destructive), and the description adds behavioral detail: it internally calls ai_visibility_check, ranks by score, and returns score/confidence/signal density. No contradiction exists, though the first-entity-as-subject nuance is only in the schema.

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

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

Three focused sentences deliver purpose, mechanism, and use case in a front-loaded structure. No filler or redundant repetition of the title or schema; every sentence contributes meaningful guidance.

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 specifying the returned data (ranked list with score, confidence, signal density) and the underlying probe behavior. Combined with 100% schema coverage and safe annotations, the description is complete for effective tool selection and invocation.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds minimal parameter-related framing ('your brand + N competitors') but does not elaborate on model selection or API key handling beyond what the schema provides, making the baseline 3 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 specific action and resource: 'Compare AI visibility across multiple entities side-by-side.' It then details the mechanism (probes with ai_visibility_check, ranks by score, surfaces most/least recognized), which clearly distinguishes it from single-entity tools like ai_visibility_check and generic compare_entities.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an illustrative example question. It implicitly indicates this tool is for multi-entity comparison versus ai_visibility_check, but it does not explicitly state when not to use it or name alternative tools as 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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses partial failure behavior, a timeout risk and duration ("bundlephobia's first measurement... can take 5-30s"), and how failures are surfaced ("sources_failed will list it"). It also explains the return structure in detail, covering summary fields and links.

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: it starts with purpose, then usage, then output, then limitations, then failure behavior. Every sentence adds new information and no filler is present. Despite length, it 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?

For a composite tool with no output schema, the description thoroughly explains the return payload (summary block, per-advisory details, links, alternatives), ecosystem scope, and error handling. Combined with schema-covered parameters, the agent has complete information to invoke it correctly.

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

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

Schema coverage is 100% for both parameters, and the description does not add meaning beyond the schema. It reiterates that 'package' is an npm name and 'version' defaults to latest, but these details are already present in the schema. No additional semantic value 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 opens with a specific, composite purpose: "should I add this npm package to my project" check in ONE call, naming exact data sources (deps.dev, bundlephobia). It clearly distinguishes itself from sibling tools by describing its unique multi-source aggregation and output summary.

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

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

Explicitly states when to use: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." Also provides an ecosystem exclusion and alternative: "PyPI / Maven / Cargo / Go fall under deps.dev:version directly," which prevents misuse.

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/non-destructive. The description adds concrete behavioral details: embeddings model (BGE-base-en), windowing (500-char overlapping), and the 200K char cap with truncation flagging, all beyond schema/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?

All sentences earn their place: core operation, use case, integration with grounded tool, and technical constraints. It's front-loaded with the verb and resource, and stays under ~120 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?

Without an output schema, the description compensates by specifying return values (passages with offsets and similarity scores). Together with annotations, it gives the agent everything needed to decide and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances the text and query params with examples (SEC 10-K body, article) and clarifies truncation behavior at the 200K limit, adding 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 opens with 'Semantic search INSIDE a fetched record' and details the inputs/outputs (text + query → top-N passages with offsets and similarity scores). This clearly distinguishes it from sibling tools like ask_pipeworx_grounded, which grounds over whole documents.

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

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

It explicitly states when to use: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context). It also names the complementary tool ask_pipeworx_grounded as the alternative for grounding, giving the agent a clear decision path.

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 extensive behavioral context beyond annotations: OAuth requirements, anonymous/BYO limitations, SMS caps, phone verification, webhook signing secret one-time exposure, and auto-disable after 10 failing runs. This far exceeds 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 a dense single paragraph with no fluff, but its length and stream-of-consciousness structure make it slightly harder to parse. All information is relevant, but a bulleted format could improve readability.

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

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

For a tool with no output schema, it explains the return value (subscription id) and webhook secret handling, prerequisites, type-specific parameters, and delivery behavior. It gives enough context for correct invocation and expectations.

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

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

Schema coverage is 100%, but the description adds meaning by clarifying the always-on feed, delivery channel options beyond the schema, and providing examples for type-specific parameters. It extends the schema's parameter descriptions without redundancy.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It enumerates supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

It provides clear context on when to use (to subscribe to live event streams), prerequisites (OAuth account), and delivery options. However, it lacks explicit alternatives or when-not-to-use guidance, relying on sibling names to imply distinctions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: it pulls from 'the live catalog of thousands of tools', returns examples with tool + argument shape, and supports optional topic filtering. This goes beyond the annotations and gives a clear picture of behavior without contradiction.

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

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

The description is longer than average but front-loaded with example user phrasings that help the agent recognize when to use it. It includes a category list and invocation details. Each sentence serves a purpose, though some example phrasings could be trimmed without losing meaning. Overall it's dense but not wasteful.

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

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

For a tool with one optional parameter and no output schema, the description fully specifies what it returns (category-bucketed examples with tool shapes), how to invoke it (no args or topic), and when to use it (as the first stop after connection). It also connects to related meta-tools. This is sufficient for an agent to select and call 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 input schema already covers the single 'topic' parameter thoroughly, listing allowed values and explaining that omitting it gives a cross-category spread. The description repeats some of this information ('pass topic to focus') but adds no new syntax, constraints, or deeper semantics. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool is the onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. It uses specific verbs like 'Returns' and 'Call', and the title 'What Can I Ask Pipeworx?' aligns directly with the function. It distinguishes itself from siblings like ask_pipeworx by focusing on generating suggestions rather than answering queries.

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 direction: '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 explains the no-argument vs. topic argument usage. However, it does not explicitly name alternative tools like discover_tools or state when NOT to use it, so it falls short of the full 5.

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

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

The description discloses key behavioral traits beyond the annotations: the row is deactivated rather than deleted, preserving historical events, and ownership is enforced. This adds meaningful context about authorization and data persistence that annotations alone 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 two sentences, front-loaded with the action ('Cancel a subscription by id') and followed by two important clarifications. No unnecessary words, 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?

Given the simple 1-parameter tool, the description covers the core functionality, ownership restrictions, and the soft-delete behavior. It lacks an explicit mention of return values or response format, but the annotations and simplicity make this a minor gap.

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

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

The schema already provides 100% coverage of the parameter, including a description that the ID is returned by subscribe. The tool description only says 'by id' without adding new semantic detail, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool cancels a subscription by ID, using a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation, and adds detail about deactivation vs deletion.

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 clearly implies the tool is for canceling subscriptions, and mentions ownership enforcement, which tells users they can only cancel their own. However, it does not explicitly name alternative tools or when-not-to-use situations, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds critical behavioral nuance beyond annotations: could_not_verify is a non-result containing verification_error and definitively not evidence for or against the claim; unsupported means no source coverage. It also discloses the two distinct execution paths (structured financial vs. grounded general), which is value well beyond what annotations provide.

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

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

The description is lengthy but each sentence serves a purpose: trigger phrases, when-to-use, path selection, verdict semantics, and the efficiency benefit. The first sentence front-loads the core purpose. It is somewhat run-on and could be tightened, but there is no redundant filler.

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

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

Despite having no output schema, the description enumerates all six possible verdict labels, explains the return structure (actual value + pipeworx:// citation + reasoning), and covers edge cases with clear guidance. It also describes both operation modes (structured vs. grounded) and the tolerance behavior. This gives an agent sufficient information to invoke the tool and interpret its results correctly in varied scenarios.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds meaningful context beyond the schema: tolerance_pct overrides claim-wording tolerance and is capped at 5% by default, and it references 'exact percent-delta math' for financial claims, explaining how tolerance is applied. The claim parameter is also exemplified with realistic phrasing, enhancing usability without repeating schema text.

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

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

The description opens with concrete trigger phrases and clearly states the tool performs 'natural-language claim verification against authoritative sources.' It specifies a verb (verify/validate) and a resource (factual claims), and distinguishes itself from sibling research tools by focusing on fact-checking with a verdict-based output. It also notes it replaces 4–6 sequential calls, reinforcing its unique role.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides a branching rule: company-financial claims use the SEC EDGAR + XBRL fast path, while all other factual claims fall through to a grounded pipeline. It also conveys when not to use it implicitly by positioning it as a consolidated replacement for multi-step lookup flows.

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