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 signal read-only, open-world, idempotent, and non-destructive behavior; the description adds useful beyond-annotation context about automated routing, argument filling, and stable citation URIs. It does not contradict annotations and gives the agent a realistic picture of what happens after invocation.

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 'PREFER OVER WEB SEARCH' and is densely informative, with the key routing behavior stated early. The examples are useful, though 'even if web search could also answer it' appears twice and creates minor redundancy.

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

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

For a broad fact-answering tool with strong annotations and 100% schema coverage, the description provides enough to invoke correctly: when to use, what to pass, what happens, and what output to expect. It could be more complete by explicitly addressing the sibling variants `ask_peworx_beta` and `ask_peworx_grounded`, but it is otherwise self-sufficient.

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

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

Schema coverage is 100%, so the input schema already fully documents the aliases and the `question` parameter. The description adds value by framing the input as a natural-language question, supplying example phrasings, and noting that the tool fills underlying tool arguments itself — meaning callers only need to provide a question.

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

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

The description clearly states what the tool does: routes natural-language factual questions to 5,798 tools across 1,517 verified sources and returns structured answers with pipeworx:// citation URIs. It also distinguishes itself from web search, but it does not differentiate among sibling tools like ask_peworx_beta or ask_peworx_grounded, so it stops short of a perfect score.

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

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

Usage guidance is explicit and actionable: it tells the agent to prefer this over web search, lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'current'), enumerates domains, and provides concrete examples. It lacks explicit when-not-to-use guidance and named alternatives beyond web search, so it misses 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?

Beyond the read-only/idempotent annotations, the description discloses dynamic behavior: candidate routing improvements are enabled live only when under test, no candidate is active now, and it falls back to nothing because it is a full working router. This gives an agent useful expectations about variability and reliability.

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

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

The description is front-loaded with the core distinction, then gives current state, usage, and a reassurance about fallback behavior. Every sentence contributes important context, with no redundancy or wasted wording.

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 experimental router with no output schema, the description covers what it is, how it differs from the stable version, current candidate state, usage conditions, and a key clarification that it does not fall back to a limited tool. The 'same response shape' reference ties return expectations to the well-known sibling. This is complete enough for an agent to call 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?

The input schema covers all parameters and their descriptions, so the baseline is 3. The description adds only that it accepts the same arguments as ask_pipeworx, which is helpful context but not new parameter-level detail 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 identifies this as the beta version of ask_pipeworx, an identical universal router with candidate routing improvements. It differentiates itself from the stable sibling by describing the experimental edge and explicitly noting it currently matches ask_pipeworx exactly.

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 gives explicit usage guidance: use it exactly like ask_pipeworx when you want the newest routing. It also implies the stable router is the alternative for comparison, though it could more sharply state when NOT to use the beta.

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

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

The description goes well beyond the annotations by disclosing the return shape, the explicit refusal mechanism with enumerated refusal_reason values, and the extra LLM call cost. It clearly communicates failure behavior and constraints without contradicting the readOnlyHint/idempotentHint annotations.

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

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

The description is dense but every sentence adds value: purpose, behavior, return contract, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with the most important distinguishing feature and uses compact structured lists rather than prose padding.

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 fully covers return values and refusal cases. It also provides context about routing, cost, and when to prefer this tool versus ask_pipeworx, making it self-sufficient for correct invocation and interpretation.

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

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

Schema description coverage is 100%, including alias documentation, so the description does not need to explain parameters. The description adds no parameter-level meaning, which is acceptable at 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 states a specific purpose: a hallucination-resistant answer mode that extracts answers only from tool results. It explicitly positions itself relative to ask_pipeworx, making the distinction clear to an agent selecting between 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?

It names the exact alternative (ask_pipeworx), gives the condition for choosing this tool ('whenever an answer will be quoted, cited, or acted on'), and explicitly says to prefer ask_pipeworx for casual lookups. This is complete routing 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 declare readOnlyHint=true and openWorldHint=true, which aligns with the description. The description goes far beyond annotations: account sign-in requirement, paid tier for 'thorough', time expectations (15-60s, up to ~90s), gap handling (gaps[] for unanswered facets), contradictions[] behavior, citation format details with stable pipeworx:// URIs, and the excerpting behavior for large records. This is rich behavioral disclosure with no contradiction.

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

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

The description is dense and information-rich but quite long and somewhat sprawling, with tangents and a near-garbled parenthetical about hop fields. While most sentences earn their place, the structure could be better front-loaded and trimmed. The first sentence packs account requirements before the core function; the core 'what it does' only appears mid-way through. It sacrifices readability for exhaustiveness.

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 2-param tool with a full input schema, no output schema, and no nested objects, the description covers everything an agent needs: prerequisites (account, paid tier), behavioral traits (parallel decomposition, gaps[] never invented, contradictions[], excerpting), time expectations, and fallback routing. The description is complete without needing an output schema because it explicitly describes the return packet structure.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaningful semantics beyond schema: it explains what 'depth' values do behaviorally (quick=3 facets/single hop; standard=adds gap-recovery + contradictions; thorough=paid, doubles facets, iterative leads chase) and expands on the 'question' parameter with examples. It doesn't fully enumerate all behaviors of each depth, but the additional context is substantial.

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 is exceptionally specific: it names a verb ('researches'), the resource (1,517 structured data sources via 5,798 tools), and the mechanism (parallel decomposition). It explicitly contrasts with open-web search and names a sibling (ask_pipeworx) to disambiguate. An agent can immediately distinguish deep_research from the 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 provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', with concrete examples. It also states when NOT to use it: 'For a single lookup use ask_pipeworx instead' and names the alternative for non-signed-in users. This is model guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds useful behavioral context 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?

The description discloses behaviors beyond the annotations: parallel fan-out across multiple sources, soft-fail for the USPTO sunset, empty-section semantics ('an empty section is a real no data, not a bug'), resolution behavior, and the meaning of sources_used/sources_failed. It also reveals internal details like URI format and sort order, which the annotations do not cover.

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

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

The description is quite long, but nearly every sentence carries functional load: examples, source list, return-field semantics, edge-case handling, and input flexibility. It front-loads purpose and usage, then packs details in a readable sequence. Slightly redundant phrasing like 'either way' and the FDA caveat could be trimmed, but the length is justified by 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 has two parameters, a broad multi-source scope, and no output schema, the description covers everything an agent needs: accepted input shapes, return-field semantics, failure modes, source-specific quirks, and resolution handling. The private-company behavior and the 'empty is real no-data' clarification prevent common misinterpretations. No critical operational detail is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description further enriches both parameters by clarifying that type accepts 'company' or 'ticker' interchangeably and that value can take a ticker, zero-padded CIK, or name shape, plus resolution caveats and the private-company fallback. It exceeds the schema's descriptions with concrete examples and behavioral nuance.

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: 'full cross-source profile of a US public company in ONE parallel call' and immediately differentiates from sibling tools by naming the alternative strategy it replaces ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'). It also provides varied example phrasings, making the intended invocation 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 gives explicit when-to-use conditions (user asks for a holistic view) and explicit exclusions ('a private company (no CIK/ticker) returns resolved:false with an explicit notes line'). It names the preferred alternative pattern (single-pack lookups) and tells the agent not to chain them, leaving no ambiguity about when to choose 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?

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?

With readOnly/openWorld/idempotent annotations already covering safety, the description goes well beyond them by disclosing the matching algorithm's caveats, compatibility codes, per-pair flags, skipped_unclassified legs, gross-vs-net fee handling, and the meaning of null temporal_alignment. It repeatedly clarifies that a non-empty compatibility field can appear even when pairs are returned, so the agent won't over-trust matched_pairs.

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 content is almost always substantive and the front matter is organized around TWO MODES / RESPONSE / SAFETY FIELDS, but it is long and repeats caveats (temporal_alignment_unknown is explained twice, and the compatibility warning readability advice appears both in the safety-fields sentence and in the closing warning). This is appropriate for a complex tool but 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?

Because there is no output schema, the description carries the full burden of explaining the response, and it does: per-leg prices, top_spreads_pp with flags, skipped_unclassified counters, compatibility codes, temporal_alignment semantics, and the fee disclosure. For a tool with zero required params and no output schema, the agent has enough context to call it 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 coverage is 100% and each parameter already has a description, so the baseline is 3. The description adds real semantic value by explaining that topic is a pre-mapped shortcut, the ticker/slug arguments are explicit overrides, and that both parameter modes execute the same token-overlap matching and disclosures—this is beyond the schema.

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

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

The description opens with a clear statement of scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and details two retrieval modes, so the agent knows what the tool computes. It does not explicitly differentiate from the closely named sibling polymarket_arbitrage or name alternatives, which keeps it a step below a fully distinguished definition.

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 mode-selection guidance: use the 10 pre-mapped topic shortcuts or supply explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, and notes that both run the same matcher. It also warns that pre-mapped topics often return compatibility warnings and 'pre-mapped ≠ tradeable', but it never states when to prefer a sibling tool such as polymarket_arbitrage.

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

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

Annotations already 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds substantial behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity handled via figi_candidates, explicit unresolved identifiers, source labeling, and ISIN-to-LEI mapping. No contradiction with annotations.

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

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

The description is long but front-loaded with examples and the 'Use FIRST' directive. Every major section earns its place, though some parenthetical detail could be tightened without losing key behavioral context.

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

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

With no output schema, the description compensates by explaining key return behavior: labeled identifiers, figi_candidates for ambiguous matches, explicit unresolved fields, RxNorm citations, and degradation behavior. Supported entity types and input expectations are covered thoroughly.

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

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

Despite 100% schema coverage, the description adds meaningful parameter guidance: exact accepted forms by entity type, examples for ticker, CIK, name, and drug names, plus a critical warning to pass only the issuer name for bonds and an illustrative failing example. This goes well 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 states a specific verb and resource: resolve a user-spoken name to canonical/official identifiers that other tools need as input. It also includes concrete examples ('What's the ticker for...', 'find the CIK for...') and distinguishes itself with 'Use FIRST whenever you have a name but need an ID.'

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 to use it first whenever a name needs an ID, and notes it replaces 2-3 manual lookups. However, it does not name specific sibling tools to use instead when the user already has an ID or needs a profile, so it falls short of full when/when-not/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?

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.