httpcat

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

With annotations already declaring readOnly, openWorld, idempotent, and non-destructive behavior, the description adds valuable context: the default model (Workers AI Llama-3.3-70b) is free, passing _apiKey probes Anthropic and charges the user's own key, and the return structure includes per-model {score, confidence, signals, raw_response} plus a combined view. This goes beyond annotations and clarifies cost implications and output format.

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

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

The description is three sentences and immediately states the core function. It includes the most important operational details (default model, cost implication, return value) and practical use cases without fluff or redundancy. Every sentence earns its place.

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

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

Despite lacking an output schema, the description fully specifies the return format and per-model fields. It covers the single required parameter and explains optional parameters' roles. Given the tool's moderate complexity and strong annotation support, the description provides enough context for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by stating the default model and that _apiKey is passed through to api.anthropic.com, which clarifies behavior not fully captured in the schema. It also gives example entity values ('Pipeworx', 'OpenInvoice') that illustrate expected input.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly defines the tool's function and output, distinguishing it from siblings like ask_pipeworx (which answer questions about Pipeworx) and scan_competitor_ai_presence (likely focused on competitors). The purpose is unambiguous and directly stated.

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

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

The description provides explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional models and _apiKey parameters. However, it does not explicitly name alternatives or state when NOT to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: it explains routing, argument filling, citation URIs, and that it works on every tier with one fast call. 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 lengthy but highly informative, with every sentence contributing to usage guidance or capability disclosure. It is front-loaded with the key preference directive and includes examples, but it could be slightly tighter by removing redundant phrases like 'one fast call' and 'works on every tier' duplicated in the same paragraph.

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 (routing across thousands of sources) and the lack of an output schema, the description fully explains what the agent can expect: structured answers with stable pipeworx:// citation URIs. It also covers when to escalate to alternatives and how it handles broad questions, making it complete for selection and invocation.

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

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

Schema description coverage is 100%, with the parameter 'question' already documented along with its five aliases (q, text, input, query, prompt). The tool description itself doesn't add parameter-specific semantics, but the schema is sufficient; examples in the description illustrate valid queries. Baseline 3 applies because the description doesn't go 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 this tool routes factual questions to 5,529 tools across 1,455 verified sources and returns structured answers with stable citation URIs. It distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research, and explicitly positions itself as the default entry point for most questions.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specific step-up conditions for ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions). It also includes concrete examples of acceptable queries.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context about its experimental nature, the current inactive candidate, and that results are compared against the stable router to decide what merges.

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 bit long but information-dense. It covers what the tool is, current status, usage instructions, and behavioral expectations without redundancy. Front-loaded with the most important identification in the first sentence.

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

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

The description is complete for a tool with rich annotations and full schema coverage. It clarifies that the response shape matches ask_pipeworx, covers current operational behavior, and explains the beta testing context. No output schema is needed given the stable counterpart is referenced.

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

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

Schema coverage is 100% with each alias parameter described. The description mentions 'same arguments' but does not add syntax or format details beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and a universal router with the same 5,529 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by focusing on experimental routing improvements.

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

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

The description explicitly states when to use the tool ('Use it exactly like ask_pipeworx when you want the newest routing') and contrasts it with the stable router. It also clarifies that it is a full working router, not a fallback.

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

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

Beyond the annotations' read-only/idempotent hints, the description discloses refusal behavior, lists all refusal reasons, and specifies the return object fields. It also notes the extra LLM call cost, providing behavioral context not available in structured metadata.

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

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

The description is information-dense but well-structured: purpose, mechanism, return contract, usage guidance, and cost tradeoff. Every sentence adds distinct value, and the most critical info 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?

With no output schema, the description fully documents both success and refusal return shapes, including refusal reason enum values. It also covers the routing context (5,529 tools, 1,455 sources) and cost comparison. This is a complete contract for tool selection and invocation.

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

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

Schema coverage is 100%: the schema documents the 'question' parameter and five aliases. The description does not add parameter-level detail beyond referring to natural-language input. Baseline 3 is appropriate since the schema handles semantics.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism of routing and extracting only from tool results. It explicitly distinguishes from the sibling ask_pipeworx by noting the same routing but an extra LLM call and grounded extraction.

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

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

It provides explicit usage conditions: 'Use whenever an answer will be quoted, cited, or acted on' and lists specific domains. It also gives an exclusion: 'prefer ask_pipeworx for casual lookups.' This is clear when-to-use and 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?

Beyond the readOnlyHint, the description discloses extensive behavioral details: the resolver contract (match confidence, alternatives, re-query hints), safety short-circuit for low-confidence matches, status for closed/dead markets, wide-spread illiquidity warnings, resolution-rule risk parsing, and news fallback behavior. It even includes a 24h-move warning and a note about recurring cancellation-rule losses. This far exceeds the annotations' read-only hint.

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

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

The description is lengthy but well-structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and a front-loaded purpose statement. Every section adds important behavioral or safety information, so the length is justified by the tool's complexity, though it is not concise.

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

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

Despite lacking an output schema, the description covers response shapes, resolver contract, safety routes, parent_event extraction, news fallback fields, and resolution-rule risk. It even explains the two blocking routes for dead markets. This is unusually complete for a tool of this complexity, enabling the agent to know exactly what to expect and how to handle edge cases.

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 (market, depth, include_raw) already has detailed descriptions in the input schema. The tool description adds context about fan-out behavior and response shapes, but it does not add substantial meaning to the parameters themselves beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clarifies the input forms (slug, URL, or question text) and distinguishes itself from sibling tools like polymarket_edges or arbitrage by covering broad, multi-source research rather than a single edge or spread calculation.

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 tool explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides fan-out examples for different bet types, giving clear context on when to use it. However, it does not explicitly name alternative tools for when not to use it, though the use cases imply a general research role distinct from specialized siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. No contradiction with annotations, and the extra detail goes beyond the schema.

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

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

The description is dense yet well-structured. It front-loads with trigger examples, then explains behavior, data sources, and output. Every sentence earns its place; while slightly long, the information is highly relevant and not padded.

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 fully covers return format ('paired data + pipeworx:// citation URIs per entity'), sorting behavior, entity types, and data provenance. Given the tool's moderate complexity, this is sufficient for an agent to decide when and how to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enriches parameter meaning by explaining what each type pulls (company: 10-K financials; drug: FAERS counts, FDA approvals, active trials) and how results are ordered—adding semantic value over the bare enum/array 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 natural-language trigger phrases ('Compare X and Y', 'X vs Y') and clearly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' This specific verb+resource purpose distinguishes it from sibling tools like entity_profile or search_within.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and quantifies that it 'Replaces 8–15 sequential lookups.' This provides unambiguous when-to-use guidance and contrasts with alternative approaches.

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

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

Annotations indicate this is a read-only, non-destructive tool, and the description adds a wealth of behavioral context: account/plan requirements, decomposition into facets, parallel routing, gap reporting, citation resolvability, contradiction detection, semantic excerpting, and expected latency. No contradiction with annotations.

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

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

The description is long but dense and front-loaded with the critical account requirement. Every sentence contributes substantive guidance, though some ideas are repeated or could be streamlined. It is appropriately structured 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?

With no output schema, the description thoroughly covers return value shape (findings packet, gaps[], contradictions[], hop field, citation_uri), limitations, examples, and performance expectations. It is complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the meaning of 'question' and 'depth' but mostly restates what the schema already provides; it adds some behavioral nuance (e.g., paid tier for 'thorough', gap recovery behavior) but not substantial new parameter-level 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources.' It clearly distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups or breaking news.

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

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

Provides explicit when-to-use and when-not-to-use guidance: use ask_pipeworx if not signed in, use deep_research for broad/multi-part structured-data questions, and prefer ask_pipeworx for current news or single lookups. It even describes the difference between depth levels and the paid requirement for 'thorough'.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds useful behavioral context about the output: returns top-N results with full schemas and curated examples, 'ready to call directly, no second schema lookup needed.' This goes beyond annotations and helps set 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 moderately long but front-loaded with the core purpose. The list of covered domains is useful despite adding length, and every sentence contributes value (usage, return format, when-to-use). It could be tightened but is still 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 tool's simplicity and strong schema/annotations, the description sufficiently covers what it returns, when to use it, and how it behaves. No output schema exists, but the description explains the return format. It omits edge cases like limit defaults, but those are in the schema, so overall completeness is good.

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

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

Schema description coverage is 100% with clear descriptions for query and aliases. The description restates the query concept but does not add meaning beyond the schema. It does provide a few example queries in the schema, not in the description, so the description itself contributes little to parameter understanding.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this as a meta-tool for discovering other tools, listing domains it covers and stating that it returns top-N tools with schemas, which differentiates it from the sibling tools that perform actual data operations.

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 guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent exactly when to use it and implies when not to (i.e., when a single specific tool is already known).

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

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

Annotations already cover readOnly/idempotent/destructive=false, so the description adds value by describing the multi-source fan-out (SEC, XBRL, USPTO, GDELT/GNews, GLEIF), patent sunset soft-fail behavior, and news fallback chain. It doesn't mention rate limits or error cases, but the added context is substantial.

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

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

The description is dense but each sentence earns its place: example phrases, explicit usage preference, source fan-out details, and return field enumeration. It is packed but not wasteful, though it could be slightly more scannable with 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?

With no output schema, the description fully enumerates the return shape: cik, company_name, recent_filings with URI templates, fundamentals with sort order, patents with sunset caveat, news fallback, and LEI. It also covers input constraints and the resolve_entity path, making it highly complete for a multi-source info 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%—both parameters have detailed descriptions including the name limitation and ticker/CIK format. The description reinforces with concrete examples (AAPL, 0000320193) but adds little beyond what the schema already states, so it stays at the baseline for high coverage.

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

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

The description clearly states the tool builds a full cross-source profile of a US public company in a single parallel call, with concrete example phrasings. It also distinguishes itself from siblings by explicitly saying to prefer it over chaining single-pack SEC/XBRL/news 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?

Explicit guidance is provided: use for holistic 'tell me about X' queries, prefer over chained single-source lookups, and use resolve_entity when only a company name is available. This directly addresses when and when not to use the 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?

The annotations already declare destructive and idempotent hints, but the description adds context about what exactly is destroyed (a stored memory by key) and why (clearing sensitive data). This provides additional behavioral insight beyond the structured annotations without contradiction.

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

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

The description is three sentences with no wasted words. It front-loads the core action, then adds usage guidance and tool relationships, all essential and concise.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, use cases, and relationship to sibling tools. The annotations handle safety aspects, making this description complete for an agent to select and invoke correctly.

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

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

Schema coverage for the single 'key' parameter is 100%, so the description does not need to explain it in detail. The description merely reinforces 'by key' without adding new parameter semantics, aligning with the baseline for high schema coverage.

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

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

The description uses the specific verb 'Delete' and resource 'previously stored memory by key', clearly distinguishing it from sibling tools like remember and recall. It fully clarifies the tool's function, going beyond the vague name/title.

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

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

The description explicitly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and references complementary tools (remember, recall). However, it lacks an explicit 'when not to use' exclusion, so it stops short of the top score.

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

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

Annotations already declare read-only and idempotent behavior. The description complements these hints by outlining the workflow ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and the output shape ('single text blob'), adding value without contradicting the annotations.

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

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

Four sentences, front-loaded with primary purpose, then process, output, and use cases. Every sentence carries information, with no filler or redundancy.

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

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

The description covers what, how, output format, and example scenarios. With no output schema, it still clearly conveys the result ('standard llms.txt markdown format'), making it complete for the tool's low complexity.

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

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

Input schema covers both parameters (url, max_links) with full descriptions (100% coverage), so the description doesn't need to repeat them. The description adds minimal extra parameter semantics, but the schema already does the heavy lifting.

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

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

The description uses a specific verb ('Generate') and concrete resource ('llms.txt file for any URL'), and names target AI crawlers. It clearly distinguishes itself from sibling tools by focusing on the standardized llms.txt 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?

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which makes the intended context clear. It does not mention sibling alternatives or when NOT to use the tool, so it falls short of the highest bar.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds a key behavioral detail: it returns an image URL. No contradiction with annotations.

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

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

Two short sentences, front-loaded with the core purpose and an immediate instruction. No wasted words.

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

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

The tool is simple: one parameter, output schema exists, and the description covers the essential use case. No additional context is needed for correct invocation.

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

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

Schema coverage is 100% and the status_code parameter is well-described with examples. The description repeats this information ('Provide the code (e.g., 200, 404, 500)') without adding new semantics, so the baseline 3 is appropriate.

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

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

The description uses a specific verb-resource pair ('Get a cat image representing an HTTP status code') and clearly defines the tool's scope. It is unambiguous and distinct from the unrelated sibling tools.

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

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

The description gives clear context: call it when you need a cat image for an HTTP status code, and explicitly instructs to provide the code with examples. It does not mention exclusions or alternatives, but no closely related tools exist among siblings.

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

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

Annotations already establish this as a read-only, idempotent, non-destructive, open-world operation. The description adds useful context by specifying that it returns all codes with descriptions and cat image URLs, which goes beyond the annotations without contradicting them.

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

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

The description is only two sentences, both of which earn their place: the first states the action and content, the second clarifies the intended use. There is no redundant phrasing or filler.

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

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

This is a simple tool with no parameters, and the annotations cover safety aspects. The description gives sufficient context about what the tool returns and when to use it. The output schema likely covers return structure, so no further detail is needed.

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

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

The input schema has zero parameters and schema coverage is 100%, so the baseline is 4. The description does not need to explain parameters, and it does not add any parameter-specific information, which 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: 'Browse all available HTTP status codes with descriptions and cat image URLs.' It uses a specific verb ('browse') and a specific resource ('all available HTTP status codes'), and it distinguishes itself from siblings like get_status_cat by emphasizing the comprehensive listing of all codes.

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

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

The description provides clear context for when to use the tool: 'Use to find the right code for your status or explore available options.' It does not explicitly mention alternatives or exclusions, but the context is sufficient for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavior context by detailing the exact return fields and the ability to optionally include inactive subscriptions, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, then returns fields, then usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

For a simple read-only tool with one optional parameter, the description covers its output (return fields), use case (review before subscribing/unsubscribing), and safety (via annotations). No output schema is needed because the return fields are explicitly listed.

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

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

Schema coverage is 100% with a well-described boolean parameter (include_inactive). The description does not add parameter-level details, but the schema is sufficient. The baseline of 3 applies when the schema does the heavy lifting.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes this from sibling subscription tools like subscribe and unsubscribe by focusing on the listing action.

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

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

The description gives clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use the tool relative to subscribe/unsubscribe, though it does not explicitly name alternatives or exclusions.

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

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

Despite annotations being largely false/neutral, the description richly discloses behavior: filing without an account returns a claim_token, the token can be reused to read the fix status, rate limiting is 5 per identifier per day, and it doesn't count against tool-call quota. This goes well beyond the annotations.

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

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

The description is relatively long but every sentence adds critical operational detail: purpose, when-to-use, when-not-to-use, token mechanics, rate limits, and roadmap impact. It is front-loaded with the core purpose and efficiently 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?

Even without an output schema, the description explains the return behavior (claim_token and later status retrieval), describes all parameters adequately, and covers edge cases like wrong server and unknown ownership. It is fully complete for a feedback-reporting tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for 'claim_token' (explains the pwfb_ prefix and reuse pattern) and clarifies the expected message format and length, raising it to a 4.

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

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

The description states a specific verb-resource pair ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly distinguishes this from sibling tools like ask_pipeworx and discover_tools by focusing on feedback delivery rather than querying or 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?

Provides explicit when-to-use guidance: bug reports, feature/data_gap requests, and praise. It also gives a clear exclusion ('ONLY for tools served by this Pipeworx connection... file it with that server instead') and even explains the alternative action to take when the tool belongs to another MCP server.

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, openWorldHint, and destructiveHint=false, but the description adds valuable behavioral context: it is 'self-aggregating signal' derived from 'CF analytics-engine', contains 'no PII', and is 'cached 5min-1h depending on window'. These details inform the agent about data freshness and privacy implications beyond what annotations provide.

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

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

The description is well-structured and front-loaded with the core purpose. It includes necessary details (use cases, data source, caching) in a compact form. Every sentence contributes value, and the list format for use cases is scannable. It is not overly verbose despite covering multiple aspects.

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

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

The tool has no output schema, so the description carries the burden of explaining returns, which it does ('top tools, top packs, and total call volume'). It also covers window semantics, use cases, data origin, privacy, and caching. This is fully complete for a simple, read-only, one-parameter tool.

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

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

The input schema covers 100% of the parameter meaning (window enum with description explaining shorter vs longer windows). The tool description repeats the same window explanation but does not add further semantic detail. Since schema coverage is high, the baseline of 3 is appropriate; the description neither enhances nor detracts.

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

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

The description clearly states the tool's purpose with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume over a recent window'). It explicitly targets 'What other AI agents are calling on Pipeworx right now', which differentiates it from sibling tools like discover_tools (which likely lists available tools, not usage trends). The purpose is unambiguous and distinct.

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

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

The description provides explicit use cases ('Useful for: (1) discovering what data sources are hot... (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns...'). This gives clear context for when to use the tool. However, it does not name alternatives or specify when-not-to-use, which would be needed for a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral detail beyond those. It explains monotonicity checking, partition-sum deviations, the 3pp threshold, semantic similarity anchoring (Jaccard ≥0.30), placeholder filtering (20% threshold), and the fill check pricing against live CLOB depth with a clear warning about realizable_edge_pp ≤ 0. This goes far beyond the annotations.

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

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

The description is long, but it is densely packed and organized with bolded section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. Every sentence contributes operational guidance, though some detail (e.g., full examples for topic) could be trimmed without losing core meaning. It is appropriately sized for a complex tool, but not maximally concise.

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

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

There is no output schema, so the description must explain return values, and it does: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}.' It also covers edge cases like filler filtering and fill-check conditions, making it complete for a tool with this complexity.

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

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

Schema coverage is 100% with both parameters described, but the description adds critical semantic context. For `event`, it explains that it walks child markets, checks date-axis/threshold-axis ordering, and computes partition checks; for `topic`, it explains cross-event search, flattening, and union-based comparison. It also provides realistic examples for both parameters, enriching the schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on cross-market arbitrage rather than single-position edges or fill risk assessment.

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

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

The description provides explicit usage modes: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends when to use each mode and points to a sibling tool for custom sizing ('For custom sizing use polymarket_fill_risk'). However, it does not explicitly state when not to use this tool versus other Polymarket siblings, so it falls short of a 5.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds rich behavioral details: the KV-level 1h cache keyed on all knobs, the rare-by-design longshot gates, the diagnostics funnel for empty segments, and the 24h-move warning. These behavioral traits go far beyond what annotations alone convey.

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

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

The description is long but justified by the tool's complexity. It is front-loaded with the core purpose, then logically structured into model families, tradeable-edge knobs, and response top-level. It uses clear groupings and distinct sections, though it is dense enough that some sentences could be trimmed without loss.

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 takes full responsibility for explaining the response shape: by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It also details per-opportunity fields (edge_pp_net, kelly_fraction, etc.) and explains why segments may be empty. This is complete for an agent to invoke and interpret the tool correctly.

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

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

The input schema provides 100% description coverage for all 9 parameters, so the baseline is 3. The description reinforces the 'tradeable-edge' concept for min_liquidity, max_spread_pp, and min_partition_leg_kelly, but does not add meaningful new syntax or semantics beyond the schema already provides.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement and the three model families. The 'what should I bet on today' framing makes its unique value explicit.

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 strong context: 'Built for "what should I bet on today"' and explains tradeable-edge knobs and filtering behavior. However, it does not explicitly name alternative tools or state when NOT to use this tool (e.g., versus polymarket_arbitrage), so it lacks explicit exclusionary guidance.

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

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

Even with annotations declaring readOnly, openWorld, idempotent, and non-destructive behavior, the description adds rich behavioral context: snapshots written on cache-miss, gaps meaning 'nobody scanned that day,' history bounded by 60-day TTL, decay computed from daily closes not intraday, and the meaning of negative edge_pp_net (SELL YES). This far exceeds what annotations provide.

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

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

The description is well-structured with a lead statement, explicit 'Args:' section, 'RESPONSE:' section detailing output fields, and 'LIMITS:' section for caveats. It is lengthy but every sentence provides necessary operational or interpretational information. No fluff.

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

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

With no output schema and only 2 parameters, the description fully compensates by detailing the exact response format (tracked[], expired[], snapshot_dates[]), the semantics of each field (trend states, decay_pp_per_day, lifespan_days), and the data limitations. This is a complete spec for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining 'days' as lookback with default/max, and 'window' as the snapshot family (24hr | 1wk | 1mo). It goes beyond the schema by connecting these to snapshot_dates and decay calculations, though most parameter details are already in 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 leads with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes its scope (tracking edge persistence/decay over time) from sibling tools like polymarket_edges (which likely provides current edges). The stated question 'how long has this edge existed and is it shrinking?' precisely defines the tool's purpose.

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

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

The description provides clear context for when to use the tool ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains the data caveats (TTL, snapshot gaps, daily vs intraday). However, it does not explicitly name alternative tools or state 'use X for current edge data,' so it stops short of full when/when-not 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 discloses behavior well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). It reveals it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and highlights the risk of partial fills and 'forced_directional_risk' — all without contradicting annotations.

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

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

The description is dense but appropriately structured: it leads with the core purpose, then sequentially explains SINGLE-MARKET and BASKET modes with explicit return fields and risk notes. Every sentence earns its place, and the use of uppercase mode labels aids scannability for an AI agent.

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

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

The tool has no output schema, so the description takes on the burden of explaining return values — and it does so thoroughly, listing specific fields per mode, the verdict categories, and the risk concept of unhedged directional positions. It fully contextualizes the tool's complexity and use case.

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

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

Although the schema already has 100% parameter descriptions, the tool description adds critical semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market vs 'settlement notional S (shares per leg)' in basket, side defaults are explained, and the market vs event modes are clarified. This enriches the 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explicitly ties itself to sibling tools ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'), making its purpose unmistakable.

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

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

Usage is explicit with concrete triggers: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale ('theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position') and provides mode-selection guidance (market vs 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by revealing behavioral nuances: it explains how the tool handles non-equivalent bet shapes, when compatibility_warning fires in two distinct scenarios, the meaning of temporal_alignment (aligned:false makes spreads meaningless), and how skipped_cross_type/subtype counters reflect dropped comparisons. This extra context helps the agent predict the tool's behavior and interpret results accurately.

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

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

The description is long but well-structured: it starts with a one-sentence purpose, then uses labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) to organize details. Every sentence adds value, explaining modes, output fields, and edge cases. It is front-loaded with the core purpose, and while it may be more verbose than simple tools, the complexity justifies the length.

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

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

With no output schema, the description fully compensates by explaining the response structure: per-venue leg-by-leg prices, matched spread's top_spreads_pp, compatibility_warning scenarios, temporal_alignment, and skipped counters. It covers edge cases and interpretation guidance, making the tool's behavior complete enough for an agent to use without prior knowledge. The only minor omission is exact JSON formatting, but the field names and semantics are fully disclosed.

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

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

Although the schema already describes all three parameters (100% coverage), the description adds crucial semantics: it lists the 10 valid topic shortcuts, explains that explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, and clarifies how the two modes interact. This gives the agent a richer understanding of parameter combinations beyond the bare schema descriptions.

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

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

The description opens with a crisp statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource (spread between two venues) and distinguishes itself from siblings by focusing specifically on Kalshi–Polymarket comparison with compatibility checks. The mention of 'spread' and 'same resolving question' makes the tool's function unmistakable.

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

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

The description explicitly details two usage modes (topic shortcuts vs explicit tickers) and provides clear guidance on when to expect compatibility warnings, even cautioning that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly name alternative tools from the sibling list (e.g., polymarket_arbitrage), but the mode guidance and warning about tradeability give enough usage context for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavior: listing all keys when key is omitted, and scoping to the agent identifier (anonymous IP, BYO key hash, or account ID). It does not mention error behavior, but the essential behavioral nuances are disclosed.

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 concise sentences, front-loaded with the core action. No redundant phrases; each sentence provides distinct value: function, usage, and scoping.

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

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

Given the simple one-parameter structure and no output schema, the description covers purpose, usage, scoping, and relationships with sibling tools. It explicitly explains both retrieval and listing behaviors, which fully supports an agent's invocation decision.

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% since the only parameter 'key' has a clear description ('Memory key to retrieve (omit to list all keys)'). The tool description reiterates the omission behavior but does not add meaningful detail 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 opens with a specific verb phrase 'Retrieve a value previously saved via remember' and clearly distinguishes the two modes (get by key, list all keys). It also differentiates from sibling tools remember and forget by naming them directly.

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: 'look up context the agent stored earlier'. It also provides alternatives: 'Pair with remember to save, forget to delete.' This gives a clear when/alternatives 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 explicitly states that mark_read:true flags returned events as read, affecting future calls, which contradicts the readOnlyHint=true annotation. This is an annotation contradiction, so the score is 1 regardless of other behavioral details.

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

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

The description is three sentences long, front-loaded with the purpose, then return fields, filtering, and an alternative access method. Every sentence earns its place 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?

The description thoroughly explains the return payload fields, filtering options, mark_read side effects, and an alternate URL. With no output schema, the description compensates well, though the annotation contradiction slightly undermines overall 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?

The schema covers all 5 parameters with descriptions (100% coverage), giving a baseline of 3. The description adds extra meaning by giving an example type (sec_8k), explaining the effect of mark_read on subsequent calls, and clarifying the 'since' filter as ISO timestamp, which exceeds baseline.

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

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

The description clearly states it pulls fired events from a subscription feed and returns recent alerts, using a specific verb and resource. It distinguishes itself from siblings like recent_changes and list_subscriptions by focusing on alert events.

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

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

The description mentions that polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, giving clear context for when to use the tool. It doesn't explicitly exclude or compare against sibling alert tools, but the guidance 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 signal read-only, idempotent, open-world, non-destructive behavior. The description adds valuable behavioral context: it mentions fanning out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to PatentsView sunset, and the structured return format. 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 dense but front-loaded with user-intent examples, then covers sources, fallbacks, parameter behavior, output shape, and the alternative tool. It is slightly long with semicolon-heavy clauses, but every sentence contributes meaningful information with minimal fluff.

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

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

Given there is no output schema, the description adequately explains return values (changes[], total_changes, citation URIs). It covers input formats, source behaviors, fallbacks, and the key sibling alternative, making it complete for a moderately complex tool.

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

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

Schema coverage is 100%, with each parameter already described (type enum, since format examples, value formats). The description repeats the `since` relative/ISO detail but adds no new parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly defines the tool as a 'change feed for a company in the last N days/weeks/months', anchored by natural-language user intents. It distinguishes itself from sibling tool entity_profile by explicitly stating when to use that alternative instead.

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

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

The description gives explicit usage context through example queries ('What's new with X', 'updates on Acme') and states a clear alternative: 'Use entity_profile instead when you want the static profile'. It also explains source-specific fallback behavior, helping the agent decide when this tool fits.

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 write, idempotent, and non-destructive behavior. The description adds substantial context beyond that: scoping by identifier, persistence differences for authenticated vs anonymous users, and retention duration (24 hours). This enriches the agent's understanding of what happens when the tool is invoked.

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

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

The description is three sentences, each serving a distinct purpose: stating the primary function, providing usage guidance with examples, and explaining behavioral details. It is front-loaded with the core purpose and contains no redundant or filler content.

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

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

Given the annotations and schema, the description provides a well-rounded understanding: what it saves, when to use it, how it behaves (scoping, persistence), and how it relates to sibling tools. It is complete enough for the agent to select and invoke correctly without additional 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?

The schema provides 100% coverage with detailed descriptions for both key and value. The description adds use-case examples but does not fundamentally change parameter semantics. Baseline 3 is appropriate since the schema carries the explanatory 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 states the tool saves data for later reuse, using the specific verb 'Save' and resource 'data the agent will need to reuse later'. It distinguishes from siblings by framing the memory lifecycle with recall and forget, making its role unique.

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

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

The description explicitly states when to use it ('Use when you discover something worth carrying forward') and names alternatives for related operations ('Pair with recall to retrieve later, forget to delete'). It also clarifies persistence contexts across sessions, giving the agent clear decision criteria.

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

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

Despite annotations already declaring readOnlyHint, idempotentHint, and non-destructive behavior, the description adds significant context: internal cascading lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit labeling of sources for identifiers, and that unresolved identifiers appear under `unresolved` rather than omitted. This goes well beyond what annotations provide.

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

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

The description is long but well-structured, opening with examples and a direct purpose, then providing detailed but relevant information per entity type. Every sentence adds value; the density is justified by the tool's complexity. A shorter version might omit necessary fallback 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?

This tool has no output schema, so the description must explain return structure. It does: source-labelled identifiers, explicit `unresolved` field, and graceful degradation. It covers all input forms, supported entity types, and the tool's internal behavior. Nothing critical is missing for an agent to use the tool effectively.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description enriches this by giving concrete examples ("AAPL", "0000320193", "ozempic"), clarifying that `value` can be a ticker, CIK, or name for company, and brand/generic for drug. It also explains the type-specific outputs, helping the agent choose the right `type` 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 starts with example queries and a clear statement: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It specifies distinct behaviors for company (CIK, ticker, LEI, FIGI) and drug (RxCUI) types, and explicitly says "Use FIRST whenever you have a name but need an ID," distinguishing it from sibling tools that consume identifiers.

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

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

The description gives explicit usage direction: "Use FIRST whenever you have a name but need an ID." It also describes fallback behavior and supported input types, implying when it is appropriate. However, it does not explicitly mention when not to use it or name alternative tools, leaving some gaps in exclusion criteria.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by revealing that it probes each entity via ai_visibility_check, ranks by score, and returns a structured output. This explains the underlying mechanism and output behavior without contradicting the read-only hint.

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

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

The description is four sentences, each serving a purpose: main function, mechanics, use case, and output. It is front-loaded and free of fluff. Every sentence adds value, making it appropriately concise 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 tool's complexity (meta-tool invoking another tool, ranking, output structure) and lack of output schema, the description covers the essential aspects: it states the return format ('ranked list with score, confidence, signal density per entity') and provides a concrete usage scenario. It does not explain ranking metric nuances, but the provided information is sufficient for most invocation contexts.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning to the 'entities' parameter by stating 'First entry treated as the "subject" for narrative; rest are competitors.' This clarifies the role of the first entity, which is not evident from the schema alone, justifying a 4.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It uses specific verbs (compare, probes, ranks, surfaces) and uniquely identifies the resource (AI visibility). It distinguishes from sibling tools by explicitly referencing ai_visibility_check and emphasizing multi-entity comparison, making it distinct from the single-entity counterpart.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with an example query. This gives the agent context on when to deploy the tool. However, it does not explicitly contrast with alternatives like ai_visibility_check or state when not to use it, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses failure behavior and latency: 'bundlephobia's first measurement on a new version can take 5-30s', 'Partial failures degrade gracefully', and 'sources_failed will list it if it times out'. These are valuable operational traits not inferable from annotations alone.

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: it covers the composite workflow, trigger phrases, returned fields, ecosystem scope, and error handling. It is front-loaded with the primary purpose and contains 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 (fans out to two external services, optional version parameter, no output schema), the description compensates well by enumerating the summary block fields, explaining partial-failure semantics, and noting the first-call latency. It gives an agent enough context to invoke the tool correctly and interpret results.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (package name with scoped-package support, version with example). The description only uses illustrative examples ('lodash', '18.3.1') and adds no additional semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Composite "should I add this npm package to my project" check in ONE call' and explicitly names the data sources (deps.dev, bundlephobia). This clearly distinguishes it from sibling research tools by focusing narrowly on npm dependency evaluation.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a concrete alternative for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', making the usage boundary clear.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses the underlying method (BGE-base-en embeddings + cosine over 500-char windows), the 200K character limit with truncation and flagging, and the output's inclusion of character offsets for verification. These behavioral traits are not captured in annotations.

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

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

The description is front-loaded with a clear one-line purpose, followed by usage guidance and implementation details. It's slightly longer than the minimum but every sentence provides value; no filler.

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

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

Given there's no output schema, the description adequately explains the return format (passages, offsets, similarity scores), operational limits (truncation), and how the tool fits into a larger workflow (pairing with ask_pipeworx_grounded). The tool's complexity is moderate, and the description covers the essential contexts.

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

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

The input schema provides 100% coverage with descriptions for all three parameters (text, limit, query), including default and max values. The description reinforces their usage but doesn't add substantive new meaning beyond what the schema already contains.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' using a specific verb and resource. It explains what is passed (text + query) and what is returned (top-N passages with character offsets and similarity scores), clearly distinguishing it from external search tools or other sibling tools.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and names a complementary tool, ask_pipeworx_grounded, for a two-step workflow. This gives clear when-to-use guidance and differentiates from 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 substantial behavioral context beyond annotations: OAuth requirement, return of subscription id, feed always-on behavior, SMS phone verification and 10/day cap, webhook HMAC signing and auto-disable after 10 consecutive failures. It also explains the single-return of webhook_secret, giving a comprehensive picture. 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 dense single paragraph that repeats information already present in the schema (e.g., delivery channel constraints) and is not well-structured. It also lists only three of the five supported types, omitting patent_grant and clinical_trial, making it incomplete and potentially misleading. The front-loading of the main purpose is positive, but the overall verbosity and redundancy hurt.

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

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

For a tool with 3 params, 100% schema coverage, and no output schema, the description covers auth requirements, return id, delivery options, and constraints. However, it fails to mention two valid subscription types (patent_grant, clinical_trial) from the schema, which is a notable gap. The schema compensates for this, but the description's partial list is incomplete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds concrete examples (e.g., sec_8k items:["5.02"] = officer change, polymarket_edge topic:"fed") and clarifies the always-on feed, which are not in the schema. This raises the score to 4, though it does not fully compensate for missing 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?

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' which clearly specifies the action and resource. It also states the return value (subscription id) and distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing solely 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 provides clear context about when to use the tool (creating subscriptions) and includes prerequisites like requiring a Pipeworx OAuth account and exclusions for anonymous/BYO users. It does not explicitly name alternatives like list_subscriptions, but the action is distinct enough that the intended usage 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?

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, providing a safety profile. The description adds valuable behavioral context: it returns live catalog data, organizes results by category, and supports optional topic filtering. It also clarifies the output shape (example questions with tool+argument pairs), going beyond what annotations alone convey.

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

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

Though long, every sentence in the description earns its place. It front-loads the example queries, then concisely explains the output, the catalog source, the optional parameter, and the recommended usage. The structure is logical and free of fluff.

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

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

For an onboarding tool with no output schema, the description is remarkably complete. It explains what the tool returns, how to invoke it (with or without a topic), when to prioritize it, and what meta-tools it teaches. The rich annotations further reduce the need for extra safety disclaimers.

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

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

The schema already describes the optional 'topic' parameter with allowed values, so baseline is 3. The description adds extra semantics by giving concrete examples (finance, pharma, betting) and explaining the default behavior when the parameter is omitted ('full spread'). This enriches the meaning beyond the schema.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. It distinguishes itself from siblings by positioning as a first-stop discovery tool and explicitly names meta-tools like ask_pipeworx, entity_profile, and compare_entities.

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It clearly indicates when to use it, though it does not explicitly state when not to use it. The context is sufficient for an onboarding tool.

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

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

Beyond the annotations, the description adds valuable behavioral context: ownership is enforced, the row is deactivated (not deleted), and historical events remain available via recent_alerts. This clarifies the side effects and how it interacts with other data, fully exceeding what annotations alone provide.

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

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

The description is two sentences, front-loaded with the core action ('Cancel a subscription by id') and immediately followed by key constraints. No wasted words; every sentence adds essential 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 one-parameter action, the description covers the purpose, ownership rules, and post-action effects. With annotations handling safety profile and schema covering the parameter, there are no major gaps. It mentions how historical events are preserved, which is important contextual information. No output schema exists, but the description doesn't need to explain return values for this simple cancellation operation.

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

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

The input schema already provides 100% coverage of the single parameter 'id', including its type and that it is a subscription uuid returned by subscribe. The description does not add additional parameter meaning beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Cancel' with a clear resource 'subscription' and parameter 'by id'. It clearly distinguishes itself from sibling tools like subscribe and list_subscriptions by describing the action and scope. 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?

The description clearly implies when to use this tool: to cancel a subscription you own. It warns about ownership enforcement, which is a usage constraint. However, it does not explicitly state when not to use it or mention alternatives like list_subscriptions or subscribe, so it stops short of a 5.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive, but the description adds critical semantics: could_not_verify means the check failed and is NOT evidence, unsupported means no source covers it. It also discloses the structured vs. grounded pipeline behavior and the verification_error payload.

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

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

Although lengthy, every sentence serves a purpose: trigger examples, routing logic, verdict enum, error semantics, and the benefit of replacing many calls. Front-loaded with user-phrase examples and usage, making it dense yet efficiently scannable.

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

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

No output schema exists, so the description fully explains the return structure (verdict list, actual value with citation, and reasoning) as well as edge cases (could_not_verify, unsupported). It covers routing, error handling, and caller guidance, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% (claim, tolerance_pct), but the description enriches both parameters: claim gets concrete examples, and tolerance_pct gets guidance on overriding implied tolerance, including a specific 1–2 range for hallucination detection and default cap of 5. This is meaningful 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?

Description clearly states the tool performs natural-language claim verification against authoritative sources, with examples of trigger phrases. It distinguishes itself by explaining the two routing paths (SEC EDGAR for company financials, grounded pipeline for other facts) and the verdict list, making it unique among siblings.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies routing for both company-financial and other claims. It does not explicitly name alternatives or when-not-to-use cases, but the scope is clearly defined.

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