uselessfacts

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about external calls and cost ('BYO key — you pay Anthropic directly') and describes the return structure, which annotations don't cover.

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

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

Three sentences each add essential information: function/scoring, model/cost options, return format/use cases. No wasted words, and it's front-loaded with the primary verb.

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

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

The description compensates for the missing output schema by listing per-model fields and the combined view. It covers model selection and key requirements. Minor gaps remain: 'signals' and 'combined view' are not defined, and there's no edge-case handling.

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 4 parameters, so baseline is 3. The description goes beyond the schema by clarifying that the default model is free and that supplying `_apiKey` incurs direct costs to Anthropic, adding operational meaning.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLMs) and the output (visibility score 0-100). It distinguishes itself from siblings by focusing on measuring AI visibility rather than general Q&A or research.

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

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

It explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to add an API key. However, it doesn't mention alternatives or when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context about routing across 5,529 sources, returning pipeworx:// citation URIs, being a single fast call, and working on every tier. It doesn't disclose potential latency or failure modes, but the annotation coverage lowers the bar.

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, front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH'). Every sentence provides actionable value: usage triggers, examples, alternatives, and behavioral notes. 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?

Despite lacking an output schema, the description explains the return format (structured answer with citations), provides extensive examples, covers usage boundaries with sibling tools, and sets expectations for speed and accessibility. It is fully complete for a complex, multi-purpose lookup tool.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description provides natural language examples but doesn't add detail beyond the schema's own parameter descriptions. Baseline 3 is appropriate because the schema fully covers semantics.

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

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

The description clearly states it's a general-purpose question-answering tool that routes to 5,529 tools and returns structured answers with citations. It explicitly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific needs.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with concrete examples of alternatives. Includes trigger phrases and example queries, leaving no ambiguity about when to select 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?

Discloses the experimental nature, including that no candidate is currently active and the tool matches ask_pipeworx exactly. It also clarifies that it falls back to nothing and is a full working router, adding meaningful behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). 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 three sentences but packs significant information: beta status, identical functionality, current state, usage guidance, and comparison behavior. While the second sentence is long, every clause earns its place and the key point about usage is front-loaded.

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

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

For a beta variant of an existing tool, the description covers all necessary context: what it is, why it exists, when it's currently safe to use, and how it behaves. It references ask_pipeworx for the response shape and arguments, which is sufficient given the sibling tool exists. No output schema is present, but the shared response shape covers this.

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

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

The input schema provides full documentation for all 6 parameters (question and 5 aliases) with 100% coverage. The description adds no parameter-level details beyond what the schema provides, so it stays at the baseline.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and response shape. It distinguishes itself from the sibling tool by its experimental routing improvements, making its purpose unambiguous.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the alternative (the stable router) and explains that results are compared to decide merges, giving clear context for choosing this beta over ask_pipeworx.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the grounding mechanism, refusal_reason enum, return fields, and the extra LLM call cost. It also explains that answers are extracted solely from tool results, ensuring the agent understands the non-hallucinatory behavior. No contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the core value ('Hallucination-resistant answer mode') and then methodically explaining behavior, return format, refusal reasons, and usage guidance. It is longer than the calibration examples but every sentence carries meaningful content, so it does not feel 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 high-stakes tool with no output schema, the description fully covers what the agent needs: return shape, refusal behavior, use cases, alternatives, and cost impact. It is complete enough for safe invocation and appropriate for the complexity.

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

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

Schema description coverage is 100%, with question and all aliases documented in the input schema. The description adds context about how the question is used (routing, filling arguments) but doesn't provide additional parameter-level 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 uses a specific verb ('EXTRACTS') and resource ('answer using ONLY what the tool result contains'), clearly distinguishing it from sibling ask_pipeworx by emphasizing hallucination resistance and explicit refusal behavior. It names the exact response shape and refusal reasons, leaving no ambiguity about its purpose.

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

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

The description explicitly states when to use ('whenever an answer will be quoted, cited, or acted on... must not invent facts'), when not to use (prefer ask_pipeworx for casual lookups), and provides a cost-based tradeoff ('Costs one extra LLM call'). This gives clear guidance and names the alternative tool directly.

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

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

The description richly discloses behaviors beyond annotations: parallel fan-out, response shapes, resolver contract with match confidence, safety short-circuit for low-confidence matches, status for closed markets, illiquidity warnings, and cancellation-rule parsing. It also explains news fallback behavior with retry details. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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

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

The description is long but heavily structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the main purpose. Every section contributes necessary operational details, though some sentences could be tightened. It feels appropriately sized for a complex fan-out 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 compensates by thoroughly detailing response shapes, resolver contract, parent-event extractor, news fallback fields, safety/blocking behavior, and resolution-rule risk. It covers edge cases like low-confidence matches, closed markets, and wide spreads. 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?

Input schema coverage is 100%, providing baseline 3. The description adds value by giving concrete examples of valid market inputs (slug, URL, question text), explaining quick/thorough depth with fan-out examples, and elaborating on include_raw's trade-off between response size and detail. This exceeds schema fundamentals.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and the verb (research), and distinguishes from siblings by mentioning fan-out to category-specific data packs and market-vs-model comparison. The classifier list further defines scope.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear context for when to use the tool but does not explicitly mention when not to use alternatives. This aligns with a clear context but no exclusion.

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), the description discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), specific metrics pulled, handling of off-calendar fiscal years, sorting by primary metric, and the inclusion of citation URIs. This is rich behavioral context that complements the annotations without contradiction.

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

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

The description is dense, front-loaded with trigger phrases, and every sentence adds value. The all-caps emphasis is a bit noisy but not excessive. It packs a lot of information (data source, metrics, sorting, citation URIs) into a single paragraph without redundancy, though it could be slightly more structured.

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

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

Despite the absence of an output schema, the description adequately explains the return format (paired data + citation URIs), sorting behavior, and type-specific data origins. It also covers edge cases like off-calendar fiscal years, making it complete for the agent to anticipate results and guide user expectations.

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

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

The schema already describes both parameters with 100% coverage, but the description adds important semantics: explaining how 'type' determines the data source and metrics, and giving examples for 'values' (tickers vs. drug names). It also notes edge case handling (off-calendar fiscal years) that 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 description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific verbs like 'compare' and trigger phrases. It distinguishes itself from sequential lookups by saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' making the purpose unambiguous.

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

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

Explicit guidance is given: use this tool when comparing entities and prefer it over sequential lookups, noting it 'Replaces 8–15 sequential lookups.' This tells the agent when to choose this tool over alternatives, though it doesn't name a specific sibling tool.

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

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

The description adds substantial behavioral context beyond annotations: explains decomposition, parallel routing, the gaps[] field ('never invented'), contradictions[] for standard/thorough, semantic excerpting ('not head-truncated'), timing expectations (15-60s, up to 90s), and citation URI fetchability. No contradiction with readOnlyHint=true or openWorldHint=true.

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 dense; every sentence carries value, covering auth, scope, alternatives, output format, caveats, and timing. It is front-loaded with the account requirement and key differentiators. Slightly verbose with parentheticals, but no filler.

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

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

Given there is no output schema, the description thoroughly explains the return value (findings packet with verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], and timing. It also covers prerequisites (account), limitations (breaking news), and fallback behavior, making the tool behavior nearly fully specified.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds extra meaning beyond the schema by elaborating the depth options ('quick=3 (single hop), standard=5... thorough=8 (paid)...') and giving examples of suitable question types ('compare X and Y's regulatory + financial exposure'). It also clarifies that broad/multi-part questions are appropriate.

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

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

The description states a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx by noting 'this is NOT open-web search' and 'For a single lookup use 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?

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx (one LLM call, not many). For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also gives a clear fallback if not signed in: 'If you are not signed in, use ask_pipeworx instead.'

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: returns top-N tools with names, descriptions, full input schemas, and curated examples, and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with purpose and usage. The long list of domains is somewhat dense but serves to clarify scope. Each sentence contributes value, though the enumeration could be trimmed without losing core meaning.

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

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

Given the tool's role as a discovery mechanism and the absence of an output schema, the description is remarkably complete. It covers purpose, when to use, return format, and integration (no second lookup). The annotations cover safety, and the schema covers parameters, 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?

Schema description coverage is 100%, with each parameter including query aliases and limit default/max. The description reinforces that 'query' is a natural language description and mentions examples, but adds little beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task' and lists many specific domains (SEC filings, FDA drugs, etc.). It distinguishes itself from sibling tools by being the meta-discovery tool that returns relevant tool schemas, not a specific data-lookup tool.

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This clearly indicates when to use this tool versus calling specific tools directly.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: parallel fan-out across multiple APIs, specifics on each returned data section, the USPTO PatentsView API sunset with soft-fail behavior, and the GDELT→GNews fallback chain. This is exactly the kind of runtime behavior an agent needs to anticipate.

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 well front-loaded with example phrases and the core value proposition. It communicates a complex multi-faceted tool without wasted words. Slightly long but every sentence carries distinct information, so it earns a 4.

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 enumerates six return categories with concrete details: recent_filings count and URI scheme, fundamentals fields, patents source status, news fallback chain, and LEI source. This is highly complete for a tool this complex.

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

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

Schema covers 100% of parameters with explanatory descriptions for both type and value. The description reinforces the ticker/CIK format and name restriction, but does not add meaning beyond the schema. Baseline 3 is appropriate given full schema coverage.

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

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

The description opens with concrete example queries and a clear definition: 'full cross-source profile of a US public company in ONE parallel call.' It lists the specific data sources and return fields, making the tool's purpose unmistakable. It also distinguishes from sibling tools by stating that names are not supported and to use resolve_entity 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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clearly states when not to use it (for names) and directs users to resolve_entity as the alternative. This goes beyond general context into actionable selection rules.

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 convey destructiveHint=true and idempotentHint=true, so the description's job is lighter. It adds context about what is deleted (previously stored memory) and a typical use case (clearing sensitive data), but does not disclose other behavioral traits like irreversibility or effects on related data. This is adequate but not rich.

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, each earning its place: purpose, usage scenarios, and sibling pairing. It is front-loaded with the main action, uses no filler, and remains compact while covering key guidance.

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 delete tool with strong annotations (destructive, idempotent) and 100% schema coverage, the description is nearly complete. It explains what, when, and related tools. It could mention that deletion is permanent or what happens if the key does not exist, but those gaps are minor given the simple scope.

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

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

The input schema covers the only parameter 'key' with 'Memory key to delete' at 100% coverage. The description merely says 'by key' without adding syntax, constraints, or examples beyond the schema. Baseline of 3 applies because the schema already documents the parameter sufficiently.

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: 'Delete a previously stored memory by key.' It clearly differentiates the tool from siblings like 'remember' and 'recall' by framing it as the deletion counterpart and explicitly pairing with 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 when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, though it does not explicitly state when not to use or name alternatives in a contrastive way.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description adds valuable detail by explaining the process: fetches the page, extracts key elements, and emits markdown. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences plus a tight 'Useful for:' list. Every sentence adds value, and the primary purpose is stated up front. No redundancy or filler.

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

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

Despite no output schema, the description fully explains the return value ('single text blob'), the process, and typical use cases. Combined with strong annotations and full schema coverage, this description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so both parameters are already well-documented. The description does not add meaningful parameter-specific details beyond what the schema provides, but it does reinforce the 'any URL' flexibility. Baseline of 3 is appropriate.

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

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

The description is precise: 'Generate a production-ready llms.txt file for any URL' clearly states the verb, resource, and scope. It also differentiates from sibling tools by mentioning AI crawlers and the output format, making its unique function unmistakable.

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

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

The 'Useful for:' list provides concrete scenarios (client site indexing, own project, competitor audit) that indicate when to use the tool. It lacks explicit exclusions or alternative tool names, but the context is clear enough to guide selection.

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

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

Annotations already declare read-only and non-destructive, but the description adds significant context beyond that: it is scoped to the caller, returns a detailed list of fields, and by default only returns active subscriptions. This enriches the agent's understanding of behavior beyond structured data.

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

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

Two concise sentences: the first states purpose and return fields, the second gives usage guidance. No redundant information, every sentence earns its place.

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

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

For a simple list tool with one optional parameter, the description is fully complete. It enumerates return fields (no output schema needed), states scope, and annotations cover side effects. 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 sole parameter, include_inactive, has a clear description in the schema (100% coverage). The overall description does not add extra meaning to the parameter, but the schema already covers it adequately, so the baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, using the specific verb 'List' and resource 'subscriptions'. It distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on reading existing subscriptions.

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

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

It explicitly provides when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel'. This gives clear context and implies alternatives (subscribe/unsubscribe) without needing to name them.

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 non-read-only and non-idempotent behavior, and the description adds valuable context: the claim_token flow, rate limit (5/day), that it's free and doesn't count against quota, and that the team reads digests daily. 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 earns its place—each adds a distinct, useful guideline (when to use, when not to, token flow, rate limits, privacy note). It is front-loaded with the core purpose and then expands logically.

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

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

For a 4-parameter tool with nested objects and no output schema, the description covers the full workflow: how to file, what happens without an account, how to read the reply, restrictions, and what information to include. It leaves no practical questions unanswered.

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

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

Schema description coverage is 100%, and each parameter has a detailed description (type enum, context object, message constraints, claim_token usage). The description reinforces the claim_token flow but does not add significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It explicitly distinguishes itself from tools of other MCP servers, making it easy to differentiate from siblings.

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

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

Provides explicit when-to-use instructions for each feedback type, and a clear exclusion: do not report issues for tools from other MCP servers. Also gives guidance on what to include (tool names/packs) and what not to include (end-user prompts).

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

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

The description goes well beyond the annotations by disclosing the data source ('derived from CF analytics-engine'), privacy ('no PII'), and the caching behavior ('Cached 5min-1h'). These traits inform the agent about potential staleness and data provenance, adding real value beyond the readOnlyHint and 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 concise and front-loaded with the core purpose, then lists use cases, then adds technical details. Every sentence contributes value, and the structure is easy to scan, making it exemplary for a tool description.

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

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

For a simple one-parameter read-only tool, the description covers the input, output nature (top tools, top packs, total call volume), and relevant behavioral nuances. It doesn't specify the exact output schema, but given no output schema is provided, the description's outline of return content is sufficient for an agent to understand 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?

The schema already fully describes the single parameter with enum values and a semantic distinction between windows ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description only repeats the window enumeration without adding further meaning, so it does not improve on the high schema coverage baseline.

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

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

The description clearly states a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It distinguishes itself from siblings by framing the tool as an aggregate signal of what other AI agents are calling, which is unique among the listed tools.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming a canonical tool, and aligning with agent needs. However, it does not explicitly state when not to use the tool or name alternatives, so it stops short of full exclusion 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 annotations (readOnlyHint=true, destructiveHint=false) already indicate safety, but the description adds substantial behavioral context: how monotonicity/partition checks work, the Jaccard similarity threshold, placeholder filters, and the fill-check pricing against live CLOB depth. It clearly explains what happens when signals are not realizable ('do not trade it'). This is exemplary disclosure of complex behavior.

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

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

The description is long but justifiably so given the tool's complexity. It is well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with a clear first sentence. Every sentence provides meaningful information; while it could be trimmed slightly, the density of valuable content earns a high 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?

With no output schema, the description fully explains the response structure: opportunities[] fields and partition_check object in event mode. It also covers edge cases (low similarity, placeholder fractions, thin legs) and explicitly states the realizable edge condition. For a complex tool, this is a thorough and complete description.

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

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

Schema coverage is 100%, but the description enriches meaning far beyond the schema's field descriptions. It explains `event` with example slugs and full behavior (walks child markets, performs ordering checks and partition check), and `topic` with seed examples and the cross-event flattening process. The description adds value that the schema alone would not 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 uses a specific verb + resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings by explaining the three invocation modes (no args, event, topic) and what each does. This goes well beyond a vague purpose and uniquely identifies the tool's niche.

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

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

The description provides explicit usage guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' and even directs custom sizing to polymarket_fill_risk. It does not explicitly mention alternatives like polymarket_edges or when NOT to use this tool, but the context is clear and the mode distinction is strong.

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

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

The description goes far beyond the annotations by disclosing caching behavior ('Cached 1h at the KV level'), diagnostics (_diagnostics with funnel counters), Kelly caps, slippage handling, 24h-move warnings, and placeholder-slug filters. These are not captured in the structured fields and give an agent deep insight into the tool's behavior.

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

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

The description is long but well-structured: it leads with a clear purpose, then systematically covers model families, response format, knobs, and caching. Every sentence adds value, and the structure makes the density acceptable. It is not as tight as a two-sentence description but fits the complexity of the 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?

Although there is no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics), caveats (edge may already be in price), and behavioral notes (Fed signal unreliability). For a tool with 9 optional parameters and no required fields, this is a complete picture for a selecting 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?

Input schema has 100% coverage with parameter descriptions, so the baseline is 3. The description adds extra meaning by explaining the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and how they affect output, as well as interpreting edge_pp_net and kelly_fraction. This is above baseline but not maximal since the schema already defines each parameter.

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

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

The description clearly states a specific verb-resource-scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also describes the intended use case ('what should I bet on today') and distinguishes via model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT).

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

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

Provides explicit use case and context: 'agents discover opportunities without paging hundreds of markets.' It also gives exclusions, e.g., Fed bets are separated into fed_candidates and excluded from ranking due to unreliable signal. However, it does not name alternative sibling tools explicitly, so it stops short of full when-to-use 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?

The description goes well beyond the annotations, which only declare read-only, open-world, idempotent, and non-destructive. It discloses data gaps ('snapshots are written when polymarket_edges runs on a cache-miss'), historical limits ('60-day snapshot TTL'), and computational methodology ('decay numbers come from daily closes of edge_pp_net (net of default slippage), not intraday'). It also explains the signed meaning of edge_pp_net, providing significant behavioral insight.

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 fairly long but every section earns its place: purpose, argument recap, detailed response format, and data limitations. It is front-loaded with the core purpose and then systematically explains the output. Slightly dense, but well-organized and not verbose.

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

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

Given the tool's complexity (time-series edge tracking with computed trends and decay) and the absence of an output schema, the description fully compensates by detailing the response structure (tracked[], expired[], snapshot_dates[]), the meaning of each field, and the inherent data limitations. It provides a complete mental model of what the tool returns and how to interpret it.

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

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

Schema coverage is 100% with descriptions for both parameters. The description repeats the defaults and adds minimal context like the term 'snapshot family' for window, but this is not substantially beyond what the schema already provides. It does not clarify parameter formatting or edge cases beyond the schema, so it meets the baseline but does not elevate it.

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 specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a precise question about edge longevity and decay. It distinguishes itself from the sibling polymarket_edges by focusing on time-series persistence rather than just current edges, explicitly contrasting fresh versus old wide edges.

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

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

The description provides strong usage context: it explains what question the tool answers ('how long has this edge existed and is it shrinking?') and gives a practical example of when it should be used (comparing a fresh wide edge to a 3-week-old one). It does not explicitly name alternative tools like 'use polymarket_edges for current edges,' but the context implies this distinction clearly enough.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations. It discloses that the tool 'walks the ladder,' returns a verdict (clean|degraded|cannot_fill), and – crucially – warns that partial basket fills convert an arb into an unhedged directional position. These are non-obvious behavioral traits that an agent needs to know before acting. 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?

Although the description is lengthy, it is front-loaded with the core purpose and then structured logically into single-market vs. basket modes. Every sentence adds distinct value: parameter semantics, return fields, verdict meaning, risk warning, and usage timing. No filler or redundancy; the density is necessary for a tool with two modes and complex outputs.

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

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

With no output schema, the description takes on the full burden of explaining return values, which it does thoroughly – listing top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers parameter interplay and edge-case risk, making the tool's behavior fully understood without an output schema.

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

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

Schema description coverage is 100%, and the parameter descriptions in the schema already fully explain each parameter's meaning in both modes. The tool description largely repeats this information (e.g., side modes, size_usd interpretation) rather than adding significantly new semantics. It provides organizational context but no new per-parameter detail beyond the schema.

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

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

The description opens with a clear, specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinctly separates single-market and basket modes, and the tool is clearly differentiated from sibling tools like polymarket_arbitrage and polymarket_edges, which are about finding or listing edges, not verifying capturability.

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

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

The description provides explicit usage instruction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why this timing is critical, citing thin books, partial-fill risk, and the dominant loss mode in arb-bot P&L, which gives clear context for when this tool is the right alternative.

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

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

Annotations already indicate read-only and non-destructive behavior, but the description adds rich behavioral context: it explains compatibility warnings (two specific cases), temporal alignment, and skipped cross-type/subtype counters. It also reveals the tool's conservative behavior (spreads are rarer than shortcuts suggest). This significantly exceeds the minimal expectations given 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 with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries information and there is no fluff or redundancy. It is front-loaded with the core purpose and then adds operational details, which is appropriate for a complex cross-venue 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?

Without an output schema, the description fully compensates by enumerating response fields: leg-by-leg prices, matched spreads in percentage points, compatibility warning, temporal alignment, and skip counters. Given the tool's complexity and the potential for nuanced mismatches, this description is exceptionally complete.

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

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

Schema coverage is 100% and each parameter has a description, so baseline is 3. The description adds value by explaining how the parameters interact (topic shortcuts vs overrides, custom pairings, and precedence). It also lists the exact topic enum values and clarifies output behavior for explicit vs mapped modes.

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: calculating cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like 'polymarket_arbitrage' by emphasizing the venue pair and its safety/compatibility analysis. The verb 'spread' and specific resource make the purpose unambiguous.

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

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

The description explicitly details two usage modes: pre-mapped 'topic' shortcuts and explicit ticker/slug pairings. It also warns when the tool is likely to return a compatibility warning and clarifies that pre-mapped topics are not necessarily tradeable. This provides strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context by naming the external API source and detailing the returned fields ('fact text with its id, the attributed source name, source URL, and a permalink'). It also specifies the language ('in English'). No contradictions found, and the description complements the annotations without over-explaining.

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 long, with the main action and source in the first sentence and return details and use cases in the second. Every word adds value, and the structure is clear and front-loaded. 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 zero-parameter tool with a rich output schema, the description covers purpose, source, return content, and intended use cases. The annotations cover safety (read-only, non-destructive, idempotent). There is no missing information needed to decide whether to invoke this tool. It is fully complete.

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

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

The tool has zero parameters, so the input schema is complete and the description cannot add further parameter semantics. Per the rubric, a baseline of 4 applies when there are no parameters, as no additional explanation is needed. The description appropriately focuses on the output and use cases.

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: 'Return one random trivia fact in English from the Useless Facts API at uselessfacts.jsph.pl.' It specifies the resource (Useless Facts API), the verb (return), and the randomness (random trivia fact). This distinguishes it from sibling tools like today_fact, which likely returns a fact for a specific day.

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

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

The description provides clear use cases: 'Use it for an amusing filler fact, an icebreaker line, or a fact-of-the-moment prompt.' This gives context for when to invoke the tool, though it does not explicitly mention alternatives or when not to use it. That is acceptable for a simple, low-risk tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)' and the behavior of listing all keys when the key argument is omitted. This goes beyond annotations but isn't exhaustive.

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 action ('Retrieve a value...'), and includes concrete examples. Every sentence adds value: the first defines behavior, the second gives usage context, and the third explains scoping and pairing. No wasted words.

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

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

For a simple tool with one optional parameter, no output schema, and good annotations, the description is complete. It covers purpose, usage, scoping, and related tools, making the tool self-explanatory 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 describes the single 'key' parameter with 100% coverage, including '(omit to list all keys)'. The description repeats this same instruction ('or list all saved keys (omit the key argument)') without adding new parameter meaning, so the baseline of 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?

The description uses a specific verb+resource construction: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes the tool from siblings by naming 'remember' and 'forget' and providing concrete use cases like 'the user's target ticker, an address, prior research notes.'

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

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

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also gives guidance on pairing with siblings: 'Pair with remember to save, forget to delete.' However, it doesn't explicitly mention exclusions or when not to use it, so a 4 is appropriate.

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

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

With annotations already providing readOnlyHint and idempotentHint, the description adds valuable context about the mark_read side effect, the persisted nature of the feed, and the contents of each returned event. It does not contradict annotations, though it could further disclose rate limits or auth requirements.

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

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

The description is concise and front-loaded, with no wasted words. It covers the tool's main purpose, return payload, filtering, mark_read behavior, polling suitability, and an alternative endpoint in a compact paragraph.

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 describes the return payload (source, citation_uri, raw event payload). It also covers filtering, mark_read, and the alternative HTTP endpoint, making the tool's behavior clear for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the description doesn't need to explain parameter existence. It adds meaning by providing an example for 'type' (sec_8k), confirming 'since' format, and explaining the behavioral consequence of mark_read (next call shows only newer events). This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns the most recent alerts, distinguishing it from sibling tools like recent_changes. It specifically identifies the resource (persisted feed) and the action (pull/return), leaving no ambiguity about the tool's function.

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

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

The description explains when to use the tool (polling) and offers an alternative access method for scripts/dashboards via a direct HTTP endpoint. It also provides context on filtering and mark_read semantics, but does not explicitly mention alternative sibling tools or when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral detail: fan-out to SEC EDGAR, GDELT preferred with GNews fallback on rate-limit/5xx, USPTO soft-fail due to API sunset, and the exact return shape (changes[] grouped by source, total_changes, citation URIs). 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 dense but well-structured: trigger phrases first, then source fan-out details, parameter syntax, return summary, and alternative tool. Every sentence earns its place, and the opening examples make the purpose instantly scannable.

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

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

Given there is no output schema, the description compensates by stating the exact return format (structured changes[], total_changes, pipeworx:// URIs) and covering edge cases like GDELT rate limits, GNews fallback, and PatentsView sun-setting. It also names the right sibling for static profiles, making the tool completely usable on description alone.

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

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

Schema coverage is 100% and each parameter already has a description, but the tool description goes further by explaining `since` formats (ISO date and relative shorthand), giving examples, and recommending '30d' or '1m' for typical monitoring. This adds meaningful 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 opens with concrete natural-language triggers and states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly identifies the specific resource (company change feed across SEC/GDELT/GNews/USPTO) and differentiates itself from the sibling tool entity_profile.

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

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

The description gives explicit when-to-use examples ('What's new with X', 'latest on Y', 'what happened to Z') and an explicit exclusion: 'Use entity_profile instead when you want the static profile' regardless of window. It also clarifies fallback behavior for news sources, leaving no ambiguity about invocation context.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond this: key-value storage scoped by identifier, persistence differences for authenticated vs. anonymous sessions (24-hour retention), and the ability to pair with recall/forget. 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?

Every sentence earns its place: purpose, usage trigger, storage semantics, persistence behavior, and companion tools. Front-loaded with the core action, compact enough to read quickly, 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 2-param tool with no output schema, the description fully covers what, why, when, where, and how long data persists. No important gaps such as missing prerequisites, return values, or edge cases.

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

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

Schema coverage is 100% and both parameters are described with examples. The description reinforces the key-value model ('Stored as a key-value pair') and adds scoping context, giving the agent a better sense of how to select keys/values. However, it doesn't add syntax or format details beyond what the schema provides, so a slight edge over 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 clear verb+resource: 'Save data the agent will need to reuse later', specifying both the action and the resource. It explicitly names sibling tools (recall, forget) as companions, distinguishing this tool's purpose from 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?

Provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference, research subject). It also states alternatives: 'Pair with recall to retrieve later, forget to delete,' clarifying when to use each sibling tool.

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

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

Beyond annotations, the description discloses graceful degradation (LEI/FIGI enrichment falls back to EDGAR), explicit unresolved identifiers, source-labeling of each identifier, and the cascading internal lookups. These are critical behavioral details not captured by 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 front-loaded with purpose. It interleaves examples, supported types, and behavioral notes. Some redundancy exists (e.g., supported types partially repeat schema), but overall it's efficiently packed with valuable info.

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, so the description carries the burden of explaining return behavior. It covers unresolved identifiers, source labels, and graceful degradation, providing a clear mental model. It doesn't specify exact output structure, but given the tool's scope, it's adequately complete.

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

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

Schema coverage is 100% and already documents both parameters, but the description adds examples and clarifies semantics (e.g., ticker vs CIK vs name, brand vs generic), plus details about what happens when values can't be resolved, which enriches 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 starts with concrete example queries and clearly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from siblings by focusing on ID resolution and naming specific identifiers (CIK, LEI, FIGI, RxCUI).

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' It explains the tool consolidates multiple lookups. However, it doesn't explicitly contrast with alternatives (e.g., when to use entity_profile instead), so it's strong but not fully exhaustive.

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 readOnly/openWorld/idempotent, and the description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. This gives behavioral context beyond the annotations, though not exhaustive.

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

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

Three sentences, front-loaded with the core purpose, then method, use case, and output. No wasted words.

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

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

Despite no output schema, the description states the return structure. It covers purpose, usage, and behavior sufficiently for the tool's complexity, with rich annotations and schema.

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

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

Schema covers all 4 parameters at 100%, and the description adds minimal extra meaning beyond confirming entities are brand + competitors. 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 explicitly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. It distinguishes itself from siblings by mentioning it ranks by score and identifies most/least recognized, and references ai_visibility_check, making its unique value clear.

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 includes 'Useful for competitive AI-marketing audits' and gives an example question, which clearly indicates when to use this tool. It implies single-entity checks would use ai_visibility_check directly, but doesn't explicitly state exclusions, so a 4.

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, but the description adds valuable behavioral context: it fans out across multiple services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and 'sources_failed' reports timeouts. This exceeds the annotation baseline with actionable detail.

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 is information-rich with clear flow: what it does, when to use, what it returns, ecosystem limits, and failure behavior. It earns its length, though a slight structure improvement would make it more scannable.

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

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

Given the tool's complexity and lack of output schema, the description covers return fields, per-source behavior, latency expectations, and limitations. The agent has enough context to invoke correctly and handle edge cases like timeouts.

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

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

Schema coverage is 100% for both parameters, so the schema documents package and version defaults. The description adds no new parameter-specific semantics, but it reinforces the npm scope and version default. Baseline 3 is appropriate because 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?

The description uses a specific verb-resource combination ('Composite ... check') and clearly scopes to npm packages, distinguishing itself from sibling tools by naming deps.dev and bundlephobia integrations. It answers 'what does this tool do' with concrete examples.

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

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

Explicitly states when to use ('whenever an agent asks is X safe / popular / small') and gives alternative guidance for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This is clear when-to-use and when-not-to-use.

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

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

Beyond the readOnly and idempotent annotations, the description discloses concrete behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, the 200K char cap with truncation flagging, and that returned passages include offsets and similarity scores.

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?

Five dense sentences, each adding unique value: purpose, usage, pairing, technical mechanism, and limits. The description is front-loaded with the core action and contains no filler.

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

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

Even without an output schema, the description fully explains what the caller receives (passages, character offsets, similarity scores), the input constraints, and processing behavior. This gives an agent enough context to use the tool correctly and understand edge cases like truncation.

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 detailed descriptions and examples for all three parameters, so the description adds little new parameter-specific meaning. It reinforces the intended use of 'text' as already-fetched content but does not go substantially beyond the schema.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which clearly names the verb, resource, and scope. It also distinguishes itself from sibling tools like ask_pipeworx_grounded by emphasizing it works on already-pulled text rather than the whole document.

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

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

The description explicitly states when to use this tool: when the record is too large to fit in the prompt, and it saves context by returning only relevant passages. It mentions pairing with ask_pipeworx_grounded but does not provide a full 'when-not-to-use' list, though the usage context is clear.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: subscriptions are not persisted for anonymous/BYO users, the feed is always on and accessible via recent_alerts or a public URL, and there are prerequisites like verified phone and a 10/day SMS cap. It does not fully clarify idempotency semantics (whether resubscribing returns the same ID), but this is not a direct contradiction and the description adds substantial 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 information-dense and mostly well-organized, but it is long and partially redundant with the schema. For example, it repeats parameter examples that already appear in the schema's delivery and type descriptions. The front-loaded purpose statement is good, but the overall length makes it less concise than it could 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?

Given the tool's moderate complexity (3 params, nested objects, 5 types, 3 channels), the description covers the core aspects: purpose, return value, account requirement, three subscription types, and the feed/email/SMS channels. The webhook channel and two remaining types are documented in the schema, so the description does not need to repeat everything. It is complete enough for an agent to use alongside the schema.

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% parameter coverage and already details all subscription types and delivery parameters. The description repeats some examples (e.g., polymarket_edge topic:fed, fred_series series_id:UNRATE) but does not add new meaning beyond the schema. It also omits two of the five enum types (patent_grant, clinical_trial), though those are well-described in the schema. Baseline of 3 is appropriate.

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

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

The first sentence states the tool's function explicitly: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. Supporting details about subscription types and delivery channels reinforce the purpose.

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

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

The description provides concrete guidance on prerequisites ('Requires a Pipeworx OAuth account'), and explains when to use each supported type with examples (e.g., sec_8k items:["5.02"] for officer changes). It also clarifies delivery channels and requirements like phone verification and SMS cap. It does not explicitly mention alternatives like list_subscriptions, but the context strongly implies that this tool is for creating new 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the actual behavior: it returns categorized example questions drawn from the live catalog, each paired with the exact tool and argument shape. This gives the agent a concrete expectation of the output and how the tool behaves. No contradiction with annotations.

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

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

The description is a single dense paragraph but well-structured: it opens with natural language queries, states the core function, lists categories, explains the return value, and gives usage instructions. Every sentence contributes useful information, though slightly verbose with the full category list and examples.

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

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

Given the tool has one optional parameter and no output schema, the description covers everything needed: purpose, usage, output content, and when to use it. It even names the meta-tools the agent can learn about. The description is complete and self-sufficient.

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

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

The schema already describes the `topic` parameter with examples, and the description adds meaning by explaining how to use it ('pass topic to focus') and providing more examples ('finance', 'pharma', 'betting'). This goes beyond the schema's static list, so the description adds value.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. The verb 'suggest_questions' and the title 'What Can I Ask Pipeworx?' align perfectly, and it explicitly distinguishes itself from sibling tools by saying 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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: it instructs the agent to use this tool FIRST when unfamiliar with Pipeworx or to learn how to call meta-tools. It also provides conditional usage: 'Call with no arguments for the full spread, or pass topic to focus.' This clearly defines when to use the tool and how to tailor the call.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds minimal behavioral context (that the fact is 'useless' and specific to 'today') but does not disclose any additional behavioral traits beyond what annotations imply.

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, focused sentence with zero wasted words. It is appropriately sized for the simplicity of the tool and front-loads the core purpose.

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

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

For a no-parameter tool with comprehensive annotations and a likely simple output, this description is mostly sufficient. A brief note differentiating it from the sibling 'random_fact' would enhance completeness, but it is not essential for basic understanding.

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

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

There are no parameters, so schema coverage is trivially 100%. The description does not need to explain parameters, and the baseline for 0 params is 4, which is appropriate here.

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

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

The description uses the specific verb 'Get' and identifies the resource as 'today's useless fact,' making the tool's function clear. However, it does not explicitly distinguish from the sibling tool 'random_fact,' which is a minor gap given the sibling list.

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 no guidance on when to use this tool versus alternatives. It does not mention 'random_fact' or any other context for choosing this tool, so an agent receives no usage direction.

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 two important behavioral traits beyond the annotations: ownership enforcement (only own subscriptions) and the soft-delete mechanism (deactivation, not deletion, preserving historical events). This adds context that the annotations do not provide, enhancing the agent's understanding of side effects.

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

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

The description is concise, consisting of two sentences. The first sentence states the core action, and the second adds necessary behavioral context without any wasted words.

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

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

For a simple tool with one parameter, clear annotations, and no output schema, the description covers all essential aspects: purpose, ownership, and side effects. It provides sufficient context for an AI 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?

The schema already describes the single parameter 'id' as a subscription id returned by subscribe, so the description adds no additional parameter semantics. With 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription'), clearly stating the tool's action. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation and 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 the tool (to cancel a subscription) and provides an ownership constraint (only your own). However, it does not explicitly mention alternatives or when-not-to-use scenarios, though the context is clear.

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

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

Beyond the readOnly/idempotent annotations, the description reveals substantial behavior: the dual-pipeline architecture, exact percent-delta math for financial claims, and the nuanced meaning of each verdict type including unsupported vs. could_not_verify. It also explains the error object and why callers must not interpret could_not_verify as a refutation—context not derivable from 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?

Despite being lengthy, every sentence earns its place: example queries, routing logic, return structure, caller warning, and efficiency rationale. The description front-loads the core purpose with examples and uses a clear progression from usage to behavior to return semantics, making it dense but 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?

There is no output schema, so the description fully compensates by specifying exactly what the tool returns (verdict, actual value with citation, reasoning) and explaining the two 'non-answer' verdicts. It covers when to use, how it behaves, parameter nuances, and failure modes—complete for a 2-parameter tool.

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

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

Even though the schema already fully documents both parameters, the description adds real semantic value: it explains that tolerance_pct overrides claim wording, recommends 1–2 for hallucination detection, and notes the default cap of 5. The claim parameter is given realistic examples that clarify expected format far beyond the schema description.

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

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

The description explicitly states the tool performs natural-language claim verification against authoritative sources, with concrete example phrasings. It clearly distinguishes the two processing paths (structured SEC EDGAR + XBRL for company-financial claims, grounded pipeline for all others) and lists the verdict types, making the purpose unmistakable and distinct from sibling tools like deep_research or 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?

Gives an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides detailed routing rules for financial vs. non-financial claims and warns that 'could_not_verify' must not be treated as evidence—critical guidance for correct use.

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