Predictit

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

Beyond annotations (readOnly, idempotent), the description adds that the tool probes multiple LLMs, returns per-model score/confidence/signals/raw_response, and mentions the free default model vs. paid Anthropic. No contradictions with annotations.

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

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

The description is two sentences plus a use-case list, all front-loaded with the core action and results. No redundant or extraneous information; every sentence adds value.

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

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

With 4 parameters, no output schema, moderate complexity, the description covers what the tool does, how to use it, and what it returns (per-model fields and combined view). Minor omission: doesn't detail 'signals' or 'raw_response' structure, but overall sufficient for an agent to invoke correctly.

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

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

Schema descriptions exist for all 4 parameters, so baseline is 3. The description adds context like default model and purpose of _apiKey, but this is minimal extra value given the schema already explains each parameter adequately.

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 'probe' and the resource 'LLMs' for knowledge about an entity, scoring visibility per model. It distinguishes from siblings by specifying this is an AI visibility audit tool, contrasting with e.g., 'scan_competitor_ai_presence' which may have a different focus.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional API key. However, it does not explicitly exclude scenarios or compare directly to alternate tools, limiting guidance on when not to use.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds genuine behavioral context beyond them: it reveals autonomous routing over thousands of sub-tools, auto-filling of tool arguments, and the stable pipeworx:// citation-URI return mechanism. None of these behaviors appear in the annotations. No contradiction exists with the read-only hints.

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

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

Long but deliberately ordered: priority directive first ('PREFER OVER WEB SEARCH'), then mechanism, then trigger phrases, then examples, then a closing 'START HERE' directive. Every section earns its place for a high-traffic router tool. The minor flaws are redundancy ('even if web search could also answer it' appears twice) and an exhaustive domain list that gets slightly bulky.

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 compensates by specifying the return shape: a structured answer with stable pipeworx:// citation URIs. For a high-complexity meta-router it covers selection, invocation, and expected result, and gives strong examples. It falls short of fully complete because the exact output format is left vague and there is no explicit guidance on sibling variants (ask_pipeworx_beta, ask_pipeworx_grounded) or deeper research alternatives.

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%: all six parameters are documented as one natural-language 'question' with five explicit aliases (q, text, input, query, prompt). The description adds helpful question-typing examples but no parameter-level semantics beyond the schema, such as format constraints, length limits, or answer style preferences. Baseline 3 applies because the schema carries the full 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?

States a specific mechanism and deliverable: routes the question to one of 5,743 tools across 1500 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. The verb+resource is precise and unmistakable, and it clearly positions itself against web search as the canonical factual-Q&A router. It does not explicitly differentiate near-clone siblings (ask_pipeworx_beta, ask_pipeworx_grounded), but the core purpose is 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?

Provides explicit when-to-use conditions: 'PREFER OVER WEB SEARCH' for a long enumerated list of domains (SEC filings, FDA data, FRED/BLS statistics, patents, weather, clinical trials, news), plus trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and concrete example questions. The alternative (web search) is named and explicitly deprioritized with 'even if web search could also answer it.' However, it never states when NOT to use the tool or routes to sibling alternatives such as deep_research or ask_pipeworx_grounded.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningfully beyond those: it may change live when a routing candidate is under test, currently no candidate is active, and it is a full working router with no fallback to nothing. This accurately discloses volatile experimental behavior.

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

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

Four sentences, each earning its place: identity, current beta status, usage instruction, and fallback reassurance. It is slightly repetitive about matching ask_pipeworx, but the size and front-loading are appropriate.

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 universal-router tool with no output schema, the description is sufficient by anchoring response shape to ask_pipeworx and giving the current state and usage instruction. It doesn't describe the response format in its own words, but referring to the stable sibling's shape is a complete-enough contract.

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

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

Schema coverage is 100%, so the schema already defines all aliases and the main question field. The description only says 'same arguments' and adds no behavioral or format detail per parameter, which matches the baseline for a fully covered 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 anchors to ask_pipeworx and identifies the tool as the experimental beta variant of a universal router, including the same 5,743 tools, arguments, and response shape. It clearly states what it is and distinguishes it from the stable ask_pipeworx sibling.

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 an explicit use condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies current state (no active candidate, matches ask_pipeworx exactly). It doesn't explicitly say when not to use it, though 'beta' and 'experimental edge' imply avoiding it for stability-sensitive use.

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

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

Beyond the annotations, the description discloses important behavioral traits: it only uses tool result content, returns a refusal object with specific refusal_reason values when it can't answer, and costs one extra LLM call. This gives the agent a clear model of failure modes and cost 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 front-loaded with the core purpose, then provides the return shape, refusal reasons, use cases, and cost trade-off in a compact sequence. Every sentence contributes actionable information, and the structure makes the key distinctions easy to scan.

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

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

Despite having no output schema, the description fully documents the success and refusal response structures, including refusal_reason values. It covers use cases, exclusions, cost, and behavioral guarantees, so an agent has everything needed to decide when to call it 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 coverage is 100% and the schema already documents question and all six aliases clearly, so the description doesn't need to add parameter syntax. The description adds context about how the question is used but no parameter-level detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies a specific, distinct mode: a hallucination-resistant answer mode that extracts answers only from the tool result and refuses when the data doesn't directly answer. It differentiates itself from ask_pipeworx by name and by emphasizing evidence and refusal behavior, so an agent can distinguish it immediately.

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

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

The description gives explicit when-to-use guidance: high-stakes reads where answers will be quoted, cited, or acted on, such as financial verdicts, legal claims, medical lookups, and public statements. It also explicitly names the alternative (ask_pipeworx) and says to prefer it for casual lookups, plus notes the extra LLM call cost.

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 (readOnlyHint=true, etc.), the description reveals extensive behavioral details: market resolution, classification, parallel fan-out, evidence packet, resolver contract with confidence levels, parent_event extraction, news fallback mechanisms, safety short-circuits for low confidence and closed markets, wide-spread warnings, and cancellation rules. 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 lengthy but well-structured, front-loading the core purpose then drilling into details. Every sentence adds necessary context given the tool's complexity. Some minor redundancy exists (e.g., repeated mentions of status codes) but overall earns its place.

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

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

Given the tool's complexity (multiple data sources, resolver, safety checks) and lack of output schema, the description is remarkably complete. It covers edge cases (low-confidence, closed markets, wide spreads, cancellation rules, fallback handling) and explains response shapes in detail. No gaps identified.

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

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

Schema coverage is 100%, but the description adds significant value: clarifies that 'market' can be slug, URL, or question text; explains default behavior for 'depth' and rationale for 'include_raw' (keep responses under ~20KB vs. full payloads). This goes well 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies multiple input formats (slug, URL, question text) and outlines the output (evidence packet + comparison). This distinguishes it from siblings like search_markets or get_market.

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

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

Explicit usage examples are given: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' It also provides classifier categories and fan-out examples. However, it does not explicitly state when not to use it or mention alternative tools like ask_pipeworx for general queries.

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

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

The description adds substantial behavioral context beyond annotations: it specifies the data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and notes it makes a single parallel call. 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 concise and front-loaded with examples and a key directive (ALWAYS PREFER). It covers necessary details without excessive wordiness, though it could be slightly more streamlined.

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 adequately explains return data: 'paired data + pipeworx:// citation URIs per entity' and sorting. It does not detail exact output format but provides sufficient context for an agent to use the tool effectively.

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

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

The description significantly enriches parameter semantics: it explains what data each 'type' returns (financial metrics for company, adverse events for drug) and notes that 'values' accepts tickers/CIKs or drug names. This goes well 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 clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes itself from siblings by explicitly preferring it over sequential single-pack lookups and mentioning it replaces 8-15 lookups.

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

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

The description provides strong usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and includes example queries. However, it does not explicitly mention when not to use this tool (e.g., for a single entity use entity_profile).

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/openWorld/idempotent, and the description adds far richer behavior beyond them: the account/paid-plan gate, 15-60s/up-to-90s latency, parallel decomposition across 5,743 tools, the full findings-packet shape (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the never-invented gaps[] guarantee, contradictions[] scanning, the hop field, the citation_uri fetchability guarantee, and semantic excerpting. 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?

Information-dense and well front-loaded, with the critical auth gate first and the core purpose immediately after. Slightly redundant — the ask_pipeworx alternative and the paid-plan constraint each recur — but for a complex tool with no output schema, nearly 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?

With no output schema, the description carries the full burden of explaining return values, and it does so exhaustively: findings packet fields, gaps[], contradictions[], hop, citation_uri, plus auth prerequisites, latency windows, sibling routing, and edge behaviors like semantic excerpting. An agent has everything required to invoke it correctly and interpret results.

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

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

Schema coverage is 100% and the depth enum is already richly described in the schema (hop counts, gap recovery, contradictions scan). The description adds value above that baseline: per-depth latency expectations, the paid-plan restriction on thorough, and worked example questions illustrating what 'question' should contain. Genuinely additive, though not a dramatic delta over the already-strong 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?

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources... in ONE call.' Actively differentiates from siblings by declaring 'this is NOT open-web search' and explicitly naming ask_pipeworx as the sibling for different jobs, so an agent can disambiguate without opening other schemas.

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

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

Gives explicit when-to-use, when-not-to-use, and named alternatives: 'If you are not signed in, use ask_pipeworx instead,' 'For a single lookup use ask_pipeworx instead,' and for breaking news 'prefer ask_pipeworx... deep_research returns mostly empty gaps[] when the topic isn't in the structured catalog.' Also provides positive worked examples ('compare X and Y's regulatory + financial exposure'). Nothing is left to inference.

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

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

Annotations already indicate read-only and idempotent. The description adds that it returns top-N tools with full schemas ready to call, providing useful context beyond the annotations without contradiction.

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

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

The description is concise, front-loaded with the core purpose, includes examples, and ends with usage advice. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description explains what is returned (names, descriptions, schemas, examples). It is complete for a discovery tool, though missing mention of handling zero results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds that 'query' is natural language, but the schema already describes it. No additional parameter guidance is needed.

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

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

The description clearly states it finds tools by describing the data or task, and lists specific domains. It distinguishes itself from sibling tools by being a discovery tool, not a specific domain tool.

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

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

Explicitly says 'Use 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'. It implies when not to use (if you know the tool) but does not explicitly state 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?

Even with annotations marking it read-only, open-world, and idempotent, the description adds substantial behavioral detail: it fans out across multiple sources, soft-fails on the USPTO sunset, treats empty FDA results as expected rather than errors, reports sources_used/sources_failed, falls back from GDELT to GNews, and returns resolved:false for private companies. This goes far beyond the annotations and helps the agent interpret results correctly.

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

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

The description is long, but for a tool of this complexity nearly every clause carries useful information: input forms, source list, output fields, failure semantics, and edge cases. It is front-loaded with trigger examples and the core purpose before diving into details, though the single dense paragraph could be structured slightly more cleanly.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it lists the major output sections, explains what each one contains, clarifies when an empty section is expected, describes fallback behavior, and covers the private-company resolved:false case. An agent has enough context to call the tool and interpret its response 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% for both parameters, so the schema already documents that `type` accepts company/ticker and `value` accepts ticker, CIK, or name. The description reinforces this with examples and notes that names resolve via SEC EDGAR, but it does not add meaningful new parameter semantics beyond what the schema already provides.

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

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

The description identifies a specific verb and resource: it builds a full cross-source profile of a US public company in one parallel call. It also includes concrete trigger phrases and enumerates the exact sources and output fields, making it clearly distinguishable from single-purpose lookup tools.

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

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

The description gives clear when-to-use guidance: prefer this over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It does not explicitly name sibling alternatives like resolve_entity or compare_entities, but it states the intended context strongly enough for an agent to select it appropriately.

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 destructiveHint=true and idempotentHint=true, covering key behavioral traits. The description adds context (e.g., 'clear sensitive data') but doesn't significantly enhance beyond annotations.

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

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

Two sentences with no wasted words. First sentence front-loads the purpose; second sentence provides usage guidance. Ideal structure for quick agent parsing.

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 1-parameter tool with no output schema, the description covers purpose, usage scenarios, and related tools. No gaps given the tool's simplicity and annotation richness.

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 single parameter 'key' is described. The description only repeats 'by key' without adding extra 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 uses a specific verb ("Delete") and resource ("previously stored memory"), clearly stating the tool's action. It also distinguishes itself from siblings by pairing with remember and recall.

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

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

Provides explicit when-to-use scenarios: stale context, task completion, clearing sensitive data. Mentions related tools (remember, recall) but lacks explicit when-not or alternative 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description details the tool's actions: fetching the page, extracting title/description/key links, and emitting llms.txt format. This adds context not covered by annotations. No contradictions.

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

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

The description is two paragraphs, front-loading the core functionality and output, followed by use cases. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (2 params, no output schema, safe annotations), the description adequately covers purpose, process, and output format. It could mention prerequisites like URL accessibility, but overall it is 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?

Both parameters (url, max_links) are described in the input schema with 100% coverage. The description does not add new semantic information beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, explaining the process (fetch, extract, emit) and the output format. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on generation rather than scanning.

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 lists specific use cases (getting a client's site indexed, drafting for own project, auditing competitors), providing clear guidance on when to use. However, it does not explicitly state when not to use or mention alternatives, though 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?

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that contract prices are implied probabilities (0–100%) and that the tool is keyless, which enriches behavioral understanding beyond annotations.

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

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

Two sentences, front-loaded with the primary action. No extraneous information. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers all needed: what it does, how to use it, a data detail, and how to find inputs. Annotations further support safety and idempotency.

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 type and description with 100% coverage. The description adds concrete examples (e.g., 7589 for 2026 Republican House seats) and clarifies the parameter's meaning, adding value beyond the schema.

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

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

Clearly states verb ('Get'), resource ('one PredictIt market by id'), and scope ('with ALL of its contracts'). Distinguishes from siblings by referencing list_markets and search_markets for finding ids.

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

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

Explicitly tells when to use this tool (to get a market by id) and when not (to find ids, use list_markets or search_markets). Provides an example id for 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: keyless access, contract prices as implied probabilities, return of compact markets with up to 8 contracts. No contradictions with annotations.

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

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

Two sentences, front-loaded with key details (what it lists, domain, size, keyless, return structure). Every sentence provides essential information with no wasted words. Ideal conciseness for agent parsing.

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 return content (compact markets, up to 8 contracts, implied probabilities). It also mentions market count and authentication requirement. The description is nearly complete but could benefit from noting that results are not paginated (limit handles 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?

Schema coverage is 100% with clear descriptions for both params (limit, open_only). The description adds overall context about market count and contract count but does not enhance parameter-specific meaning. Baseline 3 is appropriate as 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 it lists active PredictIt prediction markets with specific details (real-money, US-politics-focused, ~250 markets, contract prices as probabilities, keyless, returns compact markets with up to 8 contracts). It distinguishes the tool's purpose from siblings like get_market or search_markets, though not explicitly. The verb 'list' and resource 'markets' are specific and well-defined.

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 for viewing active markets and mentions it is keyless, but does not explicitly state when to use vs. alternatives (e.g., search_markets for filtering). It provides context (always returns active markets) but lacks exclusions or 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 provide readOnlyHint, idempotentHint, etc. Description adds value by listing return fields and usage context, with no contradiction.

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

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

Two concise sentences front-loading the primary purpose and usage, with no unnecessary content.

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

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

Given the tool simplicity (one optional param, no output schema), description fully covers purpose, output, and usage context.

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

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

Schema coverage is 100%, so description doesn't need to elaborate; it repeats parameter name but adds no new semantics beyond schema.

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

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

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

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

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

Explicitly advises using this to review monitoring before adding more or to find an id to cancel, providing context for when to use it.

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

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

Annotations provide no readOnly/idempotent/destructive hints (all false), so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and the follow-up claim_token mechanism ('Filing without an account returns a `claim_token`; pass it back later...'). These behaviors go beyond what annotations reveal.

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

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

The description is thorough, spanning multiple sentences, but it is densely informational and front-loaded with the core purpose. Each sentence earns its place (purpose, when-to-use, exclusions, claim_token flow, rate limit), though it could be slightly tightened. It remains well-structured and readable.

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 feedback tool with no output schema, the description fully explains the tool's purpose, usage rules, exclusions, follow-up mechanism, and limitations. The claim_token behavior and rate limit are covered, making the tool self-explanatory. It leaves no significant 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 description coverage is 100%, so the schema already defines all four parameters. The description adds extra semantic guidance, such as instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts, and clarifies the claim_token parameter usage. This extra context justifies a score above the baseline of 3.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly uses a specific verb ('tell') and resource ('Pipeworx team'). It distinguishes the tool from sibling research/ask tools by focusing on feedback submission, with no ambiguity about its function.

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 when a tool returns wrong/stale data... feature/data_gap... praise') and when not to ('ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead'). It also provides guidance on what to include ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), making the usage context exceptionally 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?

Description adds value beyond annotations: explains the data source 'CF analytics-engine', states no PII, and mentions caching behavior (5min-1h). Annotations already declare readOnlyHint and idempotentHint, but the description provides concrete operational details.

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

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

Concise 5-sentence description. Front-loaded with core functionality, then use cases, then technical details. Every sentence serves a purpose with no redundancy or fluff.

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

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

Fully covers the tool's purpose, usage context, parameter semantics, and behavioral details (caching, privacy). Given the simple 1-parameter schema and rich annotations, the description is complete and leaves no significant 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 has 100% coverage with one parameter 'window' including enums and a description. Description adds extra context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This clarifies the trade-off beyond the schema.

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

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

Description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window'. It specifies exactly what data is retrieved and the resource (Pipeworx trending). Distinguishes from siblings like 'discover_tools' by focusing on current call activity.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, assessing use case alignment). However, no direct guidance on when to avoid this tool or how it compares to alternative sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

Annotations already indicate read-only, but the description adds critical behavioral context: fill-check logic explains when arbitrage signals are not realizable, the skipped_low_similarity field, and partition filter for placeholder slugs. 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 somewhat lengthy but well-structured with clear sections and front-loaded purpose. It could be more concise, but it avoids unnecessary repetition and is logically organized.

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 thoroughly explains the response structure (opportunities[], partition_check fields, fill check) and covers edge cases like filter thresholds and similarity checks. It is complete for a complex tool.

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

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

Schema coverage is 100%, providing basic descriptions. The description enriches them by explaining the semantic meaning (event slug vs. seed question) and providing examples, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and differentiates from sibling tools by focusing on arbitrage detection.

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

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

Explicit guidance is given: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It recommends event mode for specific markets and warns about cross-event similarity. It also directs to a sibling tool for custom sizing.

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

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

The description goes far beyond the annotations (readOnlyHint=true, etc.) by detailing caching behavior ('Cached 1h at the KV level'), edge computation specifics (net of slippage, Kelly caps, segment logic), and diagnostic output. It explains how segmentation works and what fields each opportunity carries, providing full transparency for the agent.

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 comprehensive and well-structured, starting with the core purpose and then segmenting into details. While it is long, almost every sentence provides critical information for a tool with 9 parameters and complex logic. It could be slightly more streamlined but remains efficient given the complexity.

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

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

The description is exhaustive: it explains all three opportunity segments, all parameters including their defaults and use cases, the response structure (top-level fields, diagnostics), and caching. Even without an output schema, the agent gets a complete picture of what to expect and how to interpret results.

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

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

With 100% schema coverage, the baseline is 3, but the description adds significant meaning to each parameter. For example, it explains min_kelly as 'half-Kelly fraction' and how it filters opportunities, and describes max_spread_pp and min_liquidity as 'tradeable-edge filters' with concrete reasoning. This adds value beyond the schema's terse descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs ('scan', 'return') and a defined resource ('Polymarket markets'). The tool is explicitly built for the query 'what should I bet on today', distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker which likely serve different functions.

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 guidance on when to use the tool (for discovering opportunity segments like MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and how to tune it with tradeable-edge knobs (min_liquidity, max_spread_pp). It does not explicitly exclude alternatives or mention when not to use it, but given the complexity, it offers sufficient context for agents to choose appropriately.

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 provides extensive behavioral context beyond annotations: it explains that the tool reads snapshots (read-only, idempotent), details the output structure (tracked, expired, snapshot_dates), and notes limitations (60-day TTL, decay from daily closes, cache-miss behavior). 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 information-dense and well-structured, starting with purpose, then output details, then limitations. It is somewhat lengthy but every sentence adds value for a 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?

Given the lack of an output schema, the description thoroughly explains all return fields (tracked, expired, snapshot_dates) and their semantics, as well as limitations and edge cases. It is fully complete for selecting and invoking 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%, so the baseline is 3. The description adds context like 'snapshot family' and 'lookback' but does not significantly enhance meaning beyond the schema; it mostly restates or slightly rephrases the schema descriptions.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge existence and decay, and distinguishes itself from the sibling 'polymarket_edges' by focusing on time-series analysis.

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

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

The description explains when to use the tool: to determine how long an edge has existed and whether it is shrinking. It contrasts fresh vs. old edges, giving context on trade significance. However, it does not explicitly state when not to use it or mention alternatives beyond the implicit contrast.

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 annotations. It explains that the tool walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and a verdict. For baskets, it details return fields and warns about forced_directional_risk. It also explains the risk of partial fills converting arb into unhedged positions, which is critical behavioral context. 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 lengthy, but well-structured with clear sections for single-market and basket modes, and uses bold headings. Every sentence provides necessary detail. Could be slightly more concise, but the high information density justifies the length.

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

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

Given the complexity (two modes, multiple return fields, risk considerations) and the lack of an output schema, the description is extremely complete. It lists all return fields for both modes, explains the verdict, default sizes and clamps, auto side detection, and warnings about directional risk. No gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the interpretation of size_usd in both modes (spend vs. target proceeds for single-market, settlement notional per leg for basket), the auto default for side in basket mode, and the requirement that one of market or event must be provided. This adds context beyond the schema definitions.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly says to use this before polymarket_arbitrage or polymarket_edges trades, differentiating it from siblings.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why: theoretical overround is not capturable on thin books, and partial fills create directional risk. It provides clear when-to-use guidance and warns against not using it for larger trades.

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. The description adds extensive behavioral context beyond that: the compatibility_warning/compatibility_codes system, temporal null semantics ('null means it could not be computed, not that the two sides align'), the fee disclosure that spreads are gross, and the skipped_cross_type/skipped_cross_subtype counters. This is rich, non-obvious behavior fully disclosed.

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

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

Every sentence carries substantive information, but the description is a dense, continuous prose block mixing mode instructions, response fields, safety codes, temporal semantics, fee caveats, and skipped-count details. It would be more usable with headings, bullets, or a clearer separation of 'how to call' vs 'what to interpret.' It is thorough but not concise in structure.

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 is unusually complete: it documents response fields (leg prices, top_spreads_pp), safety fields and their codes, per-entry flags, skipped/unclassified handling, temporal alignment semantics, fee limitations, and behavior in both modes. An agent has enough to invoke the tool and interpret results correctly without additional external knowledge.

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 each parameter is already documented; the baseline is 3. The description adds real value by explaining that topic mode auto-fetches matching events, that explicit ticker/slug overrides operate independently, and that BOTH modes run the identical token-overlap matcher. This goes beyond the schema's field-level descriptions and clarifies how the three parameters interact.

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 statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the resource (Kalshi/Polymarket), the output (spread), and the two operating modes. However, it does not explicitly contrast itself with sibling tools like polymarket_arbitrage or polymarket_edges, so an agent must infer the differentiating factor.

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

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

The description gives substantial usage context, including the two modes, how to invoke them, and a clear caution: 'pre-mapped ≠ tradeable' and 'Real cross-venue spreads are rarer than the macro-shortcut list suggests.' It also explains when the spread is a real signal ('when the bet shapes are equivalent') versus when it is not. It stops short of naming alternative tools to use instead, so the 'when-not-to-use' guidance is only implicit.

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 safe read-only idempotent behavior. Description adds scoping detail (by identifier) and the alternative behavior (omit key to list all), providing context beyond annotations without contradiction.

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

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

Three sentences efficiently cover purpose, use case, and scoping. Front-loaded with the primary action. The pairing note is helpful but slightly redundant with sibling awareness.

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 retrieval tool with one optional parameter and no output schema, the description covers behavior, scope, and usage. Lacks explicit mention of error handling if key not found, but overall adequate.

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

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

Schema covers 100% of parameters with description matching. The free-text description reiterates the listing behavior and provides examples (ticker, address), adding marginal value but not surpassing baseline given full 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?

Clearly states it retrieves a value by key or lists all keys when omitted. Distinguishes from siblings by explicitly mentioning partners `remember` and `forget`, and provides concrete examples of usage contexts (ticker, address, notes).

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

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

Gives specific use cases (look up stored context) and explains how to list keys by omitting the argument. Does not explicitly state when not to use, but the context is clear and alternatives among siblings are not required due to specificity.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds that mark_read:true flags returned events as read, affecting next call, and mentions the feed's persistence. This extra context justifies a 4.

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

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

The description is concise, front-loaded with purpose, and every sentence adds value. It covers purpose, output structure, filtering, side effects, and alternatives without 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?

Without an output schema, the description explains the return fields (source, citation_uri, raw event payload). It covers filtering, mark_read behavior, and polling usage. All key aspects for a list tool are addressed, making it complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by giving an example value for type ('sec_8k'), explaining that since expects an ISO timestamp, and detailing the effect of mark_read. This goes beyond 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 clearly states the tool pulls fired events from the subscription feed, with specific verb 'Pull' and resource 'fired events'. It distinguishes from siblings by focusing on subscription alerts, unlike other tools like 'recent_changes' or 'list_subscriptions'.

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

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

The description provides explicit usage context, including filtering by type and since, setting mark_read, and notes polling works. It also offers an alternative GET URL. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant context: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, date format handling, and structured return. 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 a single dense paragraph but front-loaded with example queries. It efficiently packs information without redundancy. A bit more structure (e.g., bullet points) could improve readability, but it's still concise given the content.

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

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

Despite no output schema, the description explains return structure (changes[] grouped by source, total_changes count, citation URIs). It covers all essential aspects: sources, date formats, error handling, and distinguishes from sibling. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds extra meaning: explains relative date shorthand with examples, specifies value can be ticker or CIK, and recommends '30d' or '1m' for typical monitoring.

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

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

The description clearly states it provides a change feed for a company in a date range, fanning out to multiple sources. It uses specific verbs and examples, and distinguishes from the sibling tool 'entity_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?

The description explicitly says to use this tool for change feed queries and to use 'entity_profile' for static profiles regardless of window. It provides clear when-to-use and when-not-to-use guidance.

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

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

Discloses persistence behavior (authenticated vs anonymous, 24-hour retention) and scope by identifier, adding significant value beyond annotations. No contradiction.

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

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

Every sentence adds value, but could be slightly more concise. Front-loaded with main action and context.

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

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

Fully covers purpose, parameters, usage, and storage behavior with no gaps given the tool's simplicity.

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 descriptions already cover key and value; description adds usage context (example key patterns) and clarifies the key-value storage model.

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

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

The description clearly states the tool saves data for reuse across sessions and distinguishes from siblings like recall and forget via explicit pairing language.

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

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

Provides explicit when-to-use guidance ('discover something worth carrying forward') and mentions companions (recall, forget). Does not include when-not-to-use but is sufficient.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, returning `figi_candidates` for ambiguous matches, and labeling every identifier with its source. This goes well beyond what the annotations imply and does not contradict 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 front-loaded with the core purpose and the 'Use FIRST' directive, and nearly every clause carries useful information. However, it is one dense run-on paragraph with heavy nesting and parentheticals, which hurts scannability despite being content-complete.

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 still explains what will be returned for each entity type: CIK, ticker, LEI, FIGI, RxCUI, ingredient, unresolved identifiers, and `figi_candidates`. It also covers failure modes and fallback behavior, making the tool usable without external schema information.

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 schema description coverage is 100%, the description adds meaning beyond the schema: accepted identifier forms (ticker, CIK, ISIN, name), exact-name matching behavior, bond issuer nuances, and the ISIN-to-LEI mapping. This materially helps an agent construct valid parameter values and interpret results.

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

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

The description states a specific verb and resource: resolving a user-spoken NAME to canonical/official identifiers for other tools, with concrete example phrasings like 'find the CIK for…' and 'what's the RxCUI for…'. It clearly distinguishes this from sibling entity tools like entity_profile or compare_entities, which operate on already-resolved entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear trigger condition. It also details accepted input forms per type and warns about exact issuer names versus full noun phrases. It lacks explicit when-not-to-use guidance or named alternatives, so it stops short of a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds specific behavioral details: probes each entity with ai_visibility_check, ranks, returns score/confidence/signal density.

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 action, no redundant information. Efficient and clear.

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

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

Covers purpose, usage, return type (ranked list with metrics), and underlying tool call. Lacks error handling or limitations, but sufficient given annotations and schema richness.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra beyond schema; mentions 'context' for disambiguation but doesn't elaborate on parameter specifics or examples.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side' and distinguishes from sibling 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison).

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

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

Explicitly says 'Useful for competitive AI-marketing audits' and implies when to use via the example question. Does not explicitly state when not to use, but context hints at single-entity 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?

Description adds behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed will list timeouts. Annotations already indicate safe, idempotent read.

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

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

Description is detailed but not overly long. It front-loads purpose, then usage, return format, and limitations. Every sentence adds value, though it could be slightly more concise.

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

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

Despite no output schema, description fully explains return structure: summary block fields, per-advisory details, links, alternative versions. Covers edge cases like partial failures and timeouts.

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 both parameters are described. Description adds no new parameter semantics beyond what schema provides (e.g., 'scoped packages accepted' also in schema). Baseline 3 is appropriate.

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

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

The description clearly states it's a composite check for adding npm packages, performing license, advisory, size, and dependency checks in one call. It distinguishes from sibling tools which are for AI visibility, competitions, etc.

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

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

Explicitly says when to use: when agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies that for non-NPM ecosystems, use deps.dev:version directly.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds: client-side execution (no external API), scope of all markets, interpretation of prices as probabilities, and keyless access. No contradictions with annotations.

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

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

The description is two sentences, each adding essential information without redundancy. It front-loads the main purpose and adds contextual details efficiently.

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 that results include contract prices as implied probabilities. It covers scope, limitations (no PredictIt endpoint), and authentication. Slightly more detail on output format could push to 5, but current 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% with detailed descriptions for both parameters. The description adds no new information beyond the schema (case-insensitive substring, defaults). Baseline 3 is appropriate as the schema bears the explanatory burden.

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

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

The description clearly states 'Search PredictIt markets by name', providing a specific verb and resource. It distinguishes from siblings like 'get_market' and 'list_markets' by noting it performs client-side search over all ~250 PredictIt markets and that PredictIt lacks a search endpoint.

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

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

The description gives clear context: it's client-side, covers ~250 markets, and is US-politics-focused. It also mentions 'Keyless' for auth. However, it does not explicitly state when to prefer this over sibling tools like get_market or list_markets, though the scope is implied.

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 (which already declare safe, idempotent, read-only), the description discloses internal mechanics (BGE-base-en embeddings, 500-char windows, cosine similarity), limits (200K chars with truncation flag), and output details (character offsets, similarity scores). 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?

Compact, front-loaded sentence defining the tool, followed by specific advice on usage, pairing, and technical details. No redundant sentences; every line 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 tool with no output schema, the description adequately explains return format (passages, offsets, scores), limits, and pairing strategy. All key aspects are covered.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete query examples and clarifying the text cap, slightly enhancing beyond the schema.

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

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

Description clearly states it performs semantic search inside a previously fetched record, using a natural-language query to return relevant passages. It distinguishes itself by specifying it works on already-fetched text, not on external searches, and 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?

Explicitly tells when to use: when the record is too large for the prompt. Provides a concrete alternative and pairing: use with ask_pipeworx_grounded for grounded queries instead of whole document.

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 behavioral context beyond annotations: requires OAuth, delivery constraints (email, SMS with verification and cap, webhook with HMAC signing and auto-disable), and always-on feed. However, it does not address idempotency (e.g., what happens on duplicate subscription creation) despite idempotentHint 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 well-structured with key info front-loaded (purpose, return value, requirement) followed by type details and delivery options. At ~150 words it is slightly long but every sentence adds value, making it appropriate for a 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?

Given no output schema, the description covers return value (subscription ID) and details for each delivery channel. It addresses edge cases like webhook auto-disable and phone verification. Missing error handling for invalid params, but overall complete for a subscription creation tool.

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

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

The description extensively enriches the schema with concrete examples, constraints, and behavior for each parameter: type-specific params (e.g., sec_8k items, polymarket_edge topic), delivery channels with phone verification, 10/day SMS cap, and webhook signing details. Schema coverage is 100% and description adds significant meaning.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying the create action and live-data event stream.

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 specific usage scenarios: when to subscribe to alerts, required Pipeworx OAuth account, supported types with examples, and delivery channels. It implicitly differentiates from alternatives but does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral context: returns example questions with tool shapes, supports optional topic filtering, and is non-destructive. 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 front-loaded with key phrases and structured with examples, but is slightly verbose for a single-parameter tool. Every sentence adds value, but could be tightened.

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 onboarding tool with one optional parameter and no output schema, the description covers what it returns, how to call it, and its role among sibling tools. Complete and actionable.

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

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

Schema coverage is 100%, and the description largely mirrors the schema's parameter description. It adds example topic values, but does not provide significant 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 clearly states the tool returns category-bucketed example questions for onboarding, with specific verb+resource and context like 'onboarding entry point'. It distinguishes from siblings by positioning it as the first tool to use when unsure of Pipeworx's capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and mentions alternatives like meta-tools (ask_pipeworx, entity_profile). Provides when and when-not guidance.

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

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

Annotations indicate mutation (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent (idempotentHint=true). Description adds that the row is deactivated (soft delete) and ownership is enforced, which aligns with and extends the annotation context without contradiction.

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

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

Two sentences, front-loaded with the action, no filler. Every sentence provides essential context.

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

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

For a simple one-parameter mutation tool with no output schema, the description covers the mutation behavior, ownership constraint, and data persistence, making it fully complete.

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

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

Schema coverage is 100%, so the schema already documents the 'id' parameter. The description reinforces that the id comes from 'subscribe' but adds minimal 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 clearly states the action 'Cancel a subscription by id', specifies the resource (subscription), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by highlighting ownership enforcement and soft-delete behavior.

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

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

Explicitly states when to use ('you can only cancel your own subscriptions') and implies when not to use (if not the owner). Also clarifies that the row is deactivated, not deleted, so historical events are still accessible via recent_alerts.

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 declaring readOnlyHint and idempotentHint, the description adds meaningful behavioral context: it warns that 'could_not_verify' means the check didn't happen (not evidence against the claim) and that 'unsupported' means no source coverage. This goes beyond annotation-provided safety info.

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, with front-loaded example phrasings. Each sentence contributes (routing logic, verdict list, error semantics, efficiency note), though it is slightly 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 no output schema, the description compensates by listing possible verdicts, explaining the failure semantics, and mentioning the actual value and citation. It covers the tool's routing behavior and parameter use. Minor gaps like exact output structure are acceptable at 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%, so parameters are already documented. The description adds extra value by explaining tolerance_pct semantics (overrides implied tolerance, capped at 5, use 1–2 for hallucination detection) and gives a concrete claim example, enriching the bare schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses explicit verbs ('verify', 'fact check') and provides example phrasings, distinguishing it from generic search or research 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,' giving clear when-to-use context. It also notes that it replaces 4–6 sequential calls, implying efficiency, but does not name specific sibling tools for comparison or exclusion.

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