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 destructiveHint=false. The description adds valuable behavioral context: the tool acts as a router, fills arguments on the user's behalf, returns structured answers with citations, and routes news queries to live news packs. It also discloses limitations, such as not being suitable for questions about Pipeworx itself.

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

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

The description is long but front-loaded with the most important routing advice: 'PREFER OVER WEB SEARCH'. The domain list, examples, and sibling exclusions are dense but useful. Some redundancy exists, such as repeating that web search could also answer it, but every sentence contributes selection or exclusion information.

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

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

For a read-only, one-required-parameter router with no output schema, this description is unusually complete. It states what the tool returns, when to use it, when not to use it, and which sibling tools to prefer in specific scenarios. An agent can confidently select and invoke this tool without additional context.

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

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

The input schema has 100% description coverage and already documents all six parameters as aliases for the same natural-language question field. The description contributes example questions and query-style guidance, but it does not add semantic detail beyond what the schema provides.

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

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

The description clearly states what the tool does: it routes a natural-language question to one of 5,767 tools across 1,506 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It also distinguishes itself from web search and from sibling tools like recall and deep_research through explicit routing guidance.

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

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

Usage guidance is explicit and actionable: trigger phrases like 'what is', 'look up', 'find', and 'get the latest' are listed, along with concrete examples. It also provides clear exclusions and alternatives: use recall for a single recorded event, validate_claim for a second opinion, deep_research for multi-part fan-out, and plain chat for conversational questions.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds valuable context beyond them: the live candidate-testing behavior, the current inactive state with a specific date, and the comparison process against the stable router. Nothing contradicts the annotations.

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

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

Four sentences, all load-bearing: identity, current state, usage guidance, and behavioral re-assurance. Slightly dense with embedded clauses, but front-loaded with the most critical info (beta status, identical behavior) and zero filler.

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

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

For a complex routing tool with no output schema, the description handles the gap via 'same response shape' reference to ask_pipeworx, which is sufficient for an agent to know what to expect. Covers current state, usage, and functionality; only detailed return-format documentation is deferred to the sibling.

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 covere is 100% with all six parameters described (question plus five aliases), so the schema carries the load. The description adds only 'same arguments' as a reference to ask_pipeworx, which is marginal. Baseline 3 is correct.

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

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

States the tool is a universal router (5,767 tools) and explicitly positions it as the beta version of ask_pipeworx, distinguishing it from the stable sibling and ask_pipeworx_grounded. The 'Use it exactly like ask_pipeworx' anchor removes any ambiguity about what operation it performs.

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

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

Gives an explicit when-to-use condition ('when you want the newest routing'), names the alternative (the stabe router), and clarifies that this is not a fallback stub ('Falls back to nothing — this IS a full working router'). No inference required.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive, and the description adds important behavioral context: it costs an extra LLM call, uses only tool-result content, returns explicit refusal reasons, and shapes success/refusal output formats. This goes well beyond what annotations convey.

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

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

The description is dense but every sentence earns its place: definition, routing behavior, success/refusal shapes, usage criteria, and cost tradeoff. It is well-structured and front-loaded with the core purpose and key caveat.

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

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

For a tool with no output schema, the description fully explains the return values and refusal reasons. It also covers when to use it, how it differs from its sibling, and operational cost, leaving no critical gap for an agent deciding whether and how to invoke it.

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

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

Schema coverage is 100%, so the schema fully documents the question parameter and its aliases. The description adds context about how the question is routed, but it does not need to repeat parameter-level semantics; baseline 3 is appropriate.

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

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

The description states a specific, differentiated function: a hallucination-resistant, grounded answer mode for Pipeworx. It explicitly contrasts with ask_pipeworx by explaining that it extracts answers only from tool results and can refuse when evidence is insufficient.

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: use whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts. It also names the alternative ask_pipeworx and recommends it for casual lookups, making the usage boundary clear.

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

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

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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses a rich behavioral contract: it returns a findings packet with verbatim evidence, confidence, source, fetched_at, and a stable pipeworx:// citation; it exposes explicit gaps[] for unanswered facets and never invents findings; standard/thorough depths also return contradictions[]. It also explains semantic excerpting and timing expectations, which is exactly the kind of contextual behavior an agent needs. No contradiction with annotations exists.

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 and well-structured: prerequisites are front-loaded, followed by the core capability, when-to-use examples, output contents, caveats, and latency. Every sentence carries operational value, and no part merely restates the tool name or title. The density is justified by the tool's complexity.

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

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

Given no output schema, the description thoroughly enumerates the return shape (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, citation_uri). It also covers authentication requirements, plan gating, latency, alternative routing, and non-open-web scope. An agent has everything needed to select and invoke this 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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter-level context beyond the schema: depth:'thorough' requires a paid plan, and depth:'standard'/'thorough' additionally return contradictions[] and an extra hop. It also clarifies the question parameter is meant for broad or multi-part natural-language questions. This goes beyond the schema's enum descriptions without being redundant.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in one call, and explicitly contrasts itself with open-web search. It also conveys the decomposition-and-parallel-routing mechanics, making it easy for an agent to know exactly what the tool accomplishes. The focus on broad/multi-part structured-data questions clearly differentiates it from siblings like 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?

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and includes concrete example queries. It also states when NOT to use it: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead.' This provides both inclusion and exclusion criteria, leaving no ambiguity.

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 declare readOnly/idempotent/destructiveHint, and the description adds rich behavioral detail: source fan-out list, soft-fail for USPTO sunset, 'sources_used/sources_failed' semantics, empty sections being real no-data, and resolved:false behavior for private companies. No contradiction with annotations.

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

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

The description is long but every sentence carries a distinct fact or examples; there is no fluff. However, it's a dense wall of text that could benefit from bullet points or more structural separation, so it loses one point 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?

For a complex multi-source tool with no output schema, this description is exceptionally complete: it covers input variants, source behavior, return fields, edge cases (private companies, empty sections), and failure semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for both parameters, but the description goes beyond by giving concrete examples ('AAPL', '0000320193', 'Moderna'), stating that 'type' values are interchangeable, and explaining name resolution via SEC EDGAR. This adds real operational meaning the schema alone doesn't convey.

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

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

The description starts with concrete example queries and immediately states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from single-pack lookups and sibling tools by describing the multi-source fan-out and the holistic-view use case.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear when-to-use instruction. It also scopes the tool to US public companies and describes the private-company fallback, so an agent knows when the tool won't fit.

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?

Beyond the readOnly/idempotent annotations, the description discloses the matching algorithm, safety fields, compatibility codes, null semantics for temporal_alignment, fee treatment, skipped-leg counters, and the caveat that pairing_unverified is always set. This is far more than annotations alone provide.

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

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

The description is long and dense, but almost every sentence earns its place given the tool's complexity and safety warnings. It opens with the core purpose and then delivers modes, response shape, and caveats in a logical order; minor redundancy and length keep it from a perfect 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?

With no output schema, the description carries the full burden of explaining return values, and it does: leg prices, top_spreads_pp, compatibility fields, flags, skipped counters, fees note, and temporal alignment semantics. Optional-parameter behavior is addressed via mode explanations, leaving no critical gap for calling 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining the topic shortcuts auto-fetch matching events and that explicit ticker/slug override the topic-mapped side. It doesn't fully specify validation rules or required combos, but it goes 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 opening sentence names a specific resource and action: cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes this from pure single-venue or edge tools by emphasizing the two markets, but it never explicitly names a sibling tool to route away from.

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 two modes ('topic' vs explicit ticker/slug) are clearly explained with concrete examples and precedence ('Overrides the topic-mapped ... side'), and the 'pre-mapped ≠ tradeable' warning gives practical context. However, it doesn't say when a sibling tool like polymarket_arbitrage or polymarket_edges would be a better choice.

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?

Annotations already declare readOnly/idempotent/openWorld behavior, but the description adds substantial beyond-annotation context: ambiguous names return figi_candidates instead of asserting a match, unresolved identifiers are explicitly listed, LEI/FIGI enrichment degrades gracefully, and multiple internal lookups are cascaded. This far exceeds the 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?

The description is front-loaded with useful trigger phrases and 'Use FIRST,' but the body is an extremely dense run-on paragraph with nested parentheticals that are hard to scan. No sentence is strictly wasted, but the formatting makes the content harder to parse than it should be.

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 must explain return behavior, and it does: labeled sources, unresolved identifiers, figi_candidates, drug RxCUI/brand/ingredient/citation, and graceful degradation. Even complex edge cases like ISIN resolution and non-equity instruments are covered, making the definition complete for an agent to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description greatly expands the meaning of both parameters: 'company' is enriched with CIK/ticker/LEI/FIGI details, ISIN-to-LEI mapping, non-equity coverage, and ambiguity behavior; 'value' is clarified with the entity-name-only rule and issuer-name caveat. This goes well beyond the schema's own generic 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 states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete trigger examples and distinguishes itself from downstream tools by positioning itself as the identity-lookup entry point.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear context for when to invoke this tool. It does not explicitly name excluded alternatives or state when to prefer siblings like entity_profile or compare_entities, so no exclusion guidance is provided.

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.