ukpolice

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds valuable context beyond that: the default model is free, probing Anthropic requires the user's own API key, and 'you pay Anthropic directly for those calls' highlights a cost implication. It also outlines the per-model return structure, giving good transparency for a safe read operation.

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 deliver the core purpose, default/configuration detail, return shape, and use cases with no filler. The information is front-loaded and 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 read-only probing tool with rich annotations and 100% schema coverage, the description covers the essential extras: return format, default behavior, cost note, and typical scenarios. It is slightly shy of a 5 because it does not mention potential caveats (e.g., hallucinated answers, latency) or clarify whether 'signals' are textual, but the provided context is sufficient for correct use.

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 all four parameters are already documented in the input schema. The description reinforces the default model ('Workers AI Llama-3.3-70b (free)') but adds no new parameter-specific meaning beyond what the schema provides, earning the baseline 3.

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

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

The description clearly states the verb 'Probe' and the resource ('LLMs for what they know about a business / brand / product / topic') plus the output concept ('score visibility (0-100) per model'). It is specific and actionable, though it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it loses the top point for explicit sibling distinction.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and states the default model and when to pass _apiKey ('pass `_apiKey` to also probe Anthropic'). It does not mention when not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness. The description adds valuable behavior context: routing to the right tool, filling arguments, returning citations, and working on every tier with one fast call. It does not mention failure modes or rate limits, but the annotation safety profile lowers the burden.

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

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

The description is long but densely packed with decision-relevant content: preference signal, domain list, trigger phrases, examples, and alternatives. It is front-loaded with 'PREFER OVER WEB SEARCH' and 'START HERE', and every sentence serves a purpose, though it could be tightened slightly without losing value.

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

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

The description fully equips an agent to select and invoke the tool: it explains the return format (structured answer with citations), domain coverage, default-entry status, tier support, and when to use sibling tools. No output schema exists, but the description compensates by clarifying the expected result and workflow.

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

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

Schema coverage is 100% and all six parameters are clearly documented as aliases for the single 'question' field. The description reinforces parameter usage with examples and domain guidance, but adds no new syntax or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: it routes questions across 5,529 tools from 1,455 verified sources and returns structured answers with stable pipeworx:// citation URIs. It also distinguishes itself from siblings by explicitly stating 'START HERE' and naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit preference directives ('PREFER OVER WEB SEARCH'), trigger phrases ('what is', 'look up', 'find'), and concrete examples. It also gives exclusion guidance by naming when to step up to ask_pipeworx_grounded or deep_research, and handles the breaking-news edge case.

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, openWorldHint, idempotentHint), the description adds substantial behavioral context: it explains the tool is an experimental edge, currently matches ask_pipeworx exactly, and that it "Falls back to nothing — this IS a full working router," preventing misconceptions about it being a stub. It also discloses the testing mechanism (results compared against stable) and current status (no active candidate). This goes well beyond annotation disclosure.

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

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

The description is three sentences, but the first sentence is long and dense, packing the core definition and scope. It is well-structured: definition, current status, usage guidance, and a clarifying note about fallback. Every sentence adds value, and the length is justified by the need to explain the beta/experimental nature, though it could be slightly tighter.

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

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

The description covers the tool's purpose, current behavior, relationship to the stable router, and full working status. It references the same response shape as ask_pipeworx, and since there is no output schema, this provides essential context. With good annotations and a simple input schema, the description is sufficiently complete for a routing tool.

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

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

Schema coverage is 100%, with all six parameters described in the schema as aliases for "question." The description adds no parameter-specific meaning beyond referring to "same arguments" as ask_pipeworx, which is already implicit. Since the schema fully documents the parameters, the baseline of 3 applies.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,529 tools, and distinguishes it from the stable version by noting it has "candidate routing improvements enabled live." It also states it is"identical" to ask_pipeworx when no candidate is active, making its purpose and relationship to siblings explicit.

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

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

The description provides clear usage context: "Use it exactly like ask_pipeworx when you want the newest routing." It also mentions the stable router as an alternative and explains that results are compared against it. However, it does not explicitly state when not to use this tool or compare it with other siblings like ask_pipeworx_grounded, so it falls short of a 5.

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

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

While annotations already declare readOnly, idempotent, and non-destructive, the description goes well beyond by detailing the internal routing (5,529 tools across 1,455 sources), the extraction constraint (only from tool result), the exact success/refusal response shapes with refusal reasons, and the cost tradeoff. This adds significant behavioral context and does not contradict the annotations.

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

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

The description is dense but every sentence earns its place: it starts with the core purpose, then explains routing and extraction, details the return contract, lists refusal reasons, and gives usage guidance with cost tradeoff. It is slightly long but not wasteful, and the structure is logical and front-loaded.

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

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

With no output schema, the description thoroughly documents the return structure and refusal reasons, filling that gap. Combined with rich annotations and clear sibling differentiation, an agent has complete context for selecting and invoking this tool correctly, including edge cases like data truncation and no tool match.

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

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

The input schema provides 100% coverage: all six parameters are documented as aliases for 'question', each with a description. The tool description adds no additional parameter semantics, but the schema already fully explains the parameters, so the baseline 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 identifies the tool as a 'hallucination-resistant answer mode' that extracts answers solely from tool results, distinguishing it from siblings like ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior. The purpose is specific, with a verb ('ask') and resource ('Pipeworx') plus the grounded modifier.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and provides concrete examples. It also names the alternative ask_pipeworx and advises preferring it for casual lookups due to the extra LLM call cost, giving 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?

The description discloses many behaviors beyond the annotations: low-confidence matches short-circuit with status, closed markets return a specific status, wide-spread markets carry an illiquidity flag, and rate-limit fallbacks (GDELT 429s) are explained. It also details resolution-rule risks like refund_50_50 and the safety rationale. This is far richer than the readOnly/idempotent 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?

The description is long but tightly structured with headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and every sentence adds information. It front-loads the core purpose in one sentence. While lengthy, the density and organization keep it effective 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?

With no output schema, the description carries the full burden of explaining return values. It thoroughly covers result.market, result.analysis, result.evidence, the resolver contract (market_match_confidence, alternatives, suggestions), the parent_event extractor, news fallback fields, safety statuses, and resolution-rule risk. This is exceptionally 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?

Although the schema already describes all 3 parameters with 100% coverage, the description adds significant value: it gives examples for the market parameter, explains depth 'quick' vs 'thorough' behavior, and provides concrete size estimates for include_raw (~20KB vs 50-500KB). This goes beyond the schema and helps agents make informed parameter choices.

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

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

The first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes it from siblings like polymarket_arbitrage and validate_claim, which have different goals.

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 for' with three query patterns, and provides extensive fan-out examples for different market types (BTC, Fed, Hormuz, etc.). It does not explicitly name alternatives or exclusion criteria, but the usage context is clear and actionable enough for tool selection.

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

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

Adds rich behavioral context beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). Annotations already declare readOnly, non-destructive, and idempotent, and the description does not contradict these.

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 provides value: purpose, usage preference, data sources, fiscal-year handling, sorting, and output. The phrasing is dense but not bloated, and it is front-loaded with the core purpose and the key directive to prefer this tool over sequential lookups.

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 sufficiently explains the return value (paired data + pipeworx:// citation URIs per entity) and covers the nuances of both entity types, including fiscal-year edge cases and sorting behavior. It provides enough context for an agent to invoke correctly.

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

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

The schema already covers both parameters with 100% coverage (type enum and values description). The description adds meaning by explaining what each type pulls ('type="company" pulls LATEST 10-K...') and gives examples of values for both types, which enriches the schema's basic 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 call, with concrete example queries ('Compare X and Y', 'rank these companies'). It differentiates from siblings by explicitly directing 'ALWAYS PREFER over sequential single-pack lookups when comparing 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?

Provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it 'Replaces 8–15 sequential lookups.' It also explains the distinction between company and drug types, helping the agent decide when 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds extensive behavioral context beyond these: expected latency (15-60s, up to 90s), account/paid-tier requirements, gaps[] never invented, contradictions[] for standard/thorough, citation_uri resolvability, and semantic excerpting of large records. No contradiction with annotations.

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

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

The description is a single, dense paragraph with no structural breaks, making it hard to scan. It is comprehensive but not concise; several sentences repeat schema content or restate the ask_pipeworx comparison, and the core purpose is buried after the account-requirement opening rather than front-loaded.

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

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

With no output schema, the description fully explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), latency expectations, auth requirements, and limitations (e.g., poor for breaking news). It is exceptionally 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% with already descriptive parameter definitions (depth offers quick/standard/thorough with facet counts and behaviors; question accepts natural language). The description adds value by giving example questions and clarifying that depth:'thorough' is paid, but much of the depth behavior is already in the schema, so it only partially extends beyond the structured data.

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

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

The description explicitly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, decomposing questions into facets and routing them to 5,529 tools in parallel. It clearly distinguishes from sibling tools with statements like 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.'

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

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

Explicit guidance is provided: 'Best for broad/multi-part questions over structured data' versus alternatives. It gives specific when-to-use and when-not-to-use instructions, including 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx,' naming the alternative tool 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=true and idempotentHint=true. The description adds useful behavioral context about the return value: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This tells the agent the result is self-contained, going beyond the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence adds value: purpose, usage context/domain list, and behavioral output/recommendation. The domain list is lengthy but informative, not wasteful.

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

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

For a discovery tool with 6 params, no output schema, and full annotation coverage, the description covers the purpose, usage timing, output format, and self-contained nature. It is complete enough for an agent 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 description coverage is 100%, so the baseline is 3. The description only indirectly references the 'limit' parameter via 'top-N' and does not add new meaning about query aliases or format. It keeps the baseline without sufficient added value for a 4.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly states what the tool does and distinguishes it from sibling tools (e.g., get_crimes, get_forces) by positioning it as a discovery/meta tool, reinforced by 'Call this FIRST when you have many tools available.'

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also implies a when-not-to-use condition ('not just one answer') but does not name specific alternative tools, so it earns a 4 rather than a 5.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: it fans out across multiple sources, returns specific fields, notes the USPTO PatentsView API sunset and soft-failure behavior, and explains the GDELT→GNews fallback chain. This is rich, useful behavioral 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?

The description is long but front-loaded with example queries and a clear preference directive. Every sentence adds value—covering output fields, URIs, fallbacks, and input constraints—though it is dense and could benefit from structured formatting. It is appropriately sized for a tool with such broad behavior.

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

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

Given there is no output schema, the description carries the full responsibility of explaining the return value. It enumerates all returned components (CIK, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and communicates input constraints, fallback behavior, and API sunset status. This leaves no major ambiguity for the agent.

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

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

Schema coverage is 100% and both parameters (type, value) are thoroughly described in the input schema, including the names-not-supported caveat. The description repeats these points and adds concrete examples like 'AAPL' and '0000320193', but it does not significantly augment the parameter semantics already present in the schema.

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

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

The description clearly states what the tool does: it produces a full cross-source profile of a US public company in one parallel call. The verb is specific (profile/brief/rundown) and it explicitly distinguishes itself from chaining single-pack SEC/XBRL/news lookups, making it easy for an agent to select over sibling tools.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear exclusion: names are not supported, and directs the agent to use resolve_entity first, which is listed as a sibling 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 destructiveHint=true and readOnlyHint=false, so the description adds value by explaining what is destroyed ('previously stored memory') and when it is appropriate to do so. It gives concrete examples of data to clear, but could add more detail about irreversibility or effects beyond the annotations.

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

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

The description is two sentences with no redundancies. The first sentence states the action, the second lists use cases and sibling tools, making it front-loaded and efficient.

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 required parameter, no output schema, and strong annotations, the description covers the essential 'what', 'when', and 'how' (by key). It also points to related tools, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema description covers the 'key' parameter fully ('Memory key to delete'), and the description references it ('by key') without adding format details or examples. Since schema_description_coverage is 100%, baseline is 3; the description provides marginal supplementary context but does not significantly exceed 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' with a clear resource ('previously stored memory by key'), which precisely states the action. It distinguishes from siblings like 'remember' and 'recall' by focusing on deletion rather than creation or retrieval.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also names sibling tools to pair with ('Pair with remember and recall'), providing clear context 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 already cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a single text blob. This is meaningful context beyond annotations, though it doesn't mention failure modes or limitations.

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

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

The description is three sentences with no fluff. It front-loads the core purpose, then explains the process/output, and ends with use cases. Every sentence contributes value.

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

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

Given the tool's simplicity (2 params, no output schema, rich annotations), the description is quite complete. It covers what it does, how it works, and when to use it. It lacks explicit limitations (e.g., public pages only) but is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. Both parameters (url and max_links) are well-described in the schema. The description does not add significant extra meaning beyond what the schema already provides, so a 3 is appropriate.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It specifies the verb (generate), the resource (llms.txt file), and the target audience (AI crawlers). It also distinguishes itself from siblings by focusing on the llms.txt format specifically.

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

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

The description provides a 'Useful for' section with three specific scenarios (client indexing, own project, competitor audit). This gives clear context on when to use the tool, though it does not explicitly mention alternatives or when not to use it, which would earn a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: the two-month data lag, the fact that unpublished months are reported as 'not yet published' rather than as zero crime, and that omitting date returns the latest published month. This is genuinely valuable operational disclosure.

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 the core purpose ('street-level crimes near a lat/lng'), followed by return value details and the date-behavior nuance. It's efficient with no wasted sentences, though it could be slightly more scannable with line breaks. The structure is functional for the amount of information conveyed.

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

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

The tool has an output schema (reducing the need to explain return values), 100% schema coverage, and strong annotations. The description covers the key operational nuance (data lag and unpublished-month handling) which is the most important thing an agent needs to know. It's complete for a read-only query tool with a well-specified schema; a 5 would require even more edge-case handling or explicit error semantics.

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 all three parameters (lat, lng, date) are fully documented in the schema itself. The description reinforces the lat/lng semantic (crimes near a location) and the date lag behavior, adding some value. However, most parameter explanation is duplicated in the schema, so the description mostly echoes rather than extends the schema. Baseline 3 with slight reinforcement is fair.

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

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

The description uses a specific verb+resource ('Get street-level crimes reported near a latitude/longitude...from the official police open data') and clearly distinguishes the tool's scope (England/Wales/Northern Ireland, street-level crimes). It even provides example question phrasings ('what crime was reported near <place>') that help an agent map user intent to this tool versus siblings like get_outcomes or get_forces.

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 on when to use the tool (when crime questions reference a place) through the example questions, and explains the date behavior (omit for latest month, feeds run two months behind). It does not explicitly name alternative tools or state when NOT to use it, so it falls short of a 5, but the contextual usage guidance is solid.

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 claims to list 'all' police forces, which contradicts the annotation openWorldHint=true, indicating the tool may not return a complete/closed-world set. This is an annotation contradiction, leading to the score of 1.

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

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

The entire description is one concise, front-loaded sentence that specifies action, scope, and return fields. Every word earns its place, with no redundancy.

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

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

For a simple parameterless list tool with an output schema and comprehensive annotations, the description provides all necessary contextual information (geographic scope, return content). The contradiction with openWorldHint is a transparency issue already scored, but contextually the description 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?

With zero parameters, the baseline is 4. The description adds no parameter-specific meaning since none exists, and the schema confirms this. No further compensation 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 the tool's action ('List all police forces'), scope ('England, Wales, and Northern Ireland'), and return fields ('force ID and name'). This distinguishes it from siblings like get_crimes and get_outcomes, which focus on crime data.

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 clear usage: whenever a list of police forces is needed, likely as reference data for other tools. However, it does not explicitly mention alternatives or exclusionary conditions. Given the tool's simplicity and zero parameters, the context is sufficiently clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the response includes outcome category and date, but since an output schema exists per context signals, this is largely redundant. No extra behavioral context such as pagination, error cases, or limitations is provided.

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, and no filler. Every word contributes to either the purpose or the return fields. This is an example of conciseness without under-specification.

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 3-parameter tool with 100% schema coverage and rich annotations, the description is nearly complete. It states the core purpose and return essence, with the output schema expected to fill in details. Minor gaps remain, such as not describing error scenarios or edge cases like no-crime months.

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 cover all three parameters (lat, lng, date) with clear format and default behavior, so baseline 3 applies. The description's phrases 'at a location' and 'given month' merely restate the parameters without adding new semantics or usage details.

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

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

The description opens with 'Get outcomes for crimes at a location for a given month,' clearly identifying the verb (get), resource (outcome categories/dates), and scope. It distinguishes from the sibling get_crimes by focusing on outcomes rather than raw crime records, and explicitly specifies what is returned.

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?

No explicit when-to-use guidance or exclusions are provided. The phrase 'for a given month' implies temporal context, but there is no mention of alternatives or when to prefer this over get_crimes. Usage is implied rather than explicitly stated.

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 destructiveHint=false, so the safety profile is known. The description adds useful context about caller-scoped data, default 'active' filtering, and the exact return fields, going 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 filler. The action and return information are front-loaded, and the second sentence provides actionable use cases, making it optimally concise.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and use cases. It is self-sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for the only parameter (include_inactive), so the schema fully documents it. The description adds no additional parameter detail, meeting the baseline for high schema coverage.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like subscribe/unsubscribe. It also enumerates return fields, providing precise scope.

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

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

Explicit use cases are stated: 'review what you're monitoring before adding more' and 'to find an id to cancel', which implicitly reference subscribe and unsubscribe as alternatives. This gives direct when-to-use guidance.

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

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

Beyond the annotations (all false), the description discloses essential behaviors: rate-limited to 5 per identifier per day, returns a claim_token when filing without an account, and how to use that token to check resolution status. It also mentions free usage and no quota impact, which are useful 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?

The description is somewhat long, but every sentence earns its place by covering purpose, use cases, exclusions, token workflow, rate limit, and cost. It is front-loaded with the core action and then provides necessary context. Slight deduction for length, but 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 complexity (multiple feedback types, claim-token workflow, scope restrictions), the description fully covers what to report, when to use it, how to identify Pipeworx tools, how to retrieve status, and operational constraints. No output schema exists, but the description explains the claim_token return and follow-up behavior, making it complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds valuable parameter semantics: instructing not to paste the end-user's prompt, describing issue scope in terms of Pipeworx tools/packs, and showing exact usage of claim_token. This enriches understanding beyond the schema's field 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 submits feedback to the Pipeworx team about broken, missing, or praise-worthy tools. It distinguishes itself from sibling tools by focusing on feedback about Pipeworx tools/packs, not on asking questions or discovering tools. The verb 'Tell' and resource 'Pipeworx team' are specific.

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 specifies when to use (bug, feature/data_gap, praise) and provides an exclusion: not for tools from other MCP servers, with the alternative to file with that server instead. It also clarifies that Pipeworx tool names are those listed by this connection, giving concrete guidance for identifying applicable tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context beyond that: caching behavior (5min–1h), data source (CF analytics-engine), and privacy (no PII). This is useful behavioral disclosure.

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

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

Three sentences, front-loaded with the primary output, followed by enumerated use cases and a concise data provenance note. Every sentence adds value and there is 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?

No output schema exists, but the description states what is returned (top tools, top packs, total call volume) and the data shape ('pack, tool, count'). Caching and window semantics are also covered. Missing error cases, but adequate for a simple read-only tool.

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

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

Schema coverage is 100% with a descriptive enum for window. The description mentions the same 24h/7d/30d windows but adds no additional parameter semantics. Baseline 3 is appropriate as the schema carries the load.

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?

Uses a specific verb+resource: 'Returns the top tools, top packs, and total call volume over a recent window.' The description clearly differentiates from siblings like discover_tools by focusing on aggregate call volume from other agents, not suggesting tools.

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

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

Explicitly lists three concrete use cases (#1 discovering hot data sources, #2 confirming canonical choice, #3 alignment with agent needs). It doesn't name alternative tools, but the guidance is clear enough to decide when to invoke.

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

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

The description discloses detailed behavioral traits well beyond the readOnlyHint annotation: partition filters, Jaccard similarity threshold, placeholder handling, and fill-check logic with realizable vs theoretical edge. It explains when signals should be rejected ('realizable_edge_pp ≤ 0 means... do not trade it'). No annotation 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 long but well-structured with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the main purpose and invocation modes. Every sentence carries operational detail, though some sections are dense and could benefit from tighter phrasing. It earns its length given the tool's complexity.

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

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

With no output schema, the description fully specifies the response structure including opportunities[], partition_check fields, and null-arb conditions. It covers failure modes, filter thresholds, and points to polymarket_fill_risk for custom sizing, making the tool usable without external documentation. Given the tool's high complexity, this is remarkably 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?

Although the schema already describes 'event' and 'topic', the description adds deep semantics: event mode walks child markets and checks date/threshold ordering, topic mode searches related events and flattens markets. It provides concrete examples ('fed-decision-may-2026'), explains the distinction, and notes recommended usage, transforming bare schemas into actionable guidance.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' which is a specific verb+resource statement. It clearly distinguishes tool purpose from related siblings by highlighting unique techniques (monotonicity, partition checks) and explicitly defines three invocation modes (trending_scan, event, topic).

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: '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 topic for cross-event scanning, and even points to an alternative tool: 'For custom sizing use polymarket_fill_risk.'

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 (readOnly, idempotent, non-destructive), the description discloses a wealth of behavioral detail: three response segments with model definitions, edge_pp_net net of slippage, Kelly caps at 0.25, a 24h-move warning, exclusion of Fed bets due to unreliable signal, diagnostics funnel counters for empty segments, and 1-hour KV caching keyed on all knobs. This far exceeds what annotations provide and contains 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 long but information-dense, with purpose front-loaded and clear structural labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Every sentence contributes value, and the structured formatting aids scanning. It could be slightly tightened but is not wasteful.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: top-level by_segment structure, per-item fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips to explain empty segments. It also covers caching semantics and constraints, making it fully actionable for an agent.

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

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

The schema already covers all 9 parameters with 100% description coverage, so the baseline is 3. The tool description adds meaningful semantic nuance beyond the schema, particularly for min_partition_leg_kelly (explaining why partition_overround returns kelly_fraction_half=0 at parent level, so min_kelly doesn't apply) and for tradeable-edge filters (min_liquidity, max_spread_pp) that drop opportunities 'where edge isn't realizable.' This extra context raises the score above baseline.

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

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

The description opens with a specific action and scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from sibling tools like polymarket_arbitrage by framing this as a broad opportunity discovery tool for 'what should I bet on today' rather than a narrow arbitrage finder.

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 the intended use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also describes tradeable-edge knobs (min_liquidity, max_spread_pp) that indicate when to filter results. However, it never explicitly names alternative tools or states when not to use this one, so it falls short of a full 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, and non-destructive behavior. The description adds substantial context beyond annotations: snapshots are written on cache-miss so gaps mean no scan, history depth is bounded by a 60-day TTL, and decay numbers come from daily closes, not intraday. This goes well beyond the structured 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?

The description is long but information-dense, with clear sections for ARGS, RESPONSE, and LIMITS. Every sentence adds value, and it's well-structured for the complexity of the tool, though it could benefit from bullet points for readability.

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

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

With no output schema, the description fully specifies the response structure: tracked[], expired[], and snapshot_dates[] along with their fields. It also explains important caveats like TTL limitations and snapshot gaps, making the tool self-sufficient for an agent to understand and invoke correctly.

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

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

The JSON schema already describes both parameters with 100% coverage. The description adds the concept of 'snapshot family' for the window parameter and clarifies the lookup defaults and max, providing marginal additional meaning beyond the schema.

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

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

The description explicitly states this provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from sibling tools like polymarket_edges, which likely focus on current edges.

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

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

It gives a clear use case ('Answers how long has this edge existed and is it shrinking?') and even explains why edge age matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it doesn't explicitly name alternatives or state when not to use this tool, though the sibling list is available.

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

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

The description discloses extensive behavioral traits beyond the annotations: it walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, and a verdict (clean|degraded|cannot_fill). It explains the risks of partial fills and forced directional risk in basket mode. The annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are consistent with the description, and the description adds significant context about the tool's operational behavior and output semantics.

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

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

The description is long but every sentence delivers essential information. It is front-loaded with a clear purpose, then uses structured markers (SINGLE-MARKET:, BASKET:) to walk through modes without wasted prose. The usage guidance is placed at the end as a practical 'when to use' rule. Given the complexity of the tool (two modes, multiple output fields, risk warnings), the length is justified and well-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?

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively: it lists the return fields for both single-market and basket modes, explains the verdict values, and names the risk output (forced_directional_risk). It also provides essential operational context (size clamping, defaults, auto side selection). The description is complete enough for an agent to understand what the tool does, when to use it, and what results 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?

Although the input schema already provides 100% parameter coverage, the description adds critical semantic meaning. It explains the mutual exclusivity of `market` and `event` ('REQUIRES one of'), clarifies the interpretation of `size_usd` differently per mode ('max spend on buys, target proceeds on sells' vs 'settlement notional S'), and defines the `side` values' purpose in each mode ('sell_yes = capture overround', 'buy_yes = capture underround'). This goes well beyond the schema's basic field descriptions.

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

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

The description opens with a clear, specific statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This uses a precise verb ('check') and resource ('live CLOB order-book depth'), and it clearly distinguishes the tool from siblings by naming polymarket_arbitrage and polymarket_edges as related but different tools. The two modes (single-market and basket) are explicitly defined, leaving no ambiguity about what the tool does.

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 states exactly when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the reasoning ('theoretical overround on thin books is not capturable' and 'partial basket fills convert an arb into an unhedged directional position'), providing clear when/why guidance. It does not explicitly say when not to use, but the context implies alternatives (e.g., not using it for small trades or for other 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?

Despite annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial behavioral context that the annotations do not cover. It discloses compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs. matched_pairs:0 with skipped_cross_type:0 and both venues >5 legs), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also explains that the delta is only a real signal when bet shapes are equivalent. This is exactly the kind of extra context that helps an agent interpret results safely.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose and then provides necessary operational detail. However, it is quite dense and could be trimmed slightly without losing critical information, especially the repeated warnings about pre-mapped topics. The structure and scannability keep it from being a wall of text, but it's still near the upper limit of acceptable 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?

There is no output schema, so the description must explain the return values, and it does: 'each venue's leg-by-leg prices (raw probability 0-1) plus matched spread[].top_spreads_pp (Kalshi − Polymarket).' It also covers edge cases such as temporal alignment and skipped cross-type/cross-subtype comparisons, providing a complete mental model for interpreting results. Given the tool's complexity and the lack of an output schema, this description is thorough and self-sufficient.

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

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

Schema description coverage is 100% and each parameter has a clear description. The tool description adds value by explaining the relationship between parameters: how 'topic' is a shortcut and how the explicit ticker/slug parameters override the mapped side. It also clarifies the output semantics tied to these parameters (e.g., matched spread). While the schema covers the 'what', the description covers the 'how to combine them', which is marginally beyond the schema, so a 4 is appropriate.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from sibling tools by focusing on the spread between two venues, and it explains the two operational modes ('topic' and explicit pairings). This makes the tool's purpose unmistakable.

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

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

The description explicitly explains the two modes of use (pre-mapped topic shortcuts vs. explicit event ticker/slug overrides) and provides a critical usage warning: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' This tells the agent when the tool's output is reliable and when it is not, effectively guiding selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds context about scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID). It also explains the list behavior when omitting the key. No contradictions, and the added scoping detail goes 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?

The description is compact and front-loaded with the core action. Each sentence contributes value: the main purpose, usage examples, scoping, and related tools. No fluff or redundancy.

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

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

For a simple memory-retrieval tool with good annotations and clear scoping, the description is sufficiently complete. It covers the main actions, usage context, scoping, and related tools. No output schema is needed since the output is the saved value or key list, and the behavior is straightforward.

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

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

The schema already covers the single parameter 'key' with the description 'Memory key to retrieve (omit to list all keys)', and schema coverage is 100%. The tool description mostly repeats this information, though it adds that values were 'previously saved via remember', which provides minor additional context but does not significantly elevate understanding.

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

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

The description clearly states the tool retrieves a saved value or lists keys, using specific verbs ('retrieve', 'list') and resource ('value previously saved via remember'). It also distinguishes itself from the sibling tools remember and forget by explicitly referencing them.

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

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

The description provides explicit guidance on when to use the tool ('Use to look up context the agent stored earlier...') and even gives examples (ticker, address, research notes). It also mentions pairing with remember and forget, offering clear alternative tool relationships.

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

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

The description explicitly states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones,' which is a mutation of state. This directly contradicts the readOnlyHint:true annotation, creating a serious inconsistency. The description reveals a side effect that the annotation denies, so it scores 1.

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

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

The description is three sentences, front-loaded with the main purpose. Each sentence adds useful information: the return payload fields, filtering options, mark_read behavior, and the HTTP alternative. It is efficient but slightly dense, so it earns a 4 rather than a 5.

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

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

Given no output schema, the description compensates by explaining the return structure (source, citation_uri, raw payload) and the mark_read side effect. It also includes polling guidance and an HTTP endpoint alternative. Despite the annotation contradiction, the description itself is reasonably complete, though it misses details on unread_only's interaction with mark_read.

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

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

The input schema already provides 100% descriptive coverage for all five parameters. The description adds a concrete example type ('sec_8k') and reinforces the mark_read side effect, but these are minor additions over the schema, so it stays at 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 a specific verb and resource: 'Pull fired events from your subscription feed.' This clearly distinguishes it from siblings like list_subscriptions and subscribe, which manage subscriptions rather than retrieve past events.

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

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

Provides clear context by stating the tool retrieves fired alerts, works well for polling, and mentions the same feed is available via HTTP endpoint for scripts/dashboards. However, it does not explicitly exclude alternatives like list_subscriptions or describe when not to use this tool, so it stops short of a full when/when-not guideline.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing the multi-source fan-out behavior, the GDELT→GNews fallback chain, the USPTO soft-failure due to PatentsView API sunset, and the exact return shape (changes[], total_changes, citation URIs). This provides rich behavioral context without contradicting annotations.

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

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

The description is long but front-loaded with user-facing query examples and structured logically: use case, fan-out behavior, parameter formats, return shape, and alternative tool. Every clause contributes meaningful detail, though some implementation specifics could be trimmed without losing value.

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

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

With no output schema, the description fully explains what the tool returns, including grouped changes, total count, and citation URIs. It also covers failure modes and source selection logic, making it complete for a complex multi-source 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, but the description adds a practical usage recommendation ('Use "30d" or "1m" for typical monitoring') and reinforces the accepted formats with concrete examples. It doesn't fundamentally change parameter understanding but does add minor guidance beyond the schema.

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

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

The description explicitly states it provides a 'change feed for a company in the last N days/weeks/months' and enumerates concrete query patterns like "What's new with X" and "latest on Y". It also distinguishes itself from the sibling tool entity_profile by explicitly recommending that tool for static profiles.

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 through example natural-language queries and a recommended time window. It explicitly names an alternative (entity_profile) and explains when to use it instead, satisfying the when-not and alternatives criteria.

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

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

Beyond annotations, it discloses that memory is scoped by user identifier, and specifies persistence: authenticated users get persistent memory, anonymous sessions retain for 24 hours. This adds meaningful behavioral context (auth needs, retention) beyond structured annotations.

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

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

Four short sentences, front-loaded with purpose, then usage, then technical details. No superfluous 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?

For a simple key-value write tool, the description covers what it does, when to use it, how data is scoped, retention behavior, and related tools. No output schema is needed, so nothing essential is missing.

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

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

The input schema already describes both parameters with examples and value type (100% coverage). The description's examples ('resolved ticker, target address, user preference') overlap with schema's examples and add no new technical constraints.

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 'Save data the agent will need to reuse later' — a specific verb+resource. It provides concrete examples and explicitly names sibling tools recall and forget, distinguishing this as the storage operation.

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

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

It provides explicit 'Use when' guidance with examples of what to store, and directs pairing with recall/forget, making appropriate usage and alternatives clear.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), it discloses internal cascading through multiple endpoints, source-labelled identifiers, explicit `unresolved` reporting, and graceful degradation if GLEIF/OpenFIGI are unavailable. This is rich behavioral context that annotations alone do not provide.

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

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

The description is long but front-loaded with user-facing examples and a 'Use FIRST' directive; information is organized by supported types. It is dense but every sentence adds value, so length is justified.

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 adequately describes return behavior for both entity types and failure/degradation modes. It does not fully specify the exact JSON shape, but for a resolution tool with rich source details it is sufficiently complete.

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

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

Schema already provides 100% coverage for both parameters, so baseline is 3. The description adds meaningful semantics: explains what each type returns (company vs. drug), acceptable input formats for value (ticker, CIK, name), and implications such as enrichment fallback. This goes beyond schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers like CIK, LEI, FIGI, RxCUI—identifiers other tools require. It opens with concrete examples and distinguishes itself from siblings by focusing on name-to-ID resolution, which is a specific verb+resource purpose.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID' and provides example queries. It does not list when to avoid using the tool or name alternative tools, but the guidance is clear and actionable.

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

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

The description adds meaningful behavioral detail beyond the annotations: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This goes beyond the read-only/idempotent hints. It does not disclose rate limits or cost implications, but the annotations cover the safety profile adequately.

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

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

The description is three sentences, each earning its place: first states the core function, second explains the mechanism and output, third gives a use case. No redundant wording, and the formatting is clear with a quoted example.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description is fairly complete: it explains what it does, how it works, what it returns, and when to use it. It lacks explicit mention of model options or entity ordering (first is subject), but those are covered in the schema or are minor gaps. Overall, it provides enough context for reliable invocation.

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

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

The input schema provides 100% coverage for all parameters, including descriptions for models, _apiKey, context, and entities. The tool description adds no additional parameter semantics beyond what the schema already offers, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Compare') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes itself from the sibling tool ai_visibility_check by emphasizing side-by-side comparison and ranking, and from compare_entities by focusing specifically on AI visibility rather than generic entity comparison.

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

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

Provides clear context: 'Useful for competitive AI-marketing audits' with a concrete example question. It implies when to use this tool over ai_visibility_check (single entity) by describing multi-entity probing, but does not explicitly state exclusions or alternatives. Still, the guidance is sufficient 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 indicate read-only, idempotent, open-world, non-destructive behavior. The description adds critical behavioral context beyond annotations: the composite fan-out across two services, partial failure degradation, the 5-30s latency for first bundlephobia measurement, and the sources_failed output. No contradiction with annotations; in fact, it enriches them.

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

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

The description is a single dense paragraph but front-loaded with the core purpose and usage. It lists output fields and failure modes without unnecessary fluff. Slightly lengthy due to the output field list, but each clause earns its place. Could be broken into bullets, but structure is acceptable.

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 composite tool with no output schema, the description is remarkably complete: input, output fields, ecosystem scope, failure behavior, latency notes, and when to use alternative tools. It covers all aspects an agent needs to invoke and interpret the result correctly. 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% for both parameters (package and version), so the heavy lifting is done by the schema. The description reinforces version defaults indirectly via the output block (is_latest, alternative versions) but does not add new parameter-level meaning beyond what the schema already states. Baseline 3 applies.

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

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

The description states a specific verb+resource: a composite check for 'should I add this npm package to my project', clearly distinguishing it from sibling scan tools by focusing on npm dependency evaluation via deps.dev and bundlephobia. The scope (NPM ecosystem in v1) further differentiates it.

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 when-to-use guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion: non-NPM ecosystems should use deps.dev:version directly, naming the alternative. This fully addresses usage context.

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

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

The description adds concrete technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also explains the proof-of-origin value: 'every passage carries an offset so the agent can verify a verbatim quote.' 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?

Each sentence adds distinct value: definition, use case, pairing, and technical mechanism. It is front-loaded and efficient for the tool's complexity.

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

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

No output schema, but the description specifies the return format ('top-N passages with character offsets and similarity scores'), input constraints (200K cap, truncation with flag), and integration context with ask_pipeworx_grounded. This fully covers the agent's invocation and interpretation needs.

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

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

Schema coverage is 100%, with each parameter already described (text, query, limit). The description reiterates the text and query roles but adds no new per-parameter semantics beyond the existing schema descriptions. Baseline 3 applies.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from sibling tools like ask_pipeworx by emphasizing it searches within user-supplied text, and describes the output: 'top-N passages with character offsets and similarity scores.'

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: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also names a complementary tool: 'Pairs with ask_pipeworx_grounded.' This is clear usage guidance.

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

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

The description discloses many behavioral details beyond the annotations: OAuth requirement, feed always on, phone verification and 10/day SMS cap, webhook HMAC signing with a one-time secret, and auto-disable after 10 failed runs. It also says the tool returns the new subscription id. 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 long but well-structured: purpose first, then requirements, then supported types, then delivery channels. Every sentence carries necessary information for a complex tool; only minor overlap with schema details keeps it from a perfect score.

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 (3 params, nested objects, 5 enum types, no output schema), the description covers purpose, auth, type examples, delivery channels, and security details. It omits patent_grant and clinical_trial from the prose list, though these are in the enum and params description, so it's a minor gap.

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

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

The input schema already provides 100% coverage with detailed descriptions for type, params, and delivery, including examples for each subscription type. The tool description adds the always-on feed channel and the return id, but does not materially enrich parameter semantics beyond the schema; baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly distinguishes the tool from siblings like list_subscriptions and unsubscribe, and the supported types add further specificity.

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 states a clear prerequisite (Pipeworx OAuth account) and notes that anonymous/BYO cannot persist subscriptions. It also points out an alternative for consuming the feed via recent_alerts or a GET endpoint, giving context on when this tool is the appropriate choice for creating subscriptions.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the description only needs to add invocation and output behavior. It does: says it draws from a live catalog of thousands of tools, returns category-bucketed examples each with tool + argument shape, and can be called with no args for full spread or with topic to focus. 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 densely packed but well-structured: opening with user intents, then the return value, then invocation modes, then when to use. It is longer than minimal, but every sentence adds necessary context for a tool with no output schema and rich categorization behavior.

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

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

With no output schema, the description appropriately details the return value: category-bucketed example questions across clearly named categories, each with the exact tool and argument shape needed. It also covers both invocation modes and the onboarding context. Combined with annotations, it gives a comprehensive picture of what to expect, though a concrete example of the output shape would push it to 5.

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

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

Schema description coverage is 100%, but the description enriches the parameter 'topic' with concrete examples ('finance', 'pharma', 'betting') and explains the effect of omission ('cross-category spread'). This goes beyond the schema's basic description and helps the agent select and format the parameter correctly.

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

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

The description opens with concrete example questions, then clearly defines the tool as the onboarding entry point for agents that want to know what to ask Pipeworx. It distinguishes itself from siblings by explaining it returns category-bucketed example questions with the exact tool and argument shape from a live catalog, and explicitly says to use it FIRST.

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 guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter and names alternatives like ask_pipeworx, entity_profile, and compare_entities as examples of what the agent will learn to call, giving clear situational 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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds valuable behavior beyond these flags: ownership enforcement, deactivation instead of deletion, and that historical events remain via recent_alerts. It does not discuss error cases or return values, but for a simple subscription cancellation this is sufficient context.

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

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

The description is three sentences, each adding distinct information: the action, the ownership constraint, and the non-destructive effect. It is front-loaded with the core purpose and contains no filler or redundancy.

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

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

For a single-parameter cancellation tool with no output schema, the description covers the essential context: what it does, who can do it, and the side effects on data. It could mention what happens if the id is invalid or not owned, but given the low complexity and strong annotations, it is close to complete.

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

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

The input schema already fully documents the only parameter 'id' at 100% coverage, including that it is a subscription id returned by subscribe. The description adds little beyond saying 'by id', so the baseline of 3 applies since the schema carries the burden.

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

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

The description begins with a specific verb+resource pair ('Cancel a subscription by id'), clearly identifying the tool's action. It also distinguishes itself from siblings like subscribe and list_subscriptions by specifying the cancellation/deactivation behavior, and mentions ownership enforcement.

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 when to use this tool: when you want to cancel a subscription and need to understand that ownership is enforced and rows are deactivated not deleted. It does not explicitly name alternatives, but the context with subscribe and recent_alerts is clear enough; however, it lacks explicit exclusions or 'use instead' guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds essential non-obvious behavior: could_not_verify means the check failed and carries verification_error (NOT evidence), unsupported means no source covered, and the exact verdict list is disclosed. This goes well beyond the annotations and gives callers clear expectations for edge cases.

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 trigger phrases and a clear purpose, then moves efficiently through routing, return values, and caveats. Every sentence carries meaningful operational detail without fluff, making it long but appropriately sized for the tool's complexity.

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

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

With no output schema, the description fully covers what the tool returns: verdicts, actual value with pipeworx:// citation, reasoning, and structured error info. It also explains the two execution paths and tolerances, making it self-sufficient for an agent to decide and interpret calls 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%, and the schema already fully describes both 'claim' (with examples) and 'tolerance_pct' (with overrides and default). The description does not add parameter-level semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description defines a specific verb+resource: 'natural-language claim verification against authoritative sources' with concrete trigger phrases like 'fact check' and 'verify the claim that…'. It clearly distinguishes itself from sibling tools by outlining judgment verdicts (confirmed, refuted, etc.) and a structured pipeline, making it the go-to for factual claim checking rather than general queries.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and describes two routing paths (SEC EDGAR for company financials, grounded pipeline for others). It mentions replacing 4–6 sequential calls as an alternative, but does not explicitly name sibling tools or exclusions, so it stops short of a full when-not/alternatives breakdown.

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