diceuear

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description adds value by disclosing the return structure (score, confidence, signals, raw_response, combined view) and the cost implication of using Anthropic (BYO key, paid directly to Anthropic). This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence provides essential information: function, output, model options, cost note, and use cases. 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?

Despite lacking an output schema, the description explicitly lists the per-model fields returned and the combined view. It covers use cases, default behavior, optional parameters, and payment implications. For a read-only, idempotent probe tool, this is comprehensive.

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 semantic meaning by indicating that the default model is Workers AI Llama-3.3-70b (free), that `_apiKey` is only required for Anthropic, and that `context` helps disambiguate common names. This enriches parameter understanding beyond the schema descriptions.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs') to clearly state the tool's function: assessing what LLMs know about a business/brand/product/topic and scoring visibility from 0-100. It distinguishes itself from siblings like ask_pipeworx (asking questions) and deep_research (in-depth research) by focusing on visibility auditing.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the `_apiKey` parameter (only if 'anthropic' is in models) and the default free model. It doesn't explicitly state when not to use it or mention alternatives, but the context is sufficient.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that it autonomously fills arguments, routes across 5,798 tools and 1,517 sources, and returns stable pipeworx:// citation URIs. It also notes live-news routing for breaking-news queries. There is no contradiction with 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 front-loaded with the key routing behavior and includes examples and exception routing. The domain list is detailed but useful for deciding when to invoke, so the prose earns its place despite being somewhat verbose.

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

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

For a natural-language router with one input parameter and no output schema, the description covers what it does, when it should be preferred, what it returns, and which siblings cover adjacent cases. It even addresses breaking news and current events, making it complete enough for reliable tool selection.

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

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

The schema already documents the single 'question' parameter with all aliases at 100% coverage, so the baseline is 3. The description goes slightly beyond it by stating accepted query forms and giving concrete domain examples, which helps an agent shape valid 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 states a clear verb-plus-resource behavior: it routes a natural-language question to one of 5,798 verified-source tools and returns a structured, cited answer. It also differentiates itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

It explicitly says to prefer this tool over web search, defines trigger phrases like 'look up' and 'get the latest', and gives concrete examples. It also explains when to step up to ask_pipeworx_grounded for verbatim evidence or deep_research for broad multi-part questions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context about the beta status, current candidate status (none active as of 2026-07-26), and that it currently matches ask_pipeworx exactly. It also discloses that routing improvements may be enabled live during tests.

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 efficient, front-loading the beta identity and the key fact that it currently matches ask_pipeworx. The parenthetical about retired candidates is slightly verbose but provides useful temporal context for behavior.

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

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

The description is complete for a simple one-parameter router tool with a rich annotation set. It explains the beta behavior, current state, and relationship to the stable sibling. Without an output schema, it could briefly note the response structure, but the statement 'same response shape as ask_pipeworx' covers that.

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

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

Schema description coverage is 100%, so the schema fully documents the question parameter and its five aliases. The description mentions 'same arguments' but doesn't add much beyond that; the schema already carries the parameter meaning.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with 5,798 tools, same arguments and response shape, and distinguishes it from the stable ask_pipeworx by its experimental routing improvements. It explicitly names the sibling tool ask_pipeworx and explains the difference.

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 to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to decide merges. It also clarifies that this is a full working router, not a fallback, which prevents misuse.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, so the description is free to add behavioral depth; it adds a lot: refusal semantics with concrete refusal_reason values, the 'ONLY what the tool result contains' extraction rule, the returned payload fields, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: mode, routing, extraction rule, return/refusal contract, use cases, and cost trade-off. The key differentiator is front-loaded in the first sentence, and no filler or redundant restatement of the title appears.

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

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

For a tool with one semantic parameter and no output schema, the description fully specifies the success and refusal return contract, the safety profile is covered by annotations, and the routing relationship to ask_pipeworx is clear. An agent has enough to select, invoke, and interpret the result correctly.

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

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

Schema description coverage is 100% and the schema itself thoroughly documents the single required question parameter, including six aliases. The description adds no parameter-level detail, which is acceptable because the structured schema already carries that 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 first phrase 'Hallucination-resistant answer mode for high-stakes reads' identifies a specific variant of a query tool with a clear purpose. 'Same routing as ask_pipeworx' plus 'EXTRACTS the answer using ONLY what the tool result contains' differentiates it from the sibling ask_pipeworx. The verb and resource are explicit and the name is not merely restated.

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 when-to-use conditions: 'whenever an answer will be quoted, cited, or acted on' and lists domains where invention is unacceptable. It also gives a clear alternative condition: 'prefer ask_pipeworx for casual lookups', plus the cost trade-off. This is exactly the routing guidance an agent needs.

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, but the description goes far beyond by detailing resolver confidence levels, blocking statuses ('low_confidence_match', 'market_closed_or_inactive'), GDELT fallback behavior, and cancellation-rule risk (flat-50¢ void settlements). This context is vital for agents to avoid sizing on phantom matches or misunderstanding void rules.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT) that make it scannable. There is some redundancy between SAFETY and RESOLVER CONTRACT regarding low-confidence matches, but every section contributes necessary context for this complex tool.

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

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

There is no output schema, so the description bears the full burden of explaining return values and edge cases. It thoroughly covers result.market, result.analysis, result.evidence, match confidence, parent events, news field fallbacks, and status codes, including wide-spread illiquidity and cancellation-rule impacts. This makes it complete for safe 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?

The input schema provides full descriptions for all three parameters (market, depth, include_raw), so the baseline is 3. The description does not add parameter-specific details beyond what the schema offers; its fan-out examples illustrate behavior but do not clarify the parameters themselves.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It directly distinguishes itself from sibling tools like polymarket_edges by focusing on a single bet's research, and it gives explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly mention when not to use it or name alternative sibling tools (e.g., polymarket_edges) for exclusion, 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?

Beyond the annotations (read-only, idempotent), the description discloses that the tool makes a parallel call, pulls latest 10-K data with correct off-calendar fiscal year handling, sorts results by primary metric, and returns citation URIs. This gives the agent a clear behavioral model 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 information-dense but not bloated. It front-loads trigger phrases and then packs data source, type-specific details, sorting, and output into a compact paragraph. Every sentence adds value, though it is longer than strictly minimal.

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

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

With no output schema, the description explains output ('paired data + pipeworx:// citation URIs'), sorting behavior, data sources, and parallel execution. It covers both types and examples, making the tool's behavior clear without missing critical aspects.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining what type='company' retrieves (revenue, net income, cash, long-term debt) and what type='drug' retrieves (adverse-event counts, FDA approvals, trial counts), and gives concrete value examples. This enhances the bare schema descriptions.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in ONE parallel call, with clear trigger phrases like 'Compare X and Y' and 'X vs Y'. It distinguishes itself from single-entity lookups by emphasizing parallel execution and covering multiple entity types.

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

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

Usage guidance is explicit: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and it differentiates when to use type='company' vs type='drug'. This tells the agent when to choose this tool over alternatives like entity_profile for multi-entity comparisons.

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 the description adds substantial behavior beyond that: parallel decomposition, gap handling with explicit gaps[] (never invented), contradictions[] for standard/thorough, semantic excerpting of large records, and expected latency. It also explains that citations are always resolvable, giving the agent a realistic execution model.

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

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

The description is long but front-loaded with the critical account requirement, and every section covers a necessary aspect (usage, behavior, output, latency, alternatives). Slight redundancy remains, for example the 'one call' idea appears repeatedly and ask_pipeworx is mentioned twice, keeping it just short of top marks.

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 correctly carries the burden of explaining the return shape: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], and contradictions[]. It also covers account tiers, latency, and what happens to multi-step questions, so an agent has enough to invoke and interpret the call 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 schema carries the parameter descriptions. The description adds useful new context by stating that depth:'thorough' requires a paid plan and that multi-step questions resolve in one call, which helps an agent choose the right depth. It mostly reinforces rather than redundantly restates the enum semantics.

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

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

The description states a specific action ('Grounded multi-source research') over a defined resource ('Pipeworx's 1517 STRUCTURED data sources') and immediately distinguishes itself from open-web search. It also names sibling ask_pipeworx as the tool for single lookups, so an agent can tell them apart.

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 is explicit about when to use deep_research ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx'). It also covers auth gating with a concrete alternative ('If you are not signed in, use ask_pipeworx instead'), and the depth tiers are mapped to plan paid/standard conditions.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond annotations: it returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes results are 'ready to call directly, no second schema lookup needed.' This clarifies the return format and reduces uncertainty.

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

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

The description is a single paragraph that front-loads purpose and usage, then explains return value and when to call. It is efficiently written, though the list of domains is somewhat long. Every sentence contributes to the agent's understanding, but the enumeration could be trimmed without losing core meaning.

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

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

Given no output schema, the description appropriately explains return values ('names, descriptions, and full input schemas'), provides usage direction, and clarifies the 'first step' context. It fully covers what an agent needs to know to decide whether to call this tool and what to expect.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including aliases and defaults. The description references 'top-N' which relates to the limit parameter, but does not add new semantic meaning 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+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools by positioning itself as a discovery/meta-tool that returns other tools, and it lists broad domains (SEC filings, FDA drugs, etc.) which further clarifies scope.

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: '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 directs the agent to use it as a first step for tool selection, which is clear and actionable.

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 annotations already indicating readOnly, idempotent, and non-destructive, the description goes well beyond by disclosing fan-out behavior, per-source soft-failures (USPTO sunset), 'sources_used/sources_failed' semantics, and the expectation that an empty section means genuine no-data, not failure. It also details private-company behavior explicitly.

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 appropriately so for a multi-source fan-out tool with many return sections. It is front-loaded with usage examples, then flows through accepted inputs, return payload, and edge cases in a logical order. Every sentence carries a distinct caveat or clarification.

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

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

Given the tool's complexity, the absence of an output schema, and the two-parameter input, the description is exceptionally complete: it enumerates all return sections, explains expected empty results, names the fallback chain (GDELT→GNews), and specifies accepted input forms. An agent can select and invoke this tool correctly with no further inference.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats and reinforces the schema's 'company'/'ticker' interchangeability and the value shapes, but adds little new parameter-level meaning beyond concrete examples like 'AAPL', '0000320193', and 'Moderna'.

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

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

The description opens with concrete user-phrase examples and an explicit anchor: 'full cross-source profile of a US public company in ONE parallel call.' It names the specific resource (US public company profile) and immediately differentiates from single-pack lookups, making the tool's 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?

The description directly states when to use this tool: whenever the user asks for a holistic view, and explicitly says to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also covers the private-company edge case (resolved:false with notes), giving an agent clear routing 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 include destructiveHint=true and idempotentHint=true. The description adds context about deleting 'previously stored memory' and 'sensitive data', which clarifies the purpose and consequences beyond the raw annotation. However, it does not detail behaviors like error handling or permission needs, so credit is moderate.

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

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

Two sentences efficiently state purpose and usage. Front-loaded with the verb and object, then followed by guidance. No unnecessary words or repetition.

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

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

For a simple one-parameter tool with strong annotations (destructive, idempotent), the description covers purpose, usage, and related tools. It does not explain the return value or behavior for missing keys, but given the lack of an output schema and the tool's simplicity, the description is sufficiently complete.

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

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

Schema has 100% coverage with the 'key' parameter described as 'Memory key to delete'. The description only reiterates 'by key', adding no new parameter semantics. Baseline 3 is appropriate as the schema carries the 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 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by pairing with 'remember' and 'recall', indicating this is the deletion 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?

Provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, giving context on related tools. No when-not-to-use guidance, but the positive guidance is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to repeat safety. It adds that the result is an SVG URL ready to display, which is useful context. No contradiction, but little extra behavioral detail beyond annotations.

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

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

One precise sentence, front-loaded with the action, includes parenthetical examples for clarity, no filler 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?

With two simple parameters, high schema coverage, annotations covering safety, and an output schema, the description is complete. It tells the agent what to expect (SVG URL) and how to call the tool.

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

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

Schema covers both parameters with descriptions, including the full style list and determinism seed semantics. The description's examples reinforce this but add no new meaning, so baseline 3 applies.

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

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

The description clearly states the tool generates a custom avatar SVG, specifies the two inputs (style and seed), and notes the output as an SVG URL. This is a specific verb+resource with distinct output, differentiating it from sibling tools like generate_llms_txt.

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

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

The description implies usage when an avatar is needed, and gives concrete examples of style values. However, it does not mention alternatives (e.g., list_styles to see available styles) or when not to use the tool, so guidance is minimal.

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 behavior, and the description adds process-level transparency by explaining it fetches the page, extracts metadata, and emits a text blob. It goes beyond the safety profile to describe the actual operational flow without contradicting any annotation.

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 plus a compact 'Useful for' list, all dense with information. It is front-loaded with the main purpose, followed by process, output, and use cases—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?

For a simple 2-parameter tool without an output schema, the description adequately covers the output format ('single text blob ready to drop at site-root/llms.txt') and the intended applications. It could be slightly more explicit about the return type (e.g., string), but it is otherwise complete enough for an agent to invoke correctly.

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

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

The input schema provides 100% coverage with clear descriptions for both parameters (url and max_links). The description reinforces the notion of links but doesn't add new syntax or formatting details beyond the schema, so it meets the baseline for high schema coverage.

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

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

The description opens with 'Generate a production-ready llms.txt file for any URL', using a specific verb and resource that clearly states the tool's function. It then details the process (fetch, extract title/description/key links, emit standard markdown), which distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

Concrete use cases are listed ('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 effectively communicates when to apply the tool. While it doesn't explicitly name alternative tools or exclude situations, the unique purpose among siblings makes the context clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the return value content ('style names and descriptions'), which goes beyond annotations and clarifies the output.

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 primary function, and includes a practical usage note. Every clause earns its place with no redundancy.

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

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

For a zero-parameter list tool with rich annotations and an output schema, the description fully covers the tool's behavior, return content, and how it fits into the broader avatar generation workflow.

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?

There are zero parameters, so the baseline for parameter semantics is 4. The description doesn't need to explain parameters, and the schema confirms the tool takes no 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 clearly states the verb ('List'), the resource ('all available avatar styles'), and the scope. It also explicitly connects the tool to generate_avatar, distinguishing its purpose from sibling tools.

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

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

The phrase 'use with generate_avatar to pick a style' provides explicit contextual guidance on when to use this tool. It does not list exclusions or alternative tools explicitly, but the context is clear enough for a simple list operation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the exact return fields ('id, type, params, created_at, last_fired_at, fire_count') and clarifying that it lists only the caller's subscriptions. 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 two sentences, front-loaded with the primary function, followed by return fields and usage guidance. No unnecessary words or repetition.

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

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

The tool is simple (one optional param, no output schema), and the description covers the core purpose, return fields, and typical use cases. With strong annotations and a clear schema, no further explanation is needed.

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

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

Schema coverage is 100% and the only parameter (include_inactive) is well-described in the schema. The description does not add any additional meaning about this parameter; it simply mentions 'active subscriptions' which aligns with the default behavior.

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

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

The description uses a specific verb and resource: 'List the caller's active subscriptions.' It clearly distinguishes the tool from siblings like subscribe and unsubscribe by focusing on the read-only listing of existing subscriptions.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It tells when to use the tool but does not explicitly name alternatives or state when not to use it.

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

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

Beyond the annotations (which indicate non-read-only, non-idempotent, non-destructive), the description adds important behavioral context: the claim_token follow-up mechanism, rate limiting to 5 per identifier per day, and that feedback is read daily and affects roadmap. This fully discloses side effects and operational nuances without contradicting the annotations.

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

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

The description is somewhat lengthy but every sentence adds value—covering when to use, exclusions, follow-up, rate limits, and impact. It is well-structured and front-loaded with the purpose, though it could be tightened slightly without losing 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?

Despite lacking an output schema, the description explains the response behavior (claim_token when not logged in, ability to check resolution later), rate limits, and that feedback is read daily. It also addresses the lack of required parameters. This makes the tool fully self-explanatory and complete for an agent to decide to use it.

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

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

The schema already provides 100% coverage with good parameter descriptions. The description adds extra semantics by explaining how to use claim_token for follow-up and advising users not to paste end-user prompts. This going beyond the schema justifies a 4 rather than a baseline 3.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly states the tool's function and differentiates it from sibling research/query tools like ask_pipeworx or deep_research. It is unambiguous about the feedback submission purpose.

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

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

The description explicitly lists when to use the tool: for bugs, feature/data_gap requests, or praise. It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with other MCP servers for unrelated tools. This is a strong, unambiguous usage guideline.

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

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

Beyond annotations, the description discloses behavioral traits: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This adds meaningful context about caching, data derivation, and privacy, which annotations do not convey.

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

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

Three sentences, front-loaded with the core purpose, followed by use cases and transparency notes. No redundant or excessive wording; 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers return structure ('top tools, top packs, and total call volume', 'just (pack, tool, count)'), caching behavior, and use cases, making it 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?

The schema covers the 'window' parameter thoroughly with its own description ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The tool description only mentions the window in passing without adding new semantic details, so the baseline of 3 applies.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('Returns') and identifies the resource, distinguishing it from siblings like discover_tools by emphasizing 'what other AI agents are calling on Pipeworx right now.'

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

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

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

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

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

The description goes far beyond the readOnly/idempotent annotations by disclosing internal mechanics: Jaccard similarity threshold (≥0.30), the >3pp deviation trigger, placeholder-slug filtering (20% threshold), null arb signal behavior, and the fill-check logic that prices against live CLOB depth. This level of detail gives the agent concrete expectations beyond what annotations provide.

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

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

The description is long but densely packed with high-value information, structured with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence serves a purpose: mode selection, parameter behavior, edge cases, response structure, and trading caveats. Given the three modes and complex logic, this is appropriately sized and front-loaded with the core purpose.

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

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

With no output schema, the description takes on the responsibility of explaining return values, and it does so thoroughly: opportunities[] with specific fields, partition_check object fields, and the fill-check output. It also covers edge cases like skipped_low_similarity and placeholder filtering, making the tool's behavior predictable in corner scenarios.

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

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

Although the schema already provides 100% coverage and descriptions for both parameters, the tool description enriches semantics by giving concrete examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explaining what each parameter triggers internally (walks child markets, flattens unions), and noting that full URLs are also accepted. This adds meaning that cannot be inferred from the schema alone.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (trending, event, topic) and clearly separates this from sibling tools by delegating custom sizing to polymarket_fill_risk.

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

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

Explicitly tells when to use no args for trending_scan, `event` for a specific market, and `topic` for cross-event scanning. It also provides decision guidance by explaining when NOT to trade (realizable_edge_pp <= 0) and points to an alternative tool for custom sizing, fulfilling both when-to-use and when-not-to-use 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?

The description goes far beyond the annotations, disclosing caching behavior ('Cached 1h at the KV level'), model-specific logic (e.g., 'lognormal barrier from 90d FRED log-returns', 'GDELT 7d/21d article-volume ratio'), and critical caveats like the 24h-move warning ('your edge may already be in the price'). It also explains why Fed bets are excluded from ranking, providing rich behavioral context not captured by readOnlyHint/idempotentHint.

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

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

The description is dense but well-structured, moving from purpose to model families to knobs to diagnostics to caching. Every sentence adds critical operational detail without redundancy. The front-loaded purpose statement ensures immediate clarity before the deeper mechanics.

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

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

Despite having 9 parameters and no output schema, the description delivers a complete picture: it details the response structure (by_segment, fed_candidates, _diagnostics), explains the tradeable-edge filters, and describes all model families. Callers understand what to expect and why certain outputs may be empty, making the tool fully self-contained 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?

Although the schema already provides 100% parameter coverage, the description adds significant meaning. For example, it explains the rationale behind min_kelly ('Skips opportunities that are too small to bet sensibly even if the edge is large'), nuances of slippage_pp ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade'), and clarifies min_partition_leg_kelly's special handling since parent-level Kelly is always 0 by design.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan/return), resource (Polymarket markets), and scope (top markets, opportunities). It also distinguishes itself by detailing the model families and segments, making its unique role in discovery evident.

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

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

The description offers extensive context on when to use the tool (e.g., 'Built for "what should I bet on today"') and detailed tuning guidance for knobs like max_spread_pp ('Set to 2 to require tight books') and min_liquidity ('Set to 5000 to drop thin-book opportunities'). It also explains diagnostics for reading empty segments. However, it does not explicitly name alternatives among sibling tools, so it falls short of the highest bar for when-not-to-use guidance.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds significant context beyond that: the 60-day snapshot TTL, history starting only when snapshotting was enabled, data gaps meaning 'nobody scanned that day', and decay computed from daily closes (not intraday). No contradictions.

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

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

The description is well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded purpose. Every sentence provides useful information, though the Args section duplicates the schema and the response section is lengthy but necessary given there is no output schema.

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

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

With no output schema, the description fully specifies the response structure (tracked[], expired[], snapshot_dates[]), including field semantics and data caveats (TTL, gaps, daily closes). It covers purpose, parameter defaults, response shape, and limitations, 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 description coverage is 100% for both parameters. The description's 'Args' section merely restates defaults and window family ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') without adding new 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 clear specific purpose ('Edge persistence and decay telemetry built from daily polymarket_edges snapshots') and explicitly answers the question 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges (which likely provides current edges) by focusing on historical persistence and decay.

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

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

The description provides clear context for when to use the tool by explaining the trade decision it supports ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly name alternatives or state when not to use this tool, though it implies complementing polymarket_edges.

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 cover readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), discloses partial-fill risks, and warns about forced directional risk in basket mode. These are not derivable from annotations and enrich the agent's understanding of side effects and limitations.

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

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

The description is long but meticulously structured: intro, REQUIRES, SINGLE-MARKET, BASKET, USE THIS. Every sentence carries critical information—no filler. The use of uppercase section labels aids scanning, and the risk warning at the end is concise yet impactful.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema) the description is remarkably complete. It lists all returned fields for both modes, explains the meaning of edge-specific metrics (capture_ratio, thin_legs, max_clean_notional_usd), and places the tool in the broader workflow by referencing sibling tools and real-world risk (unhedged directional positions).

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

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

Schema coverage is 100%, so baseline is 3, but the description significantly adds meaning: it explains size_usd semantics for both modes (max spend vs target proceeds in single-market; settlement notional in basket), the default side selection behavior in basket mode, and clarifies that each share pays $1. This goes well beyond the schema's short parameter descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and differentiates itself from sibling tools by referencing polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the required input mode (one of market or event) and the optional side/size_usd parameters, making the invocation conditions clear.

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

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

The description extensively discloses behavior beyond the readOnly/idempotent/non-destructive annotations: compatibility_warning and compatibility_codes can be non-empty even when matched_pairs>0, temporal_alignment_unknown is explicitly 'NOT the same as confirmed-aligned,' unclassified legs are never paired, flagged codes like pairing_unverified are explained, and every spread_pp is gross because Kalshi fees are not modeled. It also clarifies skipped_cross_type/subtype counters. This is exemplary transparency for a complex tool.

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 very long, dense paragraph with many clauses and code lists. It is front-loaded with the core purpose, but readability suffers from lack of bullet points or section breaks. Every sentence carries information, but the wall-of-text format makes it harder for an agent to quickly extract the two modes, the safety fields, and the caveats.

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 carries the burden of explaining return values: it details leg-by-leg prices, spread[].top_spreads_pp, compatibility_codes and their meanings, skips and skipped_* counters, temporal_alignment semantics including null handling, and the fees_note disclosure. Nothing an agent needs to interpret the response correctly 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?

Input schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that `topic` maps to 10 pre-mapped shortcuts, that explicit parameters 'override the topic-mapped' side, and that both modes run the identical token-overlap matcher. This enriches the agent's understanding of how the three optional parameters relate to each other.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly scopes the tool's output (leg-by-leg prices plus spread[].top_spreads_pp) and distinguishes it from a net tradeable edge by stating it does not model Kalshi fees. This differentiates it from siblings like polymarket_arbitrage without needing to name them.

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 presents two usage modes (topic shortcuts vs explicit ticker/slug pairings) and tells the agent when each is appropriate, including that explicit pairings are for 'custom pairings.' It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' which guides when results should not be trusted. It does not explicitly name alternative sibling tools, so it stops short of full when-to-use-vs-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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral depth by explaining scoping ('Scoped to your identifier – anonymous IP, BYO key hash, or account ID') and the optional-key listing behavior, which are not present in the annotations.

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

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

Four sentences, front-loaded with the primary action. Every sentence adds value: action, use case, scoping, and relationship to siblings. 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 tool is simple (single optional parameter, no return schema). The description covers purpose, usage, scoping, and sibling relationships. It implies the return type (value or list of keys) and is complete for this complexity level.

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

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

Schema coverage is 100% – the key parameter has a clear description ('Memory key to retrieve (omit to list all keys)'). The tool description echoes this and adds examples of key values, but does not significantly extend the schema semantics. Baseline 3 is appropriate given the 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 opens with a specific action – 'Retrieve a value previously saved via remember' – and clearly distinguishes the read/list behavior from the sibling tools remember and forget. It also provides concrete examples of stored context (ticker, address, research notes), leaving no ambiguity about 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?

Explicitly names when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It contrasts with remember (save) and forget (delete) by stating 'Pair with remember to save, forget to delete,' offering clear alternatives. This meets the bar for explicit alternatives, though it lacks an explicit 'when not to use' statement beyond the immediate sibling context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: the feed is persisted, returned events include specific fields, mark_read advances the read cursor so subsequent calls return newer events, and polling is supported. 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?

Every sentence earns its place: purpose, return payload, filtering, mark_read behavior, and alternative endpoint. It is front-loaded with the core action and remains concise 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?

Given 5 optional parameters, no output schema, and strong annotations, the description covers key user needs: what events are returned, how to filter, how to manage read state, and where to access the same feed programmatically. It is fully adequate for effective 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 provides 100% parameter descriptions, so baseline is 3. The description adds practical semantics: gives a concrete type example ('sec_8k'), explains the since parameter as ISO timestamp, and clarifies that mark_read affects future calls. This goes beyond schema descriptions, earning 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?

Description opens with 'Pull fired events from your subscription feed', a specific verb+resource statement. It further clarifies it returns recent alerts with source, citation_uri, and raw payload, distinguishing it from sibling tools like list_subscriptions or recent_changes.

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 clear context: use it to poll for fired alerts, filter by type/since, and advance read state with mark_read. It explicitly offers an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly compare to sibling tools or state when-not-to-use, 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?

Adds significant behavioral context beyond annotations: fans out to multiple sources (SEC EDGAR, GDELT, GNews, USPTO), explains fallback logic (GDELT preferred, GNews on rate limit/5xx), and notes the PatentsView API sunset causing soft-fail. Also describes the output structure (changes[] grouped by source + total_changes + citation URIs), 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 dense but well-structured: starts with example queries, then explains the data sources, date format, return shape, and alternative tool. Each sentence carries relevant information for a multi-source API with fallback behaviors, though it is longer than strictly necessary.

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 (multiple data sources, fallback logic, date parsing, and no output schema), the description covers all critical aspects: what it returns, how sources behave, the 'since' format, and when to use a sibling tool. The lack of an output schema makes the detailed return description essential, and it is provided.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the meaning of 'since' with examples and recommending '30d' or '1m' for typical monitoring. It also clarifies that 'value' accepts ticker or CIK, and that 'type' is limited to 'company', reinforcing schema details.

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

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

The description clearly identifies the tool as a change feed for a company, with specific verb phrases like 'What's new with X' and 'change feed for a company in the last N days/weeks/months'. It distinguishes itself from the sibling tool entity_profile by explicitly stating 'Use entity_profile instead when you want the static profile'.

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

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

Provides explicit usage triggers (e.g., 'latest on Y', 'updates on Acme') and a clear alternative (entity_profile for static profiles). It also documents nuanced behavior like GDELT→GNews fallback and USPTO soft-fail, helping the agent decide when to invoke this tool and what to expect.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context about persistence (authenticated vs 24-hour anonymous sessions) and scoping by identifier, which goes beyond the annotations and helps the agent understand data retention and isolation.

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 that front-load the purpose, then cover usage and related tools. Every sentence contributes meaning with no redundancy or unnecessary detail.

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

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

For a simple 2-parameter memory tool with annotations and no output schema, the description covers purpose, usage, persistence, and sibling integration. It doesn't explicitly describe overwrite behavior or return values, but those are minor gaps given the idempotent annotation and simple nature of the tool.

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

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

Schema coverage is 100% for both parameters, so the schema fully documents key/value semantics. The description's examples (resolved ticker, target address, user preference) add practical usage context, but the core parameter meaning is already well-covered by the schema, meriting the baseline score.

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

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

The description clearly states the tool's function as saving data for later reuse, using a specific verb and resource ('Save data'). It distinguishes itself from siblings by explicitly pairing with 'recall' and 'forget', making its role in the memory workflow unambiguous.

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

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

It provides explicit usage context ('Use when you discover something worth carrying forward...') and names alternatives ('Pair with recall to retrieve later, forget to delete'). This gives the agent clear when-to-use guidance and differentiates from related tools.

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

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

Annotations already mark this read-only and idempotent, and the description goes well beyond them: it discloses graceful degradation when GLEIF/OpenFIGI are unavailable, returns figi_candidates rather than asserting on ambiguous matches, labels identifiers with their source, and explicitly reports unresolved identifiers under 'unresolved' instead of omitting them. These are meaningful behavioral commitments 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 front-loaded with examples and a clear use-first directive, but it is a wall of dense, heavily parenthesized prose. Much of the detail is valuable, but it would benefit from section breaks or bullet-style formatting; the run-on sentences make parsing harder than necessary.

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

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

Given no output schema, the description carries the full burden of explaining return behavior, and it does: identifiers returned per type, source labelling, unresolved fields, figi_candidates, graceful degradation, and accepted input forms. For a tool with two entity types and multiple external services, the coverage is thorough 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 schema already covers both parameters well (100% coverage), but the description adds real semantic value beyond it: accepted input forms for company (ticker, CIK, ISIN, or name), drug examples, and the critical 'ENTITY NAME ONLY' caveat for bonds with a concrete example. That goes beyond simply repeating schema text.

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

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

The description opens with concrete user-phrase examples, then states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names specific outputs (CIK, ticker, LEI, FIGI, RxCUI) and the supported entity types, so an agent can clearly tell what this tool does and why it exists.

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 'Use FIRST whenever you have a name but need an ID,' which gives clear timing/usage guidance. It also explains that each call replaces 2-3 manual lookups, implying this is the preferred entry point for name-to-ID resolution. However, it does not list sibling alternatives or state when not to use this tool in favor of e.g. entity_profile or compare_entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context by revealing that it probes each entity with ai_visibility_check and describing the return format (ranked list with score, confidence, signal density), which goes beyond the structured fields.

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

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

The description is four sentences, each earning its place: purpose, mechanism, use case, and return format. It is front-loaded with the main action, contains no redundant phrases, and is highly efficient for the information conveyed.

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

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

Despite having no output schema, the description explicitly details the return structure (ranked list with score, confidence, signal density), explains how the tool works (probing with ai_visibility_check), and provides a concrete use case. This is sufficient context for a 4-parameter tool with strong annotations.

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

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

Schema description coverage is 100%, with all four parameters fully described. The description mentions 'your brand + N competitors' which aligns with the schema's 'first entry treated as the subject' instruction, but since the schema already contains this detail, the description adds no new semantic information beyond the baseline.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb ('compare') and resource ('AI visibility'), and distinguishes itself from siblings by mentioning it probes each entity with ai_visibility_check and ranks results, which differentiates it from single-entity or generic comparison 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 a clear use case: 'Useful for competitive AI-marketing audits' and includes a concrete example ('does Claude know about us as well as our competitors?'). It implicitly contrasts with the sibling ai_visibility_check by focusing on side-by-side comparison, but it does not explicitly state when not to use it or name alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses partial failure behavior, the potential 5-30s delay on first bundlephobia measurement, and the sources_failed field. This adds valuable operational context without contradicting the annotations.

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

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

The description is long but every sentence earns its place, covering purpose, usage, outputs, ecosystem scope, and failure modes. It is front-loaded with the core value proposition and structured logically.

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

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

With no output schema, the description thoroughly enumerates the return fields, advisory details, alternative versions, and failure handling. It gives a complete picture for a composite tool with multiple data sources and potential delays.

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 fully describes both parameters with 100% coverage, so the baseline is 3. The description adds context about version meaning (e.g., 'new version', defaults to latest) but doesn't introduce new parameter semantics beyond what the schema 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 clearly states the tool's purpose: a composite check for 'should I add this npm package' combining deps.dev and bundlephobia data. It distinguishes from siblings by explicitly limiting to the NPM ecosystem in v1 and directing other package ecosystems to deps.dev:version.

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 triggers ('Use whenever an agent asks...') with concrete examples, and gives an exclusion rule (non-NPM ecosystems) with an alternative path. This fully answers when and when not to use the tool.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the embedding model (BGE-base-en), similarity metric (cosine), windowing strategy (500-char overlapping), character cap (200K), and truncation flagging behavior. It also tells the agent that results include character offsets and similarity scores, enabling verbatim verification. This is rich behavioral detail beyond structured metadata.

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

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

Each sentence serves a purpose: core action, examples, when-to-use, pairing with a sibling, and algorithm/limitations. The description is front-loaded with the primary function, and the technical details are positioned at the end. It is dense but not bloated, earning its length.

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

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

Given no output schema, the description explains what the agent can expect (passages with offsets and similarity scores) and covers use cases, pairings, and operational limits (cap, truncation). It is sufficiently complete for an agent to decide when to invoke and what outcomes to anticipate, especially with the sibling context providing an ecosystem.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that 'text' must be already-fetched content and that inputs over 200K chars are truncated and flagged—details not fully captured in the schema. It also frames 'limit' as 'top-N passages,' reinforcing the default/range semantics though the schema already states this. This nudges above baseline.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource+scope statement. It names concrete inputs (SEC 10-K body, article, tool result) and clearly differentiates from sibling tools by highlighting that it searches within a provided text rather than a broader corpus, and explicitly pairs with ask_pipeworx_grounded.

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

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

It explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It explains the benefit (saves context, returns only relevant passages) and describes the complementary workflow with ask_pipeworx_grounded, which serves as an alternative grounding strategy. This is clear, actionable 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 adds significant behavioral context beyond annotations: OAuth requirement, SMS verification and 10/day cap, feed always-on behavior. Annotations already declare idempotency and non-read-only nature, so the description complements them with practical constraints. Webhook behaviors are documented in the schema rather than the description, which is acceptable.

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 but efficient paragraph with a clear front-loaded opening. Every sentence provides unique information (types, delivery, constraints). While a bulleted list could improve scannability, it remains appropriately sized with no wasted words.

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

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

Given the tool's complexity (nested delivery, multiple types), the description covers the essential return value (subscription id), auth, and key delivery channels. It omits webhook from the main text but the schema explains it. The description is complete enough 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%, giving a baseline of 3. The description adds value with concrete examples like items:['5.02'] = officer change and clarifies delivery prerequisites such as verified phone for SMS. It doesn't cover patent_grant/clinical_trial types, but the schema already does.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this tool from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and returning the new subscription 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?

Provides clear context for when to use the tool, including the OAuth account requirement, always-on feed, and optional email/SMS delivery. It implies the flow (create subscription then pull alerts via recent_alerts) but does not explicitly state when not to use it or name alternative tools for one-off data needs.

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 the safety profile. The description adds behavioral context about what the tool returns (category-bucketed examples with tool+argument shape) and that it draws from the live catalog, going beyond 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 a single dense paragraph but every sentence provides value: purpose, return shape, parameter behavior, and usage timing. It could be improved with bullet points or shorter sentences, but it is not wasteful.

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

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

With no output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool+argument shape) and covers both invocation modes. Given the tool's simple API (one optional parameter), the description is complete with no critical gaps.

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

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

Schema coverage is 100% for the single optional `topic` parameter, but the description adds meaningful usage nuance: calling with no arguments gives the full spread, and passing a topic (with examples like 'finance', 'pharma', 'betting') focuses results. This enriches the schema's terse list of categories.

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

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

The description clearly identifies the tool as an onboarding entry point that suggests example questions with exact tool and argument shapes. It distinguishes from siblings by emphasizing its role as a meta-orientation tool ('Use this FIRST'), and the title 'What Can I Ask Pipeworx?' reinforces the specific 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?

Explicitly states when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...'. It also explains the alternative of passing a `topic` for focus versus omitting it for a full spread, giving clear actionable 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 key behaviors beyond annotations: ownership enforcement (only own subscriptions) and soft-delete semantics (deactivated not deleted). These add significant value over the schema and annotations, which only indicate mutation and idempotency.

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

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

Two sentences, front-loaded with the core action. Every sentence earns its place, covering action, ownership, and the deactivation side effect without 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?

For a simple tool with one parameter and no output schema, the description covers action, ownership, and side-effect. It doesn't mention the return value, but that's not required without an output schema. Minor gap: no mention of error behavior, but the overall context is sufficient.

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

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

Schema coverage is 100%, and the schema already describes the id as 'Subscription id (uuid) returned by subscribe.' The description simply says 'by id' without adding new parameter meaning, 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 states a specific verb+resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like subscribe (opposite), list_subscriptions (listing), and recent_alerts (viewing history).

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

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

It provides clear context: use this to cancel a subscription by ID. It also notes ownership restrictions and that deactivation preserves history for recent_alerts, giving useful context for when to use it. However, it doesn't explicitly exclude alternatives or mention when not to use it.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by explaining important behavioral nuances: the meaning of 'could_not_verify' (check did not happen, not evidence), 'unsupported', the two distinct processing pipelines, and the citation format. This is critical context for correct interpretation of results.

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

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

The description is dense but well-organized, starting with trigger phrases, then usage, then output, then critical caveats. It is slightly long but each section adds value. The front-loaded structure aids quick comprehension.

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 two routes, six possible verdicts, and important edge cases, the description fully covers return values, the meaning of ambiguous statuses, and the distinction between 'could_not_verify' and 'unsupported'. This is complete enough for an agent to invoke and interpret correctly.

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

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

The input schema already documents both parameters (claim and tolerance_pct) with examples and clear descriptions (100% coverage). The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly states a specific verb+resource: natural-language claim verification against authoritative sources. It provides numerous trigger phrases and distinguishes the tool's scope by delineating two execution paths (financial vs. other claims), making its purpose unambiguous and separate from generic query 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and describes routing logic for different claim types. However, it does not explicitly mention when NOT to use the tool or name alternative sibling tools, though the trigger phrases imply the use case clearly.

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