deckofcards

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

Annotations already declare read-only/idempotent/non-destructive. Description adds that the default model is free while Anthropic requires a BYO key with direct payment, and describes the return structure. This adds cost/auth context beyond the annotation hints.

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

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

Three sentences, front-loaded with the core function, then default behavior, then use cases. Every sentence earns its place, with no fluff or repetition.

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

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

Despite no output schema, the description explicitly lists per-model return fields and combined view, and covers parameter behavior and use cases. For a tool with 4 params and no output schema, this is sufficient.

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

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

Schema covers all 4 parameters with descriptions (100%). Description adds the default model value and cost semantics for _apiKey, supplementing the schema 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?

Clearly states it probes LLMs for knowledge about a business/brand/product/topic and scores visibility per model. The verb 'probe' and resource 'one or more LLMs' are specific, and the output shape (per-model score/confidence) differentiates it from sibling tools.

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

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

Explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains the default free model and optional Anthropic key with cost implications, giving clear context for when to invoke it. No exclusion of alternatives, so not 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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context: the tool acts as a router/filler, returns pipeworx:// citation URIs, works on every tier, and makes one fast call. It does not contradict annotations and provides beyond-baseline behavioral disclosure.

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

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

The description is front-loaded with the key 'PREFER OVER WEB SEARCH' directive, but it is notably verbose, with a long block of text containing many examples and clauses. Some sentences could be trimmed without losing value, so it is not as concise as it could be.

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 high complexity and absence of an output schema, the description covers the essential aspects: purpose, routing behavior, citation output, usage scenarios, alternatives, and example queries. It is incomplete only in that it doesn't discuss potential errors or limitations, but 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 description coverage is 100% and the schema already documents all six parameters, with five being aliases for 'question'. The description gives helpful examples and phrasing guidance but does not add significant meaning beyond what the schema already provides. 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: it routes natural language questions to 5,529 tools across 1,455 verified sources and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different use cases.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives. It also lists many example question types and says it should be used for factual questions about real-world entities, events, or numbers.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses the beta status, the fact that no candidate is currently active (so behavior matches ask_pipeworx exactly), and that results are compared against the stable router to decide what merges. This provides meaningful context about the experimental nature and current operation, fully disclosing the tool's behavior.

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

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

The description is packed with essential information in three sentences: identity, relationship to the stable router, current state, and usage instruction. Every sentence earns its place with no filler or redundancy, making it concise yet comprehensive.

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 schema covers all parameters and the description explains the tool's relationship to ask_pipeworx, its current state, and that it's a full working router with the same response shape, the description is complete for an agent to select and invoke it correctly. The lack of an output schema is mitigated by stating the response shape is identical to ask_pipeworx.

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 provides 100% coverage with all six parameters documented as aliases for 'question.' The description adds no additional parameter semantics, but none are needed given the schema's thorough descriptions. This is the baseline score when the schema does the heavy lifting.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling ask_pipeworx by emphasizing its experimental routing candidates and the current identical behavior. The purpose is explicit: use this tool to ask questions through the experimental router.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It implies the stable ask_pipeworx is the alternative for non-experimental use, and it clarifies that the tool is a full working router, not a fallback stub. However, it doesn't explicitly state when not to use it, such as when stable routing is required, which would make the guidance even stronger.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the refusal mechanism with specific reason codes, the constraint of using only tool result content, the return shape, and the cost tradeoff. This richly describes behavior without contradicting annotations.

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

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

The description is compact yet information-dense, front-loaded with the core purpose, then detailing routing, returns, use cases, and cost tradeoff in a logical flow. Every sentence contributes unique value.

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

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

With no output schema, the description fully specifies success and refusal return structures. It also covers routing context, cost, and appropriate usage domains, making it complete for a single-question tool with strong annotations.

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

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

The schema already describes the 'question' parameter and its aliases with 100% coverage, so the description adds no new semantic detail. The tool's single logical input is fully documented, 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 defines the tool as a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers strictly from tool results. It explicitly differentiates from ask_pipeworx and cites specific use cases, 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 guidance: use when answers will be quoted/cited/acted on and facts must not be invented, and prefer ask_pipeworx for casual lookups due to the extra LLM call. This is direct when/when-not guidance with alternatives.

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

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

The description far exceeds the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing the resolver contract (market_match_confidence, score, alternatives, suggestions), safety short-circuits (low_confidence_match, market_closed_or_inactive), liquidity warnings, fan-out behavior, fallback handling with GDELT/GNews, and cancellation-rule risk. This provides deep context for how the tool behaves beyond simple read-only semantics.

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

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

The description is extremely long and dense, packing in a huge amount of technical detail. It is well-structured with capitalized section labels, but it is not concise or front-loaded. Every sentence carries information, but the sheer length makes it heavy for an agent to parse; it could be condensed significantly.

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 carries full burden for explaining return values, and it does so thoroughly: result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields, and all blocking/error paths are documented. It covers edge cases like wide spreads and cancellation-rule risk, making it complete for the tool's complexity.

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

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

The input schema already covers all parameters with detailed descriptions and 100% coverage, so the description adds little new parameter meaning. It reiterates the market input format and references depth/include_raw, but the schema already handles these. The value in the description is mostly about fan-out and response shapes, not parameter semantics.

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') and clearly states what the tool does: pulls relevant Pipeworx data, resolves the market, classifies the bet, fans out to category-specific data packs, and returns an evidence packet with a market-vs-model comparison. It distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on a single bet's research workflow.

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 names use cases: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." This gives clear context for when to invoke the tool, though it does not explicitly mention when not to use it or name alternative sibling tools for different tasks.

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

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

Annotations already declare readOnly/openWorld/idempotent safety, and the description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. 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?

Though moderately long, the description is tightly packed with useful trigger phrases, usage guidance, type-specific data details, and output expectations. Every sentence earns its place, and it is front-loaded with user-intent phrases for quick recognition.

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

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

For a tool with no output schema and two types of entity comparison, the description is fully complete: it covers what the tool does, when to use it, input parameter semantics, data sources, return behavior, and even the efficiency gain over sequential lookups. No critical gaps identified.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains what each enum value ('company' vs 'drug') pulls in terms of metrics and data sources, and clarifies the expected format for 'values' (tickers/CIKs vs drug names). Examples further aid correct invocation.

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

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

The description clearly states a specific verb ('compare') and resource (entities), with explicit scope of 2-5 companies or drugs in a single parallel call. It distinguishes itself from sequential lookups and sibling tools like entity_profile by emphasizing the side-by-side comparison capability.

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 trigger phrases ('Compare X and Y', 'which is bigger', 'rank these companies') and directly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also differentiates use cases for company vs drug types.

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 readOnly/openWorld/idempotent, but the description goes far beyond: it discloses account requirements, paid plans, non-open-web behavior, gap[] output, never-invention guarantee, contradiction scanning, semantic excerpting, and expected latencies. No annotation contradiction exists.

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

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

The description is long but front-loaded with critical constraints (ACCOUNT REQUIRED) and each sentence adds operational detail. There is no fluff, though the length is high; for a tool this complex, the density is justified.

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

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

Despite lacking an output schema, the description fully covers the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, hop field), gaps and contradictions behavior, and timing expectations. It is complete for both 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 coverage is 100%, so baseline is 3, but the description adds substantial meaning: it explains the depth enum values (quick=3, standard=5 default, thorough=8 paid), and clarifies that 'Broad/multi-part is fine' for the question parameter. This exceeds the schema's own descriptions.

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

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

The description opens with 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with 'NOT open-web search', providing a specific verb (research) and resource. It also distinguishes from siblings by noting it decomposes questions and routes to 5,529 tools in parallel, making it clearly unique.

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

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

Usage guidance is explicit: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains when to choose depth levels, so agents know exactly when to select this tool over alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it returns the 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' This discloses the tool's output behavior and efficiency, which is helpful and not redundant 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 organized into three clear sentences, with the main action and use case front-loaded. The long list of domains (SEC filings, FDA drugs, etc.) is a bit verbose but serves a purpose by signaling coverage and helping the agent match queries. It is efficient overall with no filler or repetition.

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

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

There is no output schema, so the description compensates by explicitly stating the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also gives concrete usage timing ('Call this FIRST') and covers the tool's role, making the description complete for a read-only discovery tool with strong schema coverage.

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

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

Input schema coverage is 100% and explicitly documents 'query' with aliases and 'limit' with default/max. The description mentions 'describing the data or task' (matching query) and 'top-N' (matching limit), but it adds no new semantic detail beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the burden and the description does not contradict or extend it.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb-resource pair and differentiates itself from sibling tools by explicitly listing the domains it covers (SEC filings, FDA drugs, etc.) and by positioning itself as a discovery/catalog tool rather than a direct data-retrieval tool. The mention of returning 'top-N most relevant tools' further clarifies its role.

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

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

The description gives clear usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This strongly implies when to use it, but it does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.

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

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

The description implies a state-changing operation (drawing cards removes them from the deck, changing the remaining count), but the annotations declare readOnlyHint=true. This is a direct contradiction, confusing the agent about whether the tool mutates 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?

The description is two concise sentences, front-loaded with the main verb and resource, and contains no filler. Every word 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?

The tool is simple and has an output schema, so return values need not be explained. However, the description lacks usage context (e.g., requires a pre-existing deck) and is undermined by the readOnlyHint contradiction, making it only minimally 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 input schema covers both parameters with clear descriptions (count defaults to 1, deck_id from new_deck), achieving 100% coverage. The description adds no new parameter semantics beyond restating 'specify count to draw multiple cards'.

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

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

The description clearly states the action ('Draw cards from a deck') and specifies the resource (a deck). It also notes the return value (card details and remaining count), distinguishing it from sibling tools like new_deck and shuffle_deck.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites such as needing an existing deck. The description simply states what it does without contextual direction.

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, not destructive), the description discloses that the tool fans out across multiple sources in parallel, returns specific fields, soft-fails on USPTO PatentsView due to sunset, uses a GDELT→GNews fallback, and passes ticker or zero-padded CIK. This is rich behavioral context that helps the agent predict outcomes and side effects. 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 longer than typical but packed with necessary information. It starts with usage examples, then clearly outlines the purpose, return fields, caveats, and parameter constraints. While some examples could be trimmed (there are six invocation examples), the structure and density justify the length. It earns its place, though it's slightly verbose.

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

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

Given the complexity of the tool (multiple data sources, fallback behavior, return structure), the description is thorough. It lists all key return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), mentions the patents API sunset and soft-fail, and explains the input constraints. With no output schema, this description fully compensates.

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

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

Even though schema coverage is 100%, the description adds meaning beyond the schema: it provides concrete examples ('AAPL', '0000320193'), clarifies that names are not supported, and explicitly ties the value parameter to ticker or CIK format. It also explains the type enum limitation (only 'company' currently). This goes well beyond the raw schema.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It specifies the resource (US public company) and the action (profile), and distinguishes itself from sibling tools by explicitly telling the agent to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-only inputs.

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 direct when-to-use guidance: use for holistic company research ('Tell me about X', 'brief me on Tesla'), and explicitly instructs to prefer this tool over chaining single-pack lookups. It also states when NOT to use it: names are not supported, and resolve_entity should be used first if only a name is available. 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?

Annotations already signal destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and pairing with other tools, but does not disclose additional behavioral traits such as irreversibility, error handling, or effects on related memories. It neither contradicts annotations nor significantly enriches beyond them.

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

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

The description is two concise sentences, front-loaded with the action verb and resource. Every sentence earns its place, providing purpose, usage scenarios, and related tools without waste.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description covers what it does, when to use it, and how it relates to siblings. Annotations cover destructive and idempotent behavior, making the description sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The description's phrase 'by key' adds no new meaning beyond the schema. Baseline of 3 is appropriate given 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 ('Delete') and clearly identifies the resource ('previously stored memory by key'). It distinguishes itself from sibling tools like remember and recall by focusing on deletion, providing clear 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 explicitly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with remember and recall. It lacks an explicit 'when not to use' statement, but the guidance is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond annotations by explaining the process and output 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?

Two sentences, front-loaded with the main purpose, then process and output, followed by use cases. No redundant information; 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?

The description covers purpose, process, output format, and use cases. With annotations covering safety and only 2 well-documented parameters, the description is fully sufficient. No output schema required.

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

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

Schema coverage is 100% with both `url` and `max_links` having descriptions. The description doesn't add additional parameter-level meaning beyond saying 'any URL', which is already in the schema. Baseline 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, using the specific verb 'Generate' and resource 'llms.txt'. It distinguishes from siblings by focusing on file generation for AI indexing, unlike sibling tools like scan_competitor_ai_presence.

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

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

Provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context but does not name alternative tools or when-not-to-use, so score 4.

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 description doesn't need to repeat safety. It adds value by disclosing the return fields (id, type, params, created_at, last_fired_at, fire_count) and the default behavior of active-only via the include_inactive parameter. 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?

Two sentences, front-loaded with the action and resource, no filler. Every sentence adds value: the first defines the operation and return fields, the second gives practical usage 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?

The description is complete for a simple, read-only list tool. It covers return fields, scope, and usage intent. No output schema means the description's list of fields is essential and provided. The schema handles the one parameter. No gaps.

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

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

The single parameter include_inactive is fully described in the schema (100% coverage), so the description need not repeat it. The description adds no additional meaning beyond the schema, but the schema does the job adequately. 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 verb 'List' and resource 'subscriptions', scoped to 'the caller's active subscriptions'. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on read-only listing of existing subscriptions.

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

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

Explicitly provides use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel'. This gives clear guidance on when to use the tool and implicitly points to subscribe/unsubscribe as related actions.

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

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

Description contradicts annotations. The description says 'Create a shuffled deck', implying a mutation, but annotations declare readOnlyHint=true and destructiveHint=false. This is a serious inconsistency, similar to the 'create_record' example. Additionally, the description does not add behavioral context beyond the annotations, such as whether the deck is persisted or if results are deterministic.

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

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

The description is concise, consisting of only three short sentences. Every sentence adds value: what it does, what it returns, and how to combine decks. There is no fluff 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 is simple and the description covers the core functionality, return values, and combination behavior. However, the parameter name mismatch and the contradiction with annotations reduce completeness. Since an output schema exists, return values are covered, but the semantic inconsistency could mislead an agent about the tool's safety and side effects.

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 with a clear description, so baseline is 3. The description adds an example (2 for 104 cards) and explains the effect, but incorrectly refers to the parameter as 'deck_count' instead of the schema name 'count'. This mismatch could confuse an agent, slightly reducing utility despite the 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 that the tool creates a shuffled deck of playing cards, which is a specific verb+resource. It also mentions the return values (deck_id and remaining count). However, it does not explicitly distinguish itself from the sibling tool 'shuffle_deck', which could be confused since both relate to shuffling.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'shuffle_deck' or 'draw_cards'. It only explains how to combine multiple decks via the 'deck_count' parameter, which is parameter usage rather than situational guidance. There are no explicit when/when-not conditions or prerequisite mentions.

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

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

The annotations are all false, offering minimal safety or side-effect info. The description compensates richly by disclosing rate limits (5/day), the claim_token return flow, daily team review, roadmap impact, free cost, and no quota impact. This goes far beyond structured annotations.

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

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

The description is long but every sentence carries essential information: purpose, usage triggers, exclusions, claim-token mechanics, rate limit, cost. It is front-loaded with the core purpose and then logically flows into constraints and operational details. No fluff or repetition.

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

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

Despite having no output schema, the description fully explains what to expect (claim_token on filing, status/changes on later check). It covers all parameters, nested context, rate limiting, applicability boundaries, and the feedback loop, 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?

Schema coverage is 100%, so schema descriptions already handle the basics. The description adds meaningful workflow context for claim_token (filing without an account returns the token) and clarifies the 'other' type via the context object. This is above the baseline but not hugely needed given the schema's completeness.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback types (bug, feature, data_gap, praise) and is unmistakably distinct from all sibling tools, none of which are feedback-related.

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 for each feedback type and a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' Also explains how to use claim_token later, giving complete operational guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: caching behavior ('Cached 5min-1h depending on window'), data provenance ('derived from CF analytics-engine'), and privacy ('no PII'). This exceeds the baseline despite strong annotations.

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

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

The description is well-structured and front-loaded with a vivid opening question, followed by a clear return summary, use-case list, and provenance details. Every sentence adds value without redundancy, making it appropriately concise for the information provided.

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

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

The description fully explains what the tool returns (top tools, top packs, total call volume, 'just (pack, tool, count)'), the meaning of the window parameter, and the data's nature (self-aggregating, no PII). Even without an output schema, the description is sufficient for a low-complexity read-only 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%, with the window parameter fully documented via enum and descriptive text. The tool description reiterates the window option but does not add new parameter syntax or format details. Baseline 3 applies because the schema carries the semantic load.

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

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

The description clearly states what the tool does: 'What other AI agents are calling on Pipeworx right now' and 'Returns the top tools, top packs, and total call volume over a recent window.' This distinguishes it from sibling discovery tools by emphasizing real-time aggregated usage and providing explicit use cases.

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

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

The description provides three specific use cases for when to use the tool, such as discovering hot data sources and confirming canonical tool choices. However, it does not explicitly state when not to use it or name alternative tools, which would have earned a 5.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses rich behavioral details: placeholder filtering thresholds, Jaccard similarity anchor, partition_check internals, and fill check pricing against live order book depth. It explains what triggers signals and when not to act.

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?

Though long, the description is tightly organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a front-loaded purpose. Each sentence adds necessary context; there is no filler or repetition.

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

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

This tool has two modes, filters, and a complex output with no output schema. The description fully covers return values (opportunities[] fields, partition_check fields, fill check outputs) and edge cases (thin legs, placeholder fractions). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving example event slugs ('fed-decision-may-2026'), topic seed questions, and noting that full URLs are accepted. It also explains the semantic difference between event and topic inputs, which the schema does not fully convey.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes two modes (event and topic) and differentiates from siblings by naming polymarket_fill_risk for sizing and contrasting with edge tools.

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

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

Provides explicit guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It explains what cross-event mode catches that single-event misses, and warns not to trade when fill check shows realizable_edge_pp ≤ 0. It also directs to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds extensive behavior: caching ('Cached 1h at the KV level'), exclusions ('fed_candidates... excluded from ranking'), diagnostics ('_diagnostics... so callers can see WHY a segment is empty'), and caveats like the 24h-move warning. This goes well beyond the annotations.

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

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

The description is long and dense, but it is well-organized with clear section markers (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and every sentence carries meaningful detail. It loses one point for being somewhat verbose; a few sentences could be trimmed without losing substance.

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 must explain the return shape, and it does thoroughly: by_segment with three model groups, fed_candidates/fed_note, _diagnostics with funnel counters, and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers caching and edge cases, making it fully self-contained for an agent.

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

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

Schema description coverage is 100%, which sets a baseline of 3. The description adds valuable extra semantics: it explains the 'TRADEABLE-EDGE KNOBS' section, clarifies that min_kelly does not filter partition arbs (and why min_partition_leg_kelly exists), and describes how slippage_pp interacts with edge_pp_net. This exceeds schema-only information.

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

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

The description states a specific verb ('Scan') and resource ('top Polymarket markets') with a clear outcome: 'return opportunities where Pipeworx data disagrees with market price.' It also provides a use case ('what should I bet on today') that distinguishes it from broader scanning tools, even without naming siblings explicitly.

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

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

Provides strong context: 'agents discover opportunities without paging hundreds of markets' and explains the tool's role in identifying tradeable edges. However, it does not explicitly name alternative sibling tools (e.g., polymarket_arbitrage) or give direct 'when not to use' guidance, so it earns a 4 rather than 5.

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

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

Even though annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds substantial context: response structure, edge trend classification, decay calculation methodology, snapshot date gaps, and TTL boundaries. It also discloses that decay numbers are from daily closes, not intraday, which is valuable behavioral nuance 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 long but highly structured, with sections for overview, arguments, response fields, and limits. Each sentence adds unique value—no filler. The length is justified by the absence of an output schema, meaning the description must carry the full weight of documenting the response format. The organization makes it scannable despite the detail.

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

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

Given no output schema, the description thoroughly documents the return structure: tracked[], expired[], and snapshot_dates[], including what each field means. It also explains edge cases (gaps, TTL, cache-miss behavior) and computation details. For a tool with this complexity, the description is complete and leaves no major ambiguity.

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

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

Schema coverage is 100% with both parameters described, so baseline is 3. The description goes further by explaining that 'window' selects a snapshot family and that 'days' is a lookback with a default. It also gives context about how snapshot dates relate to cache-miss behavior, adding meaning beyond the raw schema definitions.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes itself from sibling tools like polymarket_edges (current edges) by focusing on historical persistence and decay. The question it answers ('how long has this edge existed and is it shrinking?') is specific and unambiguous.

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

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

The description provides clear context for when to use the tool by explaining the trade insight: a fresh wide edge differs from a 3-week-old wide edge. It mentions the underlying source (polymarket_edges snapshots), implicitly framing it as the historical companion. The LIMITS section further sets expectations about data availability and computation, guiding appropriate usage.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint) already establish the non-destructive, read-only nature. The description adds substantial behavioral detail beyond that: it walks the ladder, computes VWAP/slippage, returns a verdict (clean|degraded|cannot_fill), and in basket mode reports per-leg fill details and forced_directional_risk. This materially 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 long, but every sentence earns its place for a two-mode tool with no output schema. It front-loads the core purpose, then systematically covers requirements, mode-specific behavior, return fields, and usage guidance. It could be improved with bullet points, but the density is justifiable given the tool's complexity.

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

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

With no output schema, the description must explain return values, and it does so comprehensively: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; then for basket mode theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk. It also covers prerequisites and failure modes, making it complete for a pre-trade risk-check 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 the baseline is 3. The description repeats the schema's parameter descriptions almost verbatim (e.g., side options, size_usd 'max spend on buys, target proceeds on sells'), adding no new per-parameter meaning. It does add the implicit one-of requirement for market/event, but that is more of a usage constraint than a semantic enrichment.

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+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It further differentiates two modes (single-market vs basket) and explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) to distinguish its role as a pre-trade validation step.

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

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

The description states exactly when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing thin-book uncapturable overround and partial-fill directional risk, which gives clear context and an exclusion threshold.

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 extensively discloses behavior beyond annotations, including compatibility_warning cases, temporal_alignment, and skipped_cross_type/subtype counters. It also warns that most pre-mapped topics are not tradeable, which is a crucial behavioral trait. There is no contradiction with the readOnly/idempotent hints.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and is front-loaded with purpose. However, it is quite lengthy and repeats the topic shortcut list already present in the schema, so it could be slightly more concise despite earning its place 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 thoroughly explains the response structure, safety fields, and temporal alignment, and it covers both usage modes. It also provides examples of warning conditions, making it complete for the tool's complexity.

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

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

The input schema already provides 100% coverage with descriptions for each parameter, including examples and override behavior. The description adds minimal new parameter semantics, merely repeating the topic list and explaining modes, so it doesn't exceed the baseline of 3.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, using specific language like 'Cross-venue spread between Kalshi and Polymarket.' It also explains two modes and response structure, making the purpose unambiguous. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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 by explaining the topic shortcuts and explicit ticker modes, and it cautions that pre-mapped topics often return compatibility warnings, implying the tool should be used to verify tradable spreads. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context beyond annotations, particularly scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also mentions the list-all behavior when the key is omitted.

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 action, and every sentence adds meaningful information. No fluff 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?

For a simple tool with one optional parameter, strong annotations, and no output schema, the description is fully adequate. It explains the purpose, usage, scoping, and relationship to sibling tools.

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

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

Schema coverage is 100% and the schema already documents the parameter ('Memory key to retrieve (omit to list all keys)'). The description reinforces the omission behavior and adds examples of what keys might contain, providing modest semantic enrichment beyond the schema.

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

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

The description uses a specific verb ('Retrieve') and clearly states the resource ('a value previously saved via remember') and the alternative behavior ('list all saved keys'). It distinguishes itself from siblings by explicitly referencing 'remember' and 'forget'.

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

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

It provides explicit usage context: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also pairs with siblings ('Pair with remember to save, forget to delete'), giving direct guidance on when to use this tool versus alternatives.

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

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

The description states that setting mark_read:true 'flags returned events read so the next call only shows newer ones,' implying a persistent state mutation. This directly contradicts the annotation readOnlyHint:true, which declares the tool as read-only. This is a serious annotation 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 three concise sentences, front-loaded with the core purpose, and includes essential details (return fields, filtering, mark_read side effect, alternative URL) without redundancy or filler.

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

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

Without an output schema, the description explains the return payload (source, citation_uri, raw event payload), filtering options, and mark_read behavior. It is fairly complete, though it does not address edge cases like rate limits or error handling. The alternative URL adds useful context.

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

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

Schema coverage is 100%, but the description adds value beyond the schema by providing a concrete example (type 'sec_8k') and explaining the behavioral effect of mark_read. This enhances parameter understanding beyond the raw schema descriptions.

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

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

The description clearly states the tool's purpose with a specific verb ('Pull') and resource ('fired events from your subscription feed'), and distinguishes it from siblings like list_subscriptions and recent_changes. It also describes the payload contents, leaving no ambiguity about what the tool does.

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

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

The description provides practical usage context, noting that polls work fine and offering an alternative URL (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. It does not explicitly compare against sibling tools but clearly conveys when this tool 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?

Annotations confirm safe read-only behavior (readOnlyHint, destructiveHint false), and the description adds rich behavioral detail: the fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to PatentsView API sunset, and the return structure (changes[], total_changes, citation URIs). This goes well beyond the structured fields.

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 natural language triggers, then efficiently explains the parallel fan-out, source fallback logic, input formats, output structure, and alternative tool. Every sentence provides necessary context, and the formatting makes it 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?

Given the complexity of multiple data sources, fallback behavior, and no output schema, the description fully covers the return format, source behavior, and parameter options. It also provides a pointer to the alternative tool, making it complete and actionable for an agent.

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

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

Schema description coverage is 100%, with each parameter already documented in the input schema (e.g., 'since' accepts ISO dates and relative shorthand). The description repeats these formats but adds no new parameter semantics beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly identifies the tool as a change feed for companies, with concrete examples of natural language queries ("What's new with X", "updates on Acme"). It distinguishes itself from the sibling entity_profile by specifying when to use the static profile instead.

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 this tool versus the alternative: 'Use entity_profile instead when you want the static profile...' It also describes the fallback logic between GDELT and GNews, giving the agent clear context on how the tool behaves under rate-limiting.

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

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

The annotations already cover read-only (false), idempotent (true), and destructive (false). The description adds useful context about scoping by identifier and the persistence difference between authenticated (permanent) and anonymous (24 hours), which is valuable 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?

Two sentences pack a lot of information without wasted words. The structure front-loads the core purpose and then adds context, making it concise and easy to parse.

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

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

Given the simple key-value nature, the schema, and annotations, the description covers the purpose, usage, and persistence semantics completely. There is no output schema, but none is needed for this tool.

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

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

Schema coverage is 100%, so the description doesn't need to explain parameters. It mentions key-value pair, which aligns with the schema but adds no extra detail beyond what the schema provides. 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 saves data as a key-value pair for later reuse, with a specific verb ('Save') and resource ('data'). It distinguishes itself from siblings by naming recall and forget as companion 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 describes when to use ('when you discover something worth carrying forward') and gives concrete examples. Directly mentions pairing with recall and forget, making the usage context and alternatives clear.

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

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

The description adds significant behavioral context beyond annotations: identifiers under unresolved are stated explicitly, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. These are non-obvious behaviors not captured by readOnlyHint or idempotentHint.

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 query examples, making the purpose immediately clear. It is somewhat long but structured with SUPPORTED TYPES, and every sentence adds value. No wordy fluff.

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

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

With no output schema, the description fully explains return values for both types, including source labels, unresolved handling, and fallback behavior. It also covers input variations and internal cascading, making it a complete standalone reference.

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 with descriptions and enum values. The description adds detail on what each type returns, accepted input formats for value (ticker, CIK, name; brand/generic), and examples, enriching the schema's basic semantics.

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, with examples like 'ticker for...' and 'CIK for...'. It distinguishes itself from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID' and listing supported entity types.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also details what each type returns and mentions graceful degradation, giving clear context on when to use it. It does not explicitly name alternative tools, but the guidance is sufficient.

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 and idempotent behavior. The description adds valuable process details: it probes each entity with ai_visibility_check, ranks by score, and returns a structured list with score/confidence/signal density. 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?

Three sentences, front-loaded with the action, then method, use case, and return value. Every sentence earns its place with no redundancy.

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

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

The description fully covers what the tool does, how it works, when to use it, and what it returns (since there is no output schema). It is complete for a read-only comparison tool with rich annotations and 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 input schema already covers all parameters (100% coverage). The description enriches the 'entities' parameter by noting the first entry is treated as the 'subject' for narrative, which is not present in the schema. This adds meaningful context.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), clearly distinguishing it from the single-entity ai_visibility_check tool. It also names the underlying mechanism and the ranking output, making the purpose unambiguous.

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

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

It provides a clear use case ('competitive AI-marketing audits') and an illustrative question, but does not explicitly name alternatives or state when not to use it. The context is sufficient for correct selection among siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar for extra disclosure is met by describing graceful partial failures, the 5-30s first-measurement delay from bundlephobia, and the sources_failed field. This adds context beyond structured annotations without contradicting them.

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

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

The description is dense and well-structured: purpose, usage trigger, return fields, ecosystem scope, failure behavior. Each sentence contributes useful information, though it is longer than minimal; it earns its length for a composite 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?

With no output schema, the description enumerates the exact summary-block fields (is_latest, license, etc.), mentions per-advisory detail and links, and covers alternative version lists. It also explains non-NPM handling and timeout behavior, giving a complete picture for invocation and result interpretation.

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

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

Schema description coverage is 100%, with both parameters (package and version) already documented including scoped-package examples and default-to-latest behavior. The description adds no extra parameter syntax or format details that aren't already in the schema, so baseline 3 is appropriate.

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

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

The description clearly defines a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia, enumerating specific data points (license, advisories, bundle size). This verb+resource+scope specificity distinguishes it from sibling tools like entity_profile or validate_claim.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also gives clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing to an alternative.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses detailed behavior: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, and caps at 200K chars with truncation flagging. This is rich behavioral context that helps the agent anticipate output and limitations.

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, with the core purpose front-loaded. Each sentence earns its place: definition, usage rationale, and technical specifics. No redundancy or fluff.

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

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

Given the simple schema, strong annotations, and no output schema, the description sufficiently explains the return format (passages with offsets and scores), the algorithm, and the truncation behavior. This is complete enough for an agent to use the tool effectively. The pairing with ask_pipeworx_grounded adds workflow context.

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

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

Schema description coverage is 100%, so the schema already explains each parameter. The description adds marginal context (e.g., 'Pass the text you already pulled' for text) but doesn't significantly enhance parameter understanding beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It specifies the verb (search), the resource (record/text), and the output (passages with offsets and similarity scores). This distinguishes it from sibling tools like ask_pipeworx by emphasizing 'inside a fetched record' and how it pairs with ask_pipeworx_grounded.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt — search_within saves context...' It also mentions a complementary tool (ask_pipeworx_grounded) for an alternative workflow. While it doesn't explicitly state when NOT to use it, the context is clear and useful.

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 describes a mutation (reshuffling and resetting drawn cards), which contradicts the readOnlyHint=true annotation. This is a serious inconsistency, so the description scores 1 for behavioral transparency.

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

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

The description is two concise sentences, front-loading the action and return value with no wasted words.

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

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

The tool is simple with one parameter, and the description covers the action, the reset behavior, and the return value. The output schema exists, so return details are likely covered. The main gap is the annotation contradiction, but the description itself is complete for the tool's simple scope.

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

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

The input schema already provides a complete description of the deck_id parameter (100% coverage), so the description adds no additional parameter semantics. Baseline 3 applies.

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

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

The description clearly states the tool's function: reshuffling a deck and resetting drawn cards. It uses a specific verb 'reshuffle' and specifies the resource (deck), distinguishing it from sibling tools like draw_cards and new_deck. The return count is also mentioned.

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 the tool: when a deck needs to be reshuffled and its drawn cards returned. It provides clear context but does not explicitly name alternatives or state when not to use it, though the purpose makes this fairly obvious.

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 annotations: account requirement, return of subscription id, always-on feed, opt-in email/SMS with verification and caps, and the fact that anonymous/BYO cannot persist. No contradiction with annotations; idempotentHint is not addressed but not contradicted.

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

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

The description is dense but well-organized, front-loading the primary action and then requirements, types, and delivery. It uses four sentences to convey a large amount of information without waste, though it slightly sacrifices readability by packing many clauses.

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 complex (3 params, nested objects, 5 enum types, multiple delivery channels) and there is no output schema. The description covers only three of the five subscription types and omits webhook as a delivery channel, though the schema fills these gaps. It does state the return value (subscription id), but the incomplete coverage of types and channels makes it less than fully complete.

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

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

Schema coverage is 100% with rich descriptions, so the baseline is 3. The description adds some redundant examples (e.g., 'items:["5.02"] = officer change') but does not explain parameters beyond what the schema already provides. It does mention OAuth requirement and return value, but these are not parameter-specific.

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 'Create a proactive monitoring subscription to a live-data event stream,' a specific verb+resource combination. It also lists supported subscription types and delivery channels, clearly distinguishing it from siblings 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 for use: requires a Pipeworx OAuth account, enumerates supported types with example parameters, and explains delivery options. However, it does not explicitly state when not to use this tool or mention 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive hints, so the description adds context rather than duplicating safety. It discloses that results are drawn from a live catalog of thousands of tools, that output is category-bucketed, and that each example maps to a concrete tool and argument shape. The description is consistent with the annotations and adds meaningful behavioral detail.

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 purposeful: each segment serves to capture user intents, define the return value, enumerate categories, clarify parameter behavior, and provide placement guidance. It is front-loaded with the most recognizable question phrasings, and while it could be trimmed slightly, the length is justified by the tool's onboarding role and the absence of an output schema.

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 user-facing output schema, the description fully compensates by explaining what the tool returns (category-bucketed examples each with exact tool + argument shape), how to vary the output with the optional parameter, and the intended first-use context. An agent would have all needed information to select and 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% and describes the 'topic' parameter with valid values. The description adds extra value by providing usage examples ('finance', 'pharma', 'betting'), explaining that omitting the parameter gives a cross-category spread, and framing the parameter as a focus mechanism. This goes beyond the schema's basic value list.

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 multiple natural-language user intents and immediately identifies the tool as the onboarding entry point for an agent. It states a specific verb ('Returns') and resource (category-bucketed example questions with exact tool+argument shape), clearly distinguishing it from siblings like discover_tools and the meta-tools it names.

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

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

The description gives explicit 'when to use' guidance: 'Use 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-filtered usage, and names alternative tools (ask_pipeworx, entity_profile, compare_entities) that the agent might otherwise choose.

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

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

Beyond the annotations, the description explains ownership enforcement, the deactivation behavior, and the consequence that historical events remain accessible via recent_alerts. This gives the agent important side-effect knowledge without contradicting the structured hints.

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

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

Three short, front-loaded sentences cover the action, a key constraint, and the behavioral consequence with zero filler. Each sentence earns its place.

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

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

For a single-parameter tool with strong annotations, the description is quite complete: it states ownership, the non-destructive nature, and the tie to recent_alerts. It does not describe return/error behavior, but the simple tool and existing annotations make that 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 documents id as a subscription uuid returned by subscribe, and coverage is 100%. The description adds meaningful constraint by stating ownership is enforced, which tells the agent the id must belong to the current user.

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 'Cancel a subscription by id,' using a specific verb and resource that clearly distinguishes the action from sibling tools like subscribe and list_subscriptions. It also adds identity constraints ('only cancel your own subscriptions'), reinforcing 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 provides clear usage context: use this when you have a subscription id and want to cancel an alert subscription you own. It implies exclusions by saying the row is deactivated rather than deleted, but does not explicitly name alternatives or when-not conditions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavior: SEC+XBRL fast path for company-financial claims, grounded pipeline for everything else, verdict taxonomy, and the important semantic difference between could_not_verify (did not happen) and unsupported (no source exists). This is exactly the kind of non-obvious behavioral context agents need.

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 appropriately detailed and front-loaded with purpose and triggers, then a clearly marked caller warning. It is slightly verbose in the middle ('routed to the right live source, answered with verbatim evidence, then judged'), but every sentence contributes operational value and the structure makes the key caveats easy to find.

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

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

With no output schema, the description fully compensates by enumerating possible verdicts, return contents (grounded/structured value + citation + reasoning), and the two failure-ish states with explicit instructions on how they must not be interpreted. It also covers coverage boundaries and the replacement of sequential calls, making it complete for an agent to decide and rely on the tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains claim wording implies tolerance, tolerance_pct overrides that, and gives concrete guidance (1–2 for hallucination detection, default capped at 5). This goes far beyond the bare schema descriptions.

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

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

The description opens with concrete natural-language triggers ('Is it true that…' / 'fact check') and a specific verb+resource: natural-language claim verification against authoritative sources. It clearly distinguishes itself from research/browse tools by stating it produces verdicts on factual claims and replaces a multi-step lookup pipeline.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and even differentiates company-financial claims from other factual claims with different routing paths. It doesn't name alternative sibling tools or state when not to use it, but the scope and automated fall-through behavior are clear.

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