Rubygems

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

Annotations already declare readOnlyHint and idempotentHint, so the description's job is lighter. It adds value by specifying the default model (free) and the per-model return structure (score, confidence, signals, raw_response). No contradictions.

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

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

The description is concise (3 sentences) with no filler. It front-loads the primary action and result, then explains options and outputs. 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?

Despite no output schema, the description explicitly states the return structure (per-model object with score, confidence, signals, raw_response + combined view). It covers all 4 parameters, usage, and outputs, making it complete for an agent.

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

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

Schema coverage is 100%, so the description builds on that by explaining the default model for the 'models' parameter, the condition for '_apiKey', and the disambiguation purpose of 'context'. This adds meaningful context beyond the schema.

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

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

The description clearly states what the tool does: probe LLMs for visibility (0-100) for a given entity. It uses a specific verb ('probe') and resource ('LLMs for visibility scoring'), and distinguishes itself from sibling tools like deep_research by focusing on a unique metric.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional API key. It lacks explicit 'when not to use' or references to alternatives, but the context is clear for the intended purpose.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context: routing across many sources, automatic argument filling, and stable citation URIs in the result. It does not describe failure modes or limits, but it does not contradict 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 well organized: scope, routing behavior, trigger phrases, examples, and exclusions each have a clear role. It loses a point for the incomplete trailing fragment 'If your client is ...' and for some redundancy in the 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?

For a broad question-routing tool with no output schema, this description covers the essentials: domains, example queries, exclusions, alternatives, and the shape of the returned answer. The lack of a detailed response schema is acceptable given the stated citation behavior, but a clearer return description would make it 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?

The input schema is already fully documented and covers all aliases, so the baseline is 3. The description adds value with six concrete example questions that clarify the expected natural-language format and show the breadth of acceptable queries.

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

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

The description names the core behavior precisely: it routes a natural-language question to one of 5,798 tools across verified sources, fills arguments, and returns a structured answer with pipeworx citation URIs. It also distinguishes itself from web search and from named siblings such as ask_pipeworx_grounded and deep_research.

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

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

It explicitly says PREFER OVER WEB SEARCH and START HERE for most questions, provides trigger phrases and concrete examples, and gives clear when-not-to-use guidance with alternatives: ask_pipeworx_grounded for step-by-step reasoning and deep_research for creative or multi-part questions.

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 a full safety profile (readOnly, openWorld, idempotent, non-destructive), and the description adds genuinely useful behavioral context beyond that: the experimental nature, the live-switching of candidate routing improvements, the current inactive state with a dated retirement ('the last was retired on outcome evidence 2026-07-26'), and the strong guarantee that it 'falls back to nothing' means it is not a degraded stub. This temporally-variable behavior is exactly the kind of trait annotations cannot capture.

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

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

Four sentences, each earning its place: identity/beta nature, current operational state, usage guidance, and capability reassurance. The core purpose is front-loaded in the first sentence. Minor redundancy exists in the final sentence ('this IS a full working router, just the experimental edge') which partially restates the first sentence, but it adds clarity about non-degradation.

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-question router with 100% schema coverage, rich annotations, and no output schema, the description is nearly complete. It defers response-shape details to 'same response shape' as ask_pipeworx, which is acceptable since a sibling tool describes it. The main gap is not describing rate limits or failure behavior when a candidate routing is under test, but these are minor against the strong annotation 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?

Schema description coverage is 100%, so the schema fully documents the single required question parameter and all five aliases (q, text, input, query, prompt). The description adds no parameter-level detail, but per the baseline rule for high coverage, it doesn't need to. Score 3 is appropriate since the schema carries the entire parameter burden.

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

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

The description clearly identifies the tool as the beta variant of ask_pipeworx with a specific scope: 'identical universal router (same 5,798 tools, same arguments, same response shape)'. It distinguishes itself from the stable sibling by stating it runs 'candidate routing improvements enabled live', and confirms it is a full working router, not a stub. An agent can immediately tell this apart from ask_pipeworx and 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 an explicit when-to-use condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the purpose of usage ('results are compared against the stable router to decide what merges'). It lacks an explicit when-not-to-use exclusion clause, but the 'newest routing' condition strongly implies the stable tool is preferred for non-experimental use.

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

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

The description goes well beyond the annotations by detailing the exact return shape on success, the refusal structure, and the five specific refusal reasons ('not_in_source', 'no_tool_match', 'tool_error', 'data_truncated', 'llm_error'). It also discloses the extra LLM call cost and the grounding behavior, which are critical behavioral traits not available in the annotations.

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

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

The description is dense but front-loaded with the core purpose ('Hallucination-resistant answer mode for high-stakes reads') followed by the mechanism and usage. It is somewhat long due to the enumerated refusal reasons and return shape, but each element adds decision-relevant information and could not be trivially removed.

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 specifies the success and failure return structures. It also covers routing, tool selection, evidence extraction, cost, and when to prefer the sibling. An agent has enough information to invoke it correctly and interpret its results.

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

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

Schema description coverage is 100%, so the schema already documents the question parameter and its aliases thoroughly. The description adds context about the tool's grounding behavior but does not need to repeat parameter semantics. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 a specific mode: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes itself from ask_pipeworx by noting 'Same routing as ask_pipeworx' but then explicitly stating it 'EXTRACTS the answer using ONLY what the tool result contains,' which differentiates the grounded behavior from the standard behavior.

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

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

Usage guidance is explicit and actionable: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a clear exclusion: 'prefer ask_pipeworx for casual lookups,' and explains the cost tradeoff ('Costs one extra LLM call vs ask_pipeworx').

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral details: fan-out to data sources, market matching confidence, parent event extraction, news fallback, illiquid spread handling, cancellation rules, and safety mechanisms. No contradiction with annotations.

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

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

The description is dense and informative but quite long (multiple paragraphs). Key terms are capitalized, but structure is a single block. Could be more concise by using bullet points.

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

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

Given the tool's complexity (3 parameters, no output schema), the description thoroughly covers all aspects: input formats, behavior, response shapes, safety checks, and edge cases. Nothing appears missing.

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

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

Schema covers all 3 parameters with descriptions. The description enhances understanding: explains market parameter accepts slug, URL, or question text; clarifies depth parameter meaning; gives rationale for include_raw. Adds value beyond schema.

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

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

The description clearly states it researches Polymarket bets by pulling Pipeworx data, with specific use cases like 'should I bet on X'. It distinguishes from sibling tools by focusing on market research rather than arbitrage or edge tracking.

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

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

Explicitly says when to use the tool ('Use for should I bet on X') and describes blocking conditions (low-confidence match, closed markets). However, it does not explicitly mention when not to use or compare to 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 adds significant value beyond annotations: it details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), explains how off-calendar fiscal years are handled, mentions sorting by primary metric, and specifies output format (paired data + pipeworx:// citation URIs). No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 somewhat lengthy but every sentence provides valuable information. It starts with example queries to quickly convey the tool's use case, then explains behavior, preferences, and data sources. 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?

Given the tool's complexity (2 parameter types, different data sources, no output schema), the description thoroughly explains what data is returned per entity type, how results are sorted, and the fact that it replaces multiple sequential lookups. All essential aspects are covered.

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 100% of parameters, but the description adds critical context: for type 'company' it pulls financial metrics and lists them; for type 'drug' it pulls FAERS counts, FDA approvals, trials. This goes beyond the schema's enum descriptions, enriching parameter meaning.

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

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

The description clearly states the tool's purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses specific verbs (compare) and resources (companies/drugs), and distinguishes itself from siblings like 'entity_profile' which likely handles single entities.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use this tool. While it doesn't explicitly state when not to use it, the preference is strongly conveyed, and alternatives are implied (e.g., entity_profile for single lookups).

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

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

The description goes far beyond the safety annotations by disclosing account requirements, paid-tier behavior, parallel decomposition across tools, the exact shape of returned findings, gap handling without fabrication, citation fetchability guarantees, contradiction scanning, semantic excerpting, and expected latency. This is a model of 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?

Every sentence carries real content and the account-required warning is front-loaded, but the description is dense and somewhat rambling, mixing billing, alternatives, mechanics, output format, and latency in a single paragraph. It is effective but could be better organized for quick scanning.

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

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

For a complex tool with no output schema, the description is remarkably complete: it covers required authentication, the alternative tool, data scope, decomposition strategy, return packet contents, gaps, citations, contradictions, excerpting behavior, and timing expectations. An agent calling this tool correctly needs no additional clarification.

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 both parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics on top: 'thorough' is paid, 'standard' and 'thorough' return contradictions, depth tiers drive iterative hops, and 'question' may be broad or multi-part because decomposition is intended. This lifts it above baseline.

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

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

The description states a specific action ('grounded multi-source research') over a defined resource ('Pipeworx's 1517 STRUCTURED data sources') and explicitly excludes open-web search. It distinguishes itself from ask_pipeworx by saying single lookups should use ask_pipeworx instead. This is a clear, differentiated purpose.

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

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

The description gives explicit when-to-use guidance: broad and multi-part questions over structured data, with examples like 'compare X and Y's regulatory + financial exposure'. It also names the alternative ask_pipeworx for single lookups and for signed-out users, and states this is not open-web search. No ambiguity remains about tool selection.

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

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

Annotations already set readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns top-N relevant tools with names, descriptions, full schemas with examples, and that results are ready to call directly. No contradictions.

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

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

Description is long but front-loaded with core purpose and usage. The list of domains is verbose but provides useful context; could be slightly more concise without losing key details.

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

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

No output schema, but description explains return value (top-N tools with full schemas and examples). This is adequate for a discovery tool, though performance or pagination details are absent.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions main parameter 'query' with natural language expectation and aliases, but does not add detailed syntax beyond schema.

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

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

Description uses specific verb 'Find' and resource 'tools by describing the data or task'. It lists many concrete domains (SEC filings, financials, etc.), distinguishing it from sibling tools by emphasizing discovery.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing when-to-use and implied when-not-to-use guidance.

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

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

The description goes well beyond the readOnly/idempotent annotations by explaining the fan-out across multiple data sources, the semantics of empty sections ('real no data, not a bug'), the sources_used/sources_failed reporting, name resolution via SEC EDGAR, and the private-company resolved:false behavior. This is rich, non-obvious behavioral context that an agent needs to interpret results correctly.

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

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

The description is dense and front-loaded with example user intents, then details sources, return fields, and edge cases. It is appropriately detailed for a complex aggregator tool, but it is a single long paragraph with some redundancy with the schema, so a bit more structuring would improve scannability.

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

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

With no output schema, the description carries the full burden of explaining return values, data-source behavior, input forms, and failure semantics. It covers resolved_from/resolved_to, recent_filings, fundamentals, sources_used/sources_failed, private-company handling, and type/value flexibility. Nothing critical for calling and interpreting this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: type values are interchangeable, value can be a ticker, CIK, or company name, and name resolution behavior plus private-company edge cases are explained. This enriches the parameters 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 purpose: producing a full cross-source profile of a US public company in one parallel call. It is specific about the resource and outcome, but it does not explicitly distinguish itself from sibling tools like compare_entities or resolve_entity, relying instead on contrast with chaining single-pack lookups.

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

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

The description offers strong when-to-use guidance with many trigger phrases and explicitly says to prefer this tool over chaining single-pack lookups for holistic company questions. It does not, however, provide explicit when-not-to-use guidance relative to sibling tools, such as when a user wants entity resolution only or a side-by-side comparison.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, so the description's 'delete' is consistent but adds no extra behavioral context. With annotations covering the safety profile, a score of 3 is appropriate.

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, minimal waste. The action is front-loaded, and every sentence serves a purpose.

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

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

For a simple tool with one parameter, clear annotations, and no output schema, the description covers purpose, usage guidelines, and sibling relationships. Nothing is missing.

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

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

Schema coverage is 100%, so the description of 'key' in the schema fully documents the parameter. The description mentions 'by key' but doesn't add meaning beyond the schema. Baseline 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 'Delete a previously stored memory by key,' which is a specific verb+resource combination. It implicitly distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' Also tells to pair with remember and recall, providing usage context.

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. Description adds fetch and output format, but little beyond annotations.

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

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

Three well-structured sentences, front-loaded purpose, no wasted words.

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

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

Covers input, behavior, and output format despite no output schema. Gaps are filled by description and 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?

Schema description coverage is 100%; description does not add extra meaning beyond repeating defaults and max. 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?

Clear verb 'generate', specific resource 'llms.txt', and context 'for any URL'. Distinct from sibling tools.

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

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

Explicit use cases listed (client sites, own project, competitor audit). No when-not-to-use or alternatives, but context 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by stating the tool returns dependencies with version requirement strings, providing behavioral context beyond annotations.

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

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

Two concise sentences with no wasted words. Critical information is front-loaded: what the tool does, what it returns, and a key usage hint.

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, the description covers purpose, return format, and a usage hint. Presence of output schema further reduces need for return value explanation. Adequate for 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 clear descriptions for both parameters. The description adds extra usage guidance ('Omit version to get the latest'), which goes beyond the schema's parameter info.

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

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

The description clearly states it gets dependencies for a Ruby gem, using specific verb (get) and resource (dependencies). It distinguishes from sibling tools like get_reverse_dependencies by focusing on dependencies of a gem rather than dependents.

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?

Description hints at usage by saying 'Omit version to get the latest', which guides the agent on parameter usage. However, it does not explicitly contrast with sibling tools or specify when to use this over get_reverse_dependencies or search_gems.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds context about returning metadata details (download counts, URLs) and implies requirement that the gem is published. No contradiction.

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

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

Two concise sentences: first defines purpose and outputs, second gives usage guidance. No redundant information, efficient and front-loaded.

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

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

For a simple lookup tool with an output schema, the description adequately covers purpose, usage, and key outputs. Minor omission of error handling (e.g., gem not found) but acceptable given the tool's simplicity and annotation completeness.

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

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

Schema has 100% coverage with a clear description and examples for the single 'name' parameter. The description does not add extra parameter details beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clear verb 'Get' and resource 'full metadata for a published Ruby gem by name'. Explicitly lists outputs (latest version, authors, license, etc.) and distinguishes from sibling tools like get_versions and get_dependencies.

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?

Directly states when to use: 'what is gem X?', 'tell me about Ruby gem Y', and before calling related tools. Provides explicit alternatives as follow-ups, guiding the agent effectively.

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

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

Annotations already indicate idempotent, read-only, and non-destructive behavior. The description adds a key behavioral trait: the API caps at 50 names per request, which is 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?

Three sentences with no wasted words. Use cases are front-loaded, and the limit is stated at the end. Very concise and well-structured.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers purpose, usage context, and a practical limitation, making it complete for a simple list tool.

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

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

Schema coverage is 100%, and the schema already describes the single required parameter 'name' with an example. The description does not add additional meaning or constraints beyond the schema.

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

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

The description clearly states the tool lists gems that depend on a given gem, using a specific verb (list) and resource (gems). It distinguishes from sibling 'get_dependencies' by focusing on reverse dependencies.

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 two concrete use cases (ecosystem impact, risk surface) and mentions the API cap of 50 names per request. However, it does not explicitly say when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds value by specifying the data scope (every published version) and fields returned, providing additional behavioral context beyond annotations.

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

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

Two sentences with zero waste. First sentence states purpose and returns, second gives usage examples. Highly efficient and front-loaded.

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

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

Given low parameter count, existing output schema, and clear annotations, the description fully covers necessary context. No gaps remain for agent understanding.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description does not add extra meaning for the parameters themselves; it describes the overall output instead of parameter behavior. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves 'full version history for a Ruby gem' with specific fields (release date, downloads, compatibility, licenses). This distinctly separates it from siblings like get_gem or get_dependencies.

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 concrete example questions ('what versions of X exist?', 'when did Y release version Z?') that help an agent decide when to use. Lacks explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds value by listing specific return fields (id, type, params, created_at, last_fired_at, fire_count), which annotations do not cover.

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 focused sentences: first states purpose and output, second gives usage guidance. No superfluous information.

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

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

For a simple list tool with no output schema, the description sufficiently explains what is returned and when to use it, complemented by 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?

Schema covers 100% of parameters with a description for 'include_inactive'. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' with the resource 'the caller's active subscriptions' and enumerates return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly guides when to use: 'review what you're monitoring before adding more' or 'find an id to cancel', implying alternatives and appropriate contexts.

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

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

The description discloses side effects: filing returns a claim_token for later status checks, and calls are rate-limited to 5 per day. It adds context about cost ('Free; doesn't count against your tool-call quota') and the impact on the roadmap. Annotations state readOnlyHint=false, which aligns with the write nature of feedback submission; no contradiction.

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

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

The description is dense but every sentence earns its place: scope, exclusions, token mechanics, rate limit, cost, and guidance. It's front-loaded with the primary purpose, and despite its length, there is no fluff or repetition.

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

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

Given the tool's moderate complexity and no output schema, the description covers the full workflow: how to file, what to expect (claim_token), how to follow up, and practical constraints like rate limiting and cost. It could describe the immediate response structure in more detail, but the essential return behavior is communicated.

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 beyond the schema by clarifying claim_token usage with a concrete example (pass it back with no other arguments), and by constraining message content: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This enriches parameter meaning.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by making clear this is for reporting issues/praise, not for querying or research.

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

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

Explicitly lists when to use: bug, feature, data_gap, praise. Also gives a strong exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This provides clear alternatives and prevents misuse.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds value: data source (CF analytics-engine), no PII, caching duration. No contradiction.

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

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

Well-structured with front-loaded purpose and bullet list of use cases. Efficient but could be slightly trimmed; still earns its place.

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

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

Given simple tool (1 param, no output schema, rich annotations), description covers purpose, usage, behavior, and parameter adequately. Complete for agent decision-making.

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

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

Schema coverage is 100% with detailed enum description. Description adds marginal context via use cases, but does not further explain the parameter beyond schema.

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

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

Description clearly states the tool returns top tools, packs, and call volume over a window. Uses specific verbs and resources, and implicitly distinguishes from siblings via unique output.

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 three use cases (discovering hot data, confirming canonical tool, aligning use case). Does not state when not to use or name alternatives, but provides clear context.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: scanning logic, similarity thresholds, partition filters, fill check, response structure. No contradictions with annotations.

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

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

The description is somewhat verbose but every sentence adds value. It is front-loaded with the core purpose. Structure uses clarifications and emphasis (e.g., SEMANTIC ANCHOR, PARTITION FILTER). Could be slightly more concise, but information density is high.

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

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

Given the tool's complexity (two modes, multiple checks, thresholds, output details), the description is very complete. It covers behavior, edge cases, and references companion tool for custom sizing. No output schema is present, but response structure is described in detail.

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

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

Schema coverage is 100% and each parameter has a description. The description adds meaning beyond schema: explains modes, what values are accepted (slugs, URLs, seed questions), and behavior when no args. Enhances understanding significantly.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) and explains the difference, setting it apart from sibling tools like polymarket_edges.

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

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

The description provides explicit guidance: call with no args for trending scan, pass event for single-event mode, or topic for cross-event scan. It explains when each mode is appropriate and mentions that cross-event mode catches patterns missed by single-event.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description significantly expands on these by detailing caching (1h at KV level), diagnostic sections, filter skips, and internal model behaviors. 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 verbose but well-structured, with clear sections for model families, knobs, and response format. The first sentence front-loads the purpose. While it could be more concise, the detail is justified given the tool's complexity and 9 parameters.

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 absence of an output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics), all parameters, and caching behavior. It covers edge cases like Fed bets and filter skips, making the tool understandable and reliable for an AI agent.

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

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

Schema coverage is 100%, but the description adds extensive meaning beyond the schema: it explains how each parameter (e.g., min_kelly, slippage_pp, min_partition_leg_kelly) interacts with the edge detection logic and provides concrete examples and default values. This greatly aids correct usage.

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

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

The description clearly states the tool scans Polymarket markets for edges where Pipeworx data disagrees with market price, and it is built for discovering betting opportunities. It distinguishes itself from siblings by its broad scope and focus on multiple opportunity types (model-driven, structural arbitrage, concentrated longshot).

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 frames the tool for the 'what should I bet on today' use case and notes it avoids paging hundreds of markets. While it doesn't provide explicit when-not guidance relative to siblings, the context strongly implies its primary purpose and differentiators.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds significant behavioral details: data source (daily snapshots), limitations (60-day TTL, intraday not captured), and response structure (tracked, expired, snapshot_dates). No contradictions.

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

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

The description is well-structured, starting with the core purpose, then explaining the answer it provides, followed by parameters and response fields. While somewhat verbose, each sentence adds value and the information is front-loaded.

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

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

Given no output schema, the description fully details the response fields (tracked[], expired[], snapshot_dates[]) and their semantics, including computed values and limitations. It is complete for the tool's complexity and context.

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

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

Schema coverage is 100% with descriptions for both parameters. The description restates the default values and allowed ranges for 'days' and 'window', adding minimal new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses a specific verb-answer structure ('Answers how long has this edge existed and is it shrinking?') and distinguishes itself from related tools by focusing on historical persistence rather than current edges.

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

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

The description gives clear usage context: it's for understanding how long an edge has persisted and whether it's decaying, contrasting a fresh wide edge with an old one. Parameters like 'days' and 'window' are explained. However, it does not explicitly compare to sibling tools like 'polymarket_edges' or state when not to use it.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive behavior; the description aligns and adds details: 'walks the ladder,' returns verdict, and warns about partial basket fills converting arb into directional risk. This adds significant behavioral context beyond annotations, especially for basket mode.

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 capitalized mode headers and a usage paragraph. It is relatively long but every sentence is informative; no fluff. Slight reduction for minor redundancy (e.g., mentioning 'forced_directional_risk' twice), but overall it earns its length for a complex multi-mode 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?

Given no output schema, the description fully enumerates return fields for both modes, explains safety warnings (thin books, partial fills), and covers all parameter variants. The risk explanation ('dominant loss mode in real arb-bot P&L') adds crucial context. All aspects needed for correct invocation are present.

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

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

Schema description coverage is 100%, but the description adds crucial meaning: e.g., size_usd is 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional' for basket; side default logic in basket mode; mutual exclusivity of market and event. This goes far beyond schema descriptions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket) with specific return fields. It explicitly positions itself relative to siblings like polymarket_arbitrage by advising 'USE THIS before acting' on signals, 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?

The description provides explicit when to use (before arbitrage signals or trades above $500), when not (implied: small trades), and what alternative tools exist. It specifies required parameters ('REQUIRES one of market or event'), explains both modes' inputs, and warns about risks of not using the tool (unhedged directional positions). This is comprehensive 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 only say readOnly/openWorld/idempotent, and the description goes far beyond them: it discloses safety fields (compatibility_warning/compatibility_codes), leg-pairing exclusions for unknown legs, spread arithmetic (Kalshi − Polymarket), gross-vs-net fee caveat, alignment semantics, and skipped counters. It also warns that real spreads are rarer than the shortcut list suggests, which shapes agent expectations.

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 dense and front-loaded, starting with the core definition and response shape before caveats. Some compactness is lost in exhaustive safety-field explanations, but nearly every sentence earns its place given the number of conditions that affect interpretation of the spread output.

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

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

With no output schema, the description fully documents the response surface: leg-by-leg prices, matched spreads with per-entry flags, compatibility codes, temporal alignment fields, fee disclosure, and skipped comparison counters. An agent calling this tool for the first time has the information needed to interpret results and avoid false-confidence in the spread values.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaningful usage context beyond the schema: `topic` selects one of 10 pre-mapped macro shortcuts that auto-fetch the matching event, while setting explicit tickers overrides the mapped side, and both modes run the identical matcher. This explains how parameters interact rather than merely restating their types.

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

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

Opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then differentiates itself from generic spread tools by naming both venues, explaining the two input modes, and stating the same matcher applies to both, so an agent can tell it apart from siblings like polymarket_edges without opening schemas.

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

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

Clearly describes when to use each mode: pre-mapped `topic` shortcuts for quick macro pairs and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, including the warning that pre-mapped topics often return compatibility_warning. It gives contextual usage but does not explicitly frame exclusions versus sibling tools such as polymarket_arbitrage.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds context about scoping to user identifier (anonymous IP, BYO key hash, account ID), which is beyond annotations. No contradictions.

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

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

The description is concise (three sentences), front-loads the main purpose, and efficiently conveys usage, scoping, and relationships without unnecessary words.

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

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

Given the tool's simplicity (one optional parameter, read-only, idempotent) and comprehensive annotations, the description covers all essential aspects: dual operation modes, scoping, and tool ecosystem. No output schema needed as return type is implied.

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

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

Schema coverage is 100% and the description essentially restates the schema's parameter description. It does not add new information about the 'key' parameter beyond what is already in the schema, though it clarifies the behavior of omitting the key.

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

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

The description clearly states the tool's action ('retrieve a value' or 'list all keys'), specifies the resource ('memory key/value'), and distinguishes from sibling tools (remember, forget) by name.

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

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

Explicitly describes when to use the tool ('look up context the agent stored earlier') and implies when not to use it (not for saving or deleting). Mentions pairing with 'remember' and 'forget', providing clear alternatives.

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

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

The description discloses that setting mark_read:true flags events as read and changes subsequent results, implying a state change. This contradicts the idempotentHint annotation, which states the tool is idempotent. According to scoring rules, a contradiction results in score 1.

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

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

Description is four sentences with a clear front-loaded purpose, followed by key details. It is efficient and includes helpful extras (e.g., alternative API access) without being 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?

Covers return fields (source, citation_uri, payload), filtering, and mark_read behavior. With no output schema, specifying return structure is valuable. Lacks detail on 'unread_only' interaction but overall sufficient for a read tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the purpose of 'type' and 'since' filtering, and elaborates on 'mark_read' with a concrete example. This goes beyond the schema definitions, justifying a score above baseline 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?

Clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields (source, citation_uri, payload). Verb and resource are specific, but it does not explicitly distinguish from sibling tools that might deal with alerts, though the name 'recent_alerts' is self-explanatory.

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

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

Gives context: polling works fine, and an alternative API endpoint is mentioned for scripts/dashboards. However, it does not provide explicit guidance on when to use this tool versus sibling tools, nor does it state prerequisites or when not to use it.

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

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

Description adds value beyond annotations (readOnlyHint, etc.) by detailing parallel fan-out, GDELT→GNews fallback, USPTO soft-fail, and output structure (changes[] grouped by source, total_changes count, 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?

Description is well-structured: starts with query examples, explains functionality, then details each data source and parameter behavior. Each sentence adds value, though length is slightly above average. Still efficient for the complexity.

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

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

Despite no output schema, description explains return format (structured changes grouped by source, total_changes count, citation URIs). Covers multiple sources, fallback, and soft-fail behavior. Provides complete contextual information for an agent to understand the tool's capabilities and limitations.

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

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

Schema coverage is 100% with descriptions, but the description adds extra clarity: explains that 'since' accepts ISO date or relative shorthand (with examples) and that 'value' can be ticker or CIK. This is helpful but not essential given thorough schema.

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

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

Description clearly states it provides a change feed for a company across SEC, GDELT/GNews, and USPTO, and contrasts with sibling entity_profile. It uses specific verb-resource combinations and matches the query examples from the description.

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 tells when to use this tool (for recent changes) and when to use entity_profile instead (for static profile regardless of window). Also describes fallback behavior and data sources, providing clear context.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false. The description adds scoping by identifier, persistence differences (authenticated vs anonymous, 24-hour retention), and storage mechanism (key-value pair). No contradiction with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the core purpose, then provides usage guidelines, storage details, and sibling references. Every sentence adds value with no redundancy.

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

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

For a simple key-value store with 2 parameters and no output schema, the description is complete. It covers purpose, usage conditions, persistence behavior, and sibling tools. Annotations already provide safety profile.

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 100% of parameters with descriptions. The description enhances understanding by listing example keys and stating that value is 'any text — findings, addresses, preferences, notes', adding context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the action (save), resource (data), and context (across conversation/sessions). It distinguishes from siblings by mentioning pairing with 'recall' and 'forget'.

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

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

The description explicitly tells when to use: 'when you discover something worth carrying forward'. It provides concrete examples (resolved ticker, target address, etc.) and mentions alternatives: 'Pair with recall to retrieve later, forget to delete'.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive; the description adds substantial behavioral context beyond those hints. It discloses internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, `figi_candidates` disambiguation, and source labeling. No contradiction with annotations is present.

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 long, but it is front-loaded with purpose and examples, and organized by supported types. Most sentences add useful information, though some passages are run-on and could be tightened without losing value.

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

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

There is no output schema, so the description compensates by explaining return behavior in detail: source-labeled identifiers, `unresolved` fields, `figi_candidates` on ambiguity, RxCUI outputs, and enrichment fallback behavior. Combined with the schema and annotations, an agent has enough context 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%, but the description still adds significant parameter-level meaning: it explains accepted input forms (ticker, CIK, ISIN, name; brand/generic for drugs), how ISIN resolves to the issuing legal entity, and the fact that non-equity instruments resolve here. It goes well beyond the basic `type` and `value` 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 example queries and an explicit purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists the entity types it handles and precisely names the outputs (CIK, LEI, FIGI, RxCUI). This clearly distinguishes it from likely siblings like entity_profile or compare_entities.

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

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

The description gives an explicit trigger and precedence rule: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups and supports company and drug types. However, it does not explicitly name sibling alternatives or give a concrete 'when not to use' rule beyond the inverse of the stated condition.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. Description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score, confidence, signal density. Explains API key usage for Anthropic model.

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 plus an example and output mention. Every sentence adds value. Front-loaded with key action and purpose. No redundant or unclear phrasing.

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

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

Given 4 parameters and no output schema, the description explains purpose, internal mechanism, output format, and parameter roles. Could mention output schema details, but sufficient for agent understanding.

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

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

Schema coverage is 100%. Description adds additional meaning: first entity treated as 'subject', models include defaults and Anthropic requiring key, context disambiguates common names. Goes beyond basic 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?

Description clearly states the verb 'compare... side-by-side', the resource 'AI visibility across multiple entities', and the output ranking with scores. It distinguishes itself from sibling 'ai_visibility_check' by focusing on multi-entity 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?

Description explicitly mentions use case 'competitive AI-marketing audits' with an example question. It implies that for single-entity checks one should use 'ai_visibility_check', but does not explicitly state when not to use this tool.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: fans out to two external services, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully with sources_failed field, and the exact return structure. No contradictions.

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

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

The description is one paragraph but efficiently packs all necessary information: purpose, when to use, external services, behavior, return format, and edge cases. No filler words; every sentence adds value.

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

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

Given the moderate complexity (2 parameters, no output schema), the description is remarkably complete. It explains the composite nature, external dependencies, timing issues, fallback behavior, and the exact fields returned. It compensates for the lack of an output schema by enumerating the return structure.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted, which is not in the schema. Otherwise, the description does not introduce new semantic information beyond the schema, but the addition justifies a score above baseline 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 is a composite check for evaluating npm packages, specifying the verb 'scan', the resource 'dependency', and the exact services used (deps.dev and bundlephobia). It differentiates from sibling tools by defining its specific scope (npm ecosystem, specific checks).

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 ('whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'') and when not to (NPM ecosystem only; other ecosystems fall under deps.dev directly). Also mentions partial failures and graceful degradation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying that results are sorted by relevance and include specific fields, providing useful behavioral context.

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

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

The description is a single sentence that is concise and front-loaded, with no redundant information.

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

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

With an output schema present, the description does not need to detail return values. It covers purpose and result structure, but could mention pagination limits briefly. Overall, adequate for a search tool with full 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?

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema; it mentions 'keyword in name/description' which aligns with the query parameter.

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

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

The description clearly states the action (search), resource (RubyGems), and what is returned (name, version, downloads, info text). It distinguishes from sibling tools by specifying the specific domain of RubyGems.

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. With many sibling tools like 'search_within' and 'deep_research', explicit usage context is missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds significant behavioral context: truncation at 200K chars, BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, and return of offsets. 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 concise and well-structured, with the purpose front-loaded. Each sentence provides meaningful details without redundancy. Slightly long but appropriate for the complexity.

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

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

Despite lacking an output schema, the description explains return values (top-N passages with offsets and scores). It covers all parameters and constraints. The tool is moderately complex, and the description is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples for the query parameter ('supply-chain risk', etc.) and clarifies the text parameter as 'the document text to search inside'. This adds value beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the verb 'search', the resource 'record', and the scope 'inside'. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the 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?

The description explicitly states when to use the tool: 'when the record is too big to cram into the prompt'. It also explains how it pairs with ask_pipeworx_grounded, providing clear context. It lacks explicit when-not usage, 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 indicate non-read-only, idempotent, and non-destructive. The description details delivery channels, limits (SMS cap, webhook auto-disable), and one-time secret, but does not address idempotency implications for duplicate subscriptions.

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

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

The description is thorough and front-loaded with purpose. It uses structured text and examples, but is slightly lengthy. Every sentence is informative.

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

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

Given the tool's complexity, the description covers prerequisites, types, parameter details, delivery options, and output (subscription ID). No output schema is needed as return value is stated.

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

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

Despite 100% schema coverage, the description adds significant value with concrete examples for each subscription type, delivery channel constraints, and verification requirements, far exceeding the schema descriptions.

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

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

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

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

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

The description explains prerequisites (Pipeworx OAuth account, phone verification for SMS) and when to use it. It does not explicitly contrast with other tools, but the sibling list provides context.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog, and is an onboarding entry point. No contradictions.

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

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

The description is relatively long but every sentence adds value: alternative phrasings, purpose, return content, usage guidance. It is front-loaded with the core purpose and is appropriately sized for the tool's complexity.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description is exceptionally complete. It explains the return format (category-bucketed examples with tool+argument shapes), the source (live catalog), and when to use it. No gaps remain.

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 one optional 'topic' parameter. The description enhances this by explaining that omitting topic gives a cross-category spread and listing example topics, providing meaning beyond the schema.

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

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

The description explicitly states that the tool returns category-bucketed example questions for what Pipeworx can do, with alternative phrasings and a clear purpose as an onboarding entry point. It distinguishes itself from siblings by being the first tool to call when unfamiliar with Pipeworx.

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

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

The description provides clear usage guidance: call first when you don't know what Pipeworx can do, or to learn how to call meta-tools. It also explains when to pass a topic. While it doesn't explicitly state when not to use it, the context 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?

Discloses that the row is deactivated (not deleted) and historical events remain, adding value beyond annotations. Annotations already hint non-destructive, but description provides concrete details.

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

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

Two sentences, each efficiently adds value: states action and key behavioral constraints. No wasted words.

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

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

Given simple tool with one parameter and no output schema, description covers purpose, ownership constraint, and deactivation behavior. Lacks only return info, but not required.

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

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

Schema coverage is 100% with parameter description. Description repeats 'by id' but does not add new meaning beyond the schema. Baseline 3 for high coverage.

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

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

The description clearly states the verb (cancel) and the resource (subscription by id), and distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. Does not explicitly contrast with alternatives, but sibling list makes it clear.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive hints. The description adds significant context beyond that: the two processing paths (SEC EDGAR+XBRL vs. grounded), the exact verdict outcomes, and crucial caveats about could_not_verify and unsupported. This equips callers to interpret results correctly, which is more than the annotations provide.

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

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

The description is fairly long, but every section earns its place: trigger phrases, use case, dual pipeline, return values, and edge cases. The list of trigger phrases is somewhat redundant but helpful for pattern matching. The 'IMPORTANT' cap is well-placed and crucial. Slight over-verbosity in the introduction prevents a 5.

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

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

For a complex tool with no output schema, the description thoroughly covers return values, evidence citation, error semantics, and fallback behavior. It also explains the tool's role in replacing multiple sequential calls, making it clear why and when to use it. The absence of an output schema is fully compensated by the detailed outcome breakdown in the description.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description enriches the semantics by explaining that tolerance_pct overrides the implied tolerance and recommending values for hallucination detection, which is not in the schema. It also provides a concrete example for the claim parameter, adding clarity.

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

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

The description states a specific verb and resource ('natural-language claim verification against authoritative sources') and includes clear trigger phrases like 'fact check' and 'verify the claim that,' making it distinct from siblings like ask_pipeworx_grounded. It also clarifies the scope (company-financial vs. other claims), ensuring no ambiguity.

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,' which is clear context. However, it does not provide explicit when-not-to-use guidance or compare against alternatives (e.g., ask_pipeworx_grounded), leaving a small gap in full behavioral scoping.

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