universities

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

Annotations already declare read-only, idempotent, and non-destructive behavior, lowering the bar. The description adds meaningful context about the default model, the need for an API key for Anthropic, cost implications, and the return structure, which goes beyond the annotations.

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

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

The description is three tightly packed sentences with no filler, front-loading the main purpose, then key options, and use cases. 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?

Even though there is no output schema, the description outlines the return shape (per-model object plus a combined view) and covers key parameters and use cases. It is reasonably complete, though it doesn't explain the scoring methodology 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%, so the baseline is 3. The description enhances parameter understanding by explaining the default model for the models parameter and clarifying that _apiKey is only needed when Anthropic is included, adding value beyond the schema.

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

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

The description clearly states the tool probes one or more LLMs for knowledge about a business and scores visibility 0-100 per model. It uses a specific verb and resource, and distinguishes itself from siblings by emphasizing the visibility scoring and multi-model probing.

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

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

The description provides clear usage context by listing scenarios like AI-marketing audits, pre-launch brand checks, and competitive monitoring. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context: it works on every tier, makes one fast call, routes to other tools, and for breaking news it routes to live news feeds. It also indirectly warns that this version may not be hallucination-resistant (by contrasting with ask_pipeworx_grounded). 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 longer than minimal but every sentence adds distinct value: preference, mechanism, trigger phrases, examples, tier setup, and alternatives. It is front-loaded with the key directive and structured logically, though slightly 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 role as a general-purpose router with many siblings, the description fully orients the agent: when to use it, when to escalate, what to expect in return, and its applicability across domains. No output schema exists, but the description adequately covers return type (structured answer with citations).

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

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

Schema coverage is 100% and the schema already thoroughly describes the 'question' parameter including aliases. The description adds only illustrative examples of questions, not additional semantic detail about parameters. Baseline 3 is appropriate since the schema carries the parameter information.

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: it routes questions to one of 5,529 tools across verified sources and returns structured answers with citation URIs. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, naming them as alternatives for specific use cases.

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 on when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when not to (for grounded answers use ask_pipeworx_grounded, for broad multi-part questions use deep_research). Includes concrete trigger phrases and examples.

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 destructiveHint, the description adds substantial context: it is an experimental edge, may enable candidate routing improvements, currently matches the stable router, and is a full working router (not a fallback). This goes well beyond the annotations and provides transparency about potential differences.

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 longer than a simple one-liner but each sentence contributes: it explains beta status, identical nature, candidate testing, current status, usage, and comparison. It is well-structured and front-loaded with the most critical information, though marginally verbose for the complexity.

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

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

The description covers the tool's role, current state, usage, and comparison mechanism. It mentions 'same response shape' as a reference to the stable router, which is helpful, but it does not explicitly describe the response format or error behavior. Since no output schema exists, a bit more detail on return values would have made it fully complete.

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

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

The input schema provides 100% coverage with aliases and a clear description for the question parameter. The description only mentions 'same arguments' and does not add any additional semantic meaning beyond what the schema already documents. Per the baseline, a score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,529 tools. It states the exact scope (same tools, arguments, response shape) and distinguishes it from the stable router by mentioning candidate routing improvements and that it currently matches ask_pipeworx exactly.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains how results are compared against the stable router. It clearly indicates when to choose this beta over the stable version, but does not explicitly contrast with ask_pipeworx_grounded or specify when not to use it.

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

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

Annotations already indicate readOnly/openWorld/idempotent, but the description adds substantive context: it discloses extra cost ('Costs one extra LLM call'), refusal mechanics with specific refusal_reason enumerate values, and the evidence/verbatim quote behavior. This goes beyond the safety profile provided by annotations.

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

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

The description is front-loaded with the purpose, then systematically covers routing, output contract, usage guidance, and cost. Each clause serves a distinct informational role; no filler or redundancy.

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

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

With no output schema, the description fully specifies the return contract: success returns {answer, evidence, confidence, source, fetched_at, refusal_reason:null}, and failure returns explicit refusal with enumerated reasons. It also covers routing scope, cost trade-off, and ideal use cases, making it self-contained for an agent.

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

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

Schema provides 100% coverage: every parameter is documented as an alias for 'question,' and the question property explains acceptance of aliases. The description adds no parameter-level semantics beyond that, so baseline 3 holds.

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 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's core function. It distinguishes from sibling 'ask_pipeworx' by emphasizing grounded extraction: 'EXTRACTS the answer using ONLY what the tool result contains.' This is a specific verb-resource-scope combination.

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

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

It explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides an exclusion: 'prefer ask_pipeworx for casual lookups,' directly addressing alternative 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?

Even though annotations declare readOnlyHint=true and idempotentHint=true, the description goes far beyond that by detailing response shapes, low-confidence short-circuit behavior, closed-market status, wide-spread warnings, cancellation-rule parsing, and rate-limit fallback mechanisms (e.g., GDELT 429s). This rich behavioral context is exactly what an agent needs.

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 headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and a front-loaded summary. Some sections, like the exhaustive fan-out examples, could be trimmed, but overall the structure makes the length manageable and useful.

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

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

For a tool with no output schema, the description is exceptionally complete. It covers response shapes, resolver match confidence, parent-event extraction, news field fallback behavior, safety short-circuits, wide-spread warnings, and resolution-rule risk. This is more than sufficient for an agent to understand the tool's behavior and 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 all parameters (market, depth, include_raw) have detailed descriptions in the input schema itself. The description adds examples of market formats and fan-out behavior but does not provide new parameter semantics beyond what the schema already documents. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by focusing on single-bet research with data fan-out, and provides concrete usage phrases like 'should I bet on X', which solidifies the tool's purpose.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X"...'), giving clear context. However, it does not mention when not to use it or explicitly name alternative sibling tools, so it falls short of a 5 but provides solid 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, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond this by revealing specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the return format (paired data + citation URIs). This rich behavioral context helps the agent anticipate outputs and limitations.

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

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

The description is dense but every sentence serves a purpose: trigger examples, usage guidance, data source specifics, and output behavior. It is appropriately front-loaded with the most critical information. While slightly long, the complexity of the tool justifies the length, and nothing feels like 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 the tool's moderate complexity (2 params, no output schema), the description covers all essential aspects: what it does, when to use it, what data it accesses, how results are sorted, and what output format to expect (paired data + citation URIs). It also quantifies the efficiency gain ('Replaces 8–15 sequential lookups'), making the tool's value proposition clear. No critical gaps remain.

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 both parameters described, providing a baseline of 3. The description adds substantial value by explaining that type='company' pulls specific financial metrics (revenue, net income, cash, long-term debt) and type='drug' pulls FAERS counts, along with concrete examples for the values parameter. This goes beyond the schema's generic descriptions.

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

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

The description opens with explicit trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger') and clearly defines the tool's core function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from sequential single-pack lookups, making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance through example queries and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' naming an alternative approach. However, it doesn't explicitly state when NOT to use this tool (e.g., for a single entity), though that is implied by its naming of the alternative for multi-entity comparisons.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds crucial behaviors: account requirements, expected latency, gap recovery in standard and thorough modes, contradictions[] output, hop fields, citation resolvability, semantic excerpting, and the 'never invented' guarantee. It enriches the agent's understanding of side effects and output quality without contradicting annotations.

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

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

The description is long but every sentence earns its place: prerequisites, exclusions, mechanism, output format, gap handling, citations, and latency. It is front-loaded with the account requirement to prevent immediate failure, and the structured prose makes the dense information navigable.

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

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

For a complex, multi-faceted research tool with no output schema, the description provides an unusually complete picture: what it returns (findings packet, gaps[], contradictions[], hop fields), how citations work, what happens for unsupported topics, depth-mode behavior, and performance expectations. This fully compensates for the missing 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 coverage is 100%, so the baseline is 3; the description adds value by explaining depth mode behavior beyond the enum descriptions (e.g., 'standard re-angles unanswered gaps', 'thorough chases the best leads') and illustrates suitable question phrasing with examples. It does not fully detail 'quick' in prose, but the schema covers it, so this is a strong 4.

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

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

The description explicitly states 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and clarifies 'this is NOT open-web search', making the tool's purpose distinct. It also differentiates from siblings by saying 'For a single lookup use ask_pipeworx' and 'prefer ask_pipeworx' for breaking news, so the agent knows exactly what deep_research is for.

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

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

Provides clear when-to-use vs alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also includes account and tier prerequisites, ensuring the agent can decide before invoking.

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

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

Adds meaningful behavioral context beyond the annotations: it describes the return format (top-N tools with names, descriptions, and full input schemas with curated examples) and that results are ready to call directly, eliminating the need for a second schema lookup. No contradiction with the readOnly/idempotent hints.

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

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

The description is front-loaded with the core purpose and includes a useful but somewhat long list of supported domains. It remains focused; each sentence adds value, but the category enumeration could be trimmed without losing critical 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?

For a tool with no output schema, the description adequately explains the return payload and the recommended usage flow ('Call this FIRST'). Combined with exhaustive schema documentation, it gives an agent enough to invoke the tool effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter-level detail beyond what the schema already provides; it only restates the query concept in prose. No additional semantic enrichment is given.

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 ('Find tools') and explains the tool's purpose as a discovery mechanism across many domains (SEC filings, FDA drugs, etc.). It clearly distinguishes itself from sibling tools by framing itself as the meta-tool for finding other tools.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context on when to invoke this tool versus simply asking for a direct answer.

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, non-destructive, idempotent, open-world behavior. The description adds meaningful behavioral context beyond that: the parallel fan-out across multiple sources, the USPTO PatentsView sunset with soft-fail behavior, and the GDELT-to-GNews fallback. No contradiction with annotations.

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

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

The description is information-dense and justifiably detailed for a multi-source tool, covering sources, return fields, failure modes, and input constraints. However, it opens with a long list of example queries rather than a crisp purpose statement, which slightly delays front-loading. Still, every section 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?

There is no output schema, so the description carries the burden of explaining return values. It does so thoroughly: CIK, company name, recent filings with URIs, fundamentals with specific metrics and sort order, patents status, news fallback, and LEI. It also documents input restrictions and the resolve_entity prerequisite. 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?

Both parameters are fully documented in the schema with examples (ticker 'AAPL', zero-padded CIK), enum constraints, and a note about unsupported names. The description repeats these constraints but does not add new semantic meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description states the tool's core purpose clearly: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs ('profile', 'research', 'brief me') and distinguishes itself from sibling tools by emphasizing holistic cross-source aggregation rather than single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear alternative for name-only inputs: 'use resolve_entity first if you only have a name.' This is 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 destructiveHint=true and idempotentHint=true, indicating a destructive, idempotent delete operation. The description adds context about clearing sensitive data, but no additional behavioral details beyond what annotations provide. No contradiction exists.

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

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

The description is two concise sentences, front-loaded with the primary action and followed by usage and pairing guidance. Every word earns its place with no redundancy or fluff.

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

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

For a simple one-parameter delete tool with solid annotations (destructive, idempotent) and no output schema, the description fully covers what, when, and how it relates to other tools. No gaps in practical information.

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

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

Schema description coverage is 100% (the 'key' property is already described as 'Memory key to delete'). The description only says 'by key,' which adds no new semantic value beyond the schema. Baseline of 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 clearly states the action ('Delete a previously stored memory by key') and distinguishes it from sibling tools by mentioning 'Pair with remember and recall.' This makes it obvious that this tool removes memories, unlike remember (store) or recall (retrieve).

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

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

It provides explicit when-to-use conditions ('when context is stale, the task is done, or you want to clear sensitive data') but does not explicitly state when not to use it or name direct alternatives beyond the pairing sentence. Still, the guidance is clear and actionable.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior. The description adds process detail ('Fetches the page, extracts title/description/key links') and output format ('single text blob ready to drop at site-root/llms.txt'), which enriches the behavioral picture beyond annotations without contradicting them.

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

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

The description is compact and front-loaded: the first sentence states the tool's core function, the second explains the mechanism, and the third lists concrete use cases. Every sentence adds useful information with 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?

Given the tool's moderate complexity, good annotations, and full schema coverage, the description covers purpose, process, output format, and use cases. It lacks explicit notes about error handling or prerequisites (e.g., URL accessibility), but this is a minor gap for such a straightforward read-only operation.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the schema already fully documents them. The description doesn't add specific parameter-level details beyond the schema, but it does contextualize the output format and the extraction process, which is marginal. This aligns with the baseline of 3 for high schema coverage.

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

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

The description uses a specific verb ('Generate'), names the exact resource ('llms.txt file'), and explains the purpose ('so AI crawlers can index the site cleanly'). It also outlines the steps and output format, making it distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides clear use cases in the 'Useful for' list (client sites, own projects, competitor audit), giving actionable context for when to select this tool. However, it doesn't explicitly mention when not to use it or name alternative sibling tools, so it's strong but not fully prescriptive.

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 hints, and the description does not contradict these. It adds useful context by specifying the scope ('caller's') and the exact return fields, which helps the agent understand what to expect without needing an output schema. No additional side-effect disclosure is needed for a simple list operation.

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

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

The description is concise: three sentences that lead with the action, then list return fields, and finally provide usage context. No word is wasted, and the structure 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 simple read-only tool with one optional parameter and no output schema, the description provides sufficient detail: it states the action, scope, return fields, and gives a practical use case. Annotations cover safety, making this contextually 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 schema description for include_inactive is complete ('Include cancelled subscriptions in the response (default false)'), covering 100% of the parameter. The tool description does not add further parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb and resource. It further distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions, and even mentions the return fields to clarify its output.

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

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

The description explicitly says to use this tool to review what you're monitoring before adding more subscriptions or to find an id to cancel. This provides clear when-to-use guidance, but it does not explicitly mention alternatives or when not to use it, 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 provide no safety profile (all hints false), so the description carries the full burden. It compensates comprehensively by disclosing rate limiting (5 per identifier per day), cost (free, doesn't count against quota), return behavior (claim_token), and post-submission workflow (digests read daily, signal affects roadmap). 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 longer than average but every sentence contributes operational insight (scope limits, filing rules, claim flow, rate limits, cost). It is front-loaded with the core purpose and organized by usage conditions, making it efficient despite its length.

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

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

Given the tool's nuanced purpose, nested parameters, and lack of an output schema, the description is thorough. It covers the complete workflow (submit, receive token, check status), including edge cases like anonymous filing, and provides enough context for the agent to invoke correctly without consulting external documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how to use claim_token ('pass it back later to read whether it was fixed') and clarifying message expectations ('don't paste the end-user's prompt'). It enhances parameter understanding without needing to compensate for gaps.

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

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

The description clearly identifies the actions of the tool: sending feedback to the Pipeworx team (bug, feature, praise). It specifies the exact target (Pipeworx connection tools) and differentiates from sibling tools like ask_pipeworx and discover_tools, stating 'ONLY for tools served by this Pipeworx connection.'

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

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

The description explicitly states when to use the tool (bug, feature/data_gap, praise), when NOT to use it (different MCP server), and provides a clear decision heuristic ('Not sure? Pipeworx tool names are the ones this connection lists'). It also explains how to check status later using the claim_token, which is actionable guidance beyond basic triggers.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses meaningful behavioral traits: it is self-aggregating, derived from an analytics engine, contains no PII, returns only (pack, tool, count), and is cached for 5min-1h depending on window. This adds real context about data provenance and freshness.

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 opens with a clear purpose sentence, lists returns and use cases, then adds essential transparency details about data source, PII, and caching. Every sentence earns its place; the bullet-like use-case list improves scannability without padding.

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 specifying what is returned (top tools, top packs, total call volume) and the data shape (pack, tool, count). It also covers caching, privacy, and the meaning of window choices, making the tool's behavior fully understandable 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 only parameter (window) is already fully described in the input schema, including its default and the semantic difference between shorter and longer windows. The tool description mentions the window values but does not add meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Returns') and names the exact resource and outputs: top tools, top packs, and total call volume over a recent window. It clearly distinguishes itself from siblings by focusing on aggregate trending data from other AI agents, not a specific lookup or research 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?

The description provides an explicit 'Useful for' list with three concrete use cases, giving clear guidance on when to invoke the tool. It does not explicitly name alternatives or say when not to use it, but the use cases provide strong contextual 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?

Beyond annotations (read-only, open-world, idempotent), the description discloses critical behavioral details: the fill check reveals that theoretical edge may not be realizable in the book, and it explicitly warns 'do not trade it' when realizable_edge_pp ≤ 0. It also exposes filters like placeholder slug removal and the ≥0.30 Jaccard similarity threshold, providing deep insight into internal decision-making.

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

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

The description is lengthy but well-structured: it opens with the core purpose, then separates sections for event mode, topic mode, semantic anchor, partition filter, response format, and fill check. Each sentence adds necessary detail for a complex tool, though some could be condensed. Overall, it's efficiently organized for its complexity.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: opportunities[] with specific fields, partition_check with its fields, and the fill check outputs. It also covers behavioral nuances like skipped_low_similarity and thin_legs. For a tool of this complexity, the description is remarkably complete.

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

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

Both parameters have schema descriptions, but the tool description massively extends their meaning. It gives concrete example slugs (e.g., 'fed-decision-may-2026') and seed questions, explains what each mode does, and even the difference between single-event and cross-event behavior. The description is a tutorial for using the parameters effectively.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the unique method (monotonicity + partition-sum) and the resource (Polymarket), distinguishing it from generic market edge tools. The three modes (trending_scan, event, topic) are explicitly spelled out, making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It even recommends event mode for a specific market and explains the cross-event mode's advantage. It also directs users to polymarket_fill_risk for custom sizing, naming an alternative tool, which fully satisfies the 'alternatives' requirement.

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 safety, so the description adds value through detailed behavioral context: output structure per segment, edge metrics, the 24h-move warning, diagnostics to explain empty segments, and caching behavior. It also discloses nuances like Fed bets being excluded from ranking and partition arbs returning kelly_fraction_half=0 at the parent level, which agents need to interpret results correctly.

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

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

The description is front-loaded with purpose and organized into labeled sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). However, it is long and includes some implementation minutiae (per-sport α values, historical 'Run 8' gate relaxation) that are not necessary for selecting or invoking the tool, though they add transparency. It earns its length for a complex tool but is not as tightly pruned as 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?

With no output schema, the description furnishes the full response shape: by_segment with three segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains why segments can be empty and how knobs affect filtering, covering the agent's need to interpret results and tune parameters. The caching note adds operational context.

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

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

Schema descriptions cover 100% of the 9 parameters with detailed explanations, so the baseline is 3. The description's mention of 'TRADEABLE-EDGE KNOBS' summarizes existing schema content but does not add new meaning beyond what the schema already provides; it only groups them conceptually. Thus 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly differentiates from siblings by focusing on Pipeworx-model disagreement and by defining the output segments (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?

It states a clear use case ('what should I bet on today') and notes that it avoids paging hundreds of markets. However, it does not explicitly mention alternative tools like polymarket_arbitrage or polymarket_edge_tracker, nor does it state when not to use it, so it stops at clear context without 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 description adds significant behavioral context beyond the annotations. It discloses that 'snapshots are written when polymarket_edges runs on a cache-miss, so gaps mean nobody scanned that day,' that history depth is bounded by the '60-day snapshot TTL,' and that decay numbers 'come from daily closes of edge_pp_net, not intraday.' These details help the agent interpret data gaps and time-series correctly. No contradiction with annotations (readOnlyHint=true, destructiveHint=false).

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 longer than average but heavily information-dense. It is structured with 'Args', 'RESPONSE', and 'LIMITS' sections, making it easy to parse. Every sentence provides useful detail; there is no fluff or repetition. The length is justified by the absence of an output schema, which requires the response structure to be described inline.

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 carries the full burden of explaining return values. It does so thoroughly: tracked[] with fields (full edge_pp_net time-series, first_seen, trend, decay_pp_per_day), expired[] with lifespan_days, and snapshot_dates[]. It also explains limitations (TTL, cache-miss gaps, daily closes) which are critical for correct interpretation. For a read-only telemetry tool with two simple params, this 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?

Schema description coverage is 100%, so the baseline is 3. The description's Args section ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') mostly repeats the schema, but adds the phrase 'snapshot family' which clarifies that the window parameter selects between families of snapshots (24hr vs 1wk vs 1mo), reinforcing the schema's 'window family' phrasing. This is marginal value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a specific verb (track) and distinct resource (historical edge snapshots), and differentiates from the related polymarket_edges tool by focusing on how edges persist and decay over time. The phrase 'Answers "how long has this edge existed and is it shrinking?"' ties it to a concrete use case.

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

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

The description provides clear context on when to use it: 'a fresh wide edge and a 3-week-old wide edge are different trades' implies this tool is for historical persistence analysis. However, it does not explicitly name an alternative tool or state 'use this instead of polymarket_edges'; the guidance is implicit rather than explicit. The mention of 'daily polymarket_edges snapshots' indirectly points to the relationship with the sibling tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds behavioral detail: it 'walks the ladder,' returns specific metrics like vwap_fill_price and slippage_pp, and highlights risks like forced_directional_risk and thin_legs. No contradiction with annotations.

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

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

The description is lengthy but well-structured with ALL-CAPS mode labels and a final usage directive. Every sentence adds information—modes, parameters, outputs, and risk context—making it dense rather than verbose. The front-loaded first sentence immediately conveys 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?

Without an output schema, the description enumerates the return fields for both modes (top_of_book, vwap_fill_price, capture_ratio, etc.), explains edge cases (thin legs, partial fills, forced directional risk), and ties usage to sibling tools. This is comprehensive for a tool of this complexity.

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

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

Although the input schema covers all four parameters with 100% coverage (baseline 3), the description deepens semantics by explaining the dual interpretation of size_usd (max spend for buys vs target proceeds for sells vs settlement notional in basket mode) and the auto side selection based on partition sum. It also clarifies the required presence of either market or event, which the schema leaves optional.

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

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

The opening sentence defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly specifies the two modes (single-market and basket) and the sibling tools it complements, distinguishing it from polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the failure mode (partial fills converting arb to unhedged directional position), giving a strong when-to-use rationale.

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

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

Even with annotations indicating read-only and idempotent behavior, the description goes far beyond by explaining output semantics (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning with two specific trigger cases), temporal_alignment, and skipped_cross_type/subtype counters. It also discloses that real spreads are rarer than the shortcut list suggests, providing honest behavioral 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 long but well-structured with clear sections (modes, response, safety fields) and front-loaded purpose. It uses formatting like TWO MODES and SAFETY FIELDS to aid scannability. While dense, every sentence contributes necessary information about behavior and limitations, so it earns its length.

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

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

Given there is no output schema, the description thoroughly explains return values including raw probabilities, spread in percentage points, compatibility_warning conditions, and temporal_alignment. It also details skip counters and their meanings, making it complete for a complex cross-referencing tool. The absence of an output schema is fully compensated.

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?

While the schema already describes each parameter (100% coverage), the description adds meaningful context: topic is a pre-mapped shortcut that auto-fetches a matching event, while kalshi_event_ticker and polymarket_event_slug override the mapped sides for custom pairings. It also enumerates the exact topic strings and provides example values, enriching the schema's basic descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which precisely states the tool's function with a specific resource and action. It clearly distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges by emphasizing the cross-venue comparison aspect.

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 clearly explains two usage modes (topic shortcuts and explicit ticker/slug pairings), and warns that most pre-mapped topics currently return compatibility_warning, implying limited tradeability. It also provides conditions under which spreads are meaningful (temporal alignment, equivalent bet shapes), but does not name alternative tools like polymarket_arbitrage for different use cases.

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

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

Annotations already mark it read-only and idempotent. The description adds valuable behavioral context not captured in annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the dual mode (value retrieval vs. key listing). 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 three sentences, each earning its place: core function, use case, and scoping/pairing. It is front-loaded with the primary action and contains no fluff or redundancy.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description covers the essential information: how to use it (with/without key), why it exists (avoid re-derivation), and its boundaries (scoped to identifier, paired with remember/forget). No missing information that would confuse 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 has 100% coverage—one parameter 'key' with description 'Memory key to retrieve (omit to list all keys).' The description repeats this usage pattern ('omit the key argument') and adds scoping context, but does not add significant semantic detail beyond 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 description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys' with a specific verb and resource. It distinguishes from siblings by explicitly mentioning remember and forget, making its role in the memory lifecycle 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 provides clear use context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch,' and references complementary tools with 'Pair with remember to save, forget to delete.' It lacks explicit when-not-to-use conditions but otherwise gives solid guidance.

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

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

The description reveals that mark_read:true flags events as read, which modifies state, contradicting the readOnlyHint:true annotation. This is a serious inconsistency because the annotation claims read-only behavior while the tool can mutate read status. Therefore, the description contradicts the annotations.

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

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

The description is four sentences, each serving a distinct purpose: core function, payload composition, filtering options, and behavioral nuance plus alternative access. It is tightly written with no redundancy, front-loading the action verb and resource.

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 detailing what each alert contains (source, citation_uri, raw payload), covering filtering and mark_read behavior, and noting an alternative HTTP endpoint. It fully equips an agent to select and use the tool correctly, including polling suitability.

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 100% means the schema already documents all parameters. The description adds meaningful value by explaining the consequence of mark_read (only newer events on next call) and giving a concrete type filter example. This goes beyond the baseline of 3, warranting a 4.

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

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

The description clearly states the tool pulls recent alerts from the subscription feed and describes the payload fields, making the purpose specific and unambiguous. However, it does not explicitly differentiate from sibling tools like recent_changes, so it falls short of a 5.

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

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

The description gives clear context: it mentions polling works fine and points to an HTTP endpoint for scripts, which provides guidance on when to use the tool versus external access. It also explains the mark_read effect for subsequent calls, implying a polling workflow. No direct comparison with sibling tools, but the context is sufficient.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavior: fan-out to multiple sources, GDELT→GNews fallback on rate limits or 5xx, USPTO soft-fail due to PatentsView sunset, and the structured output shape. This gives the agent a realistic model of how the tool behaves.

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

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

The description is front-loaded with likely user questions, then delivers a dense but well-organized summary of behavior, fallbacks, outputs, and the alternative tool. Every sentence adds value and there is no fluff; the length is justified by the tool's complexity.

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

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

With no output schema, the description compensates by explicitly stating the return shape: structured changes[] grouped by source, total_changes count, and citation URIs. It also covers data sources, error/fallback behavior, and the key alternative, making the description complete for an agent to select and invoke the tool.

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

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

The input schema already covers all three parameters with 100% coverage, including format details for `since` and examples for `value` and `type`. The description repeats the `since` format but adds no new parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly defines the tool as a change feed for a company over a recent window, with concrete natural-language examples ('What's new with X', 'updates on Acme'). It distinguishes itself from the sibling entity_profile by explicitly positioning recent_changes as the windowed dynamic feed versus the static profile.

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

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

The description provides explicit guidance on when to use this tool, including the quoted user-intent patterns. It also names the alternative entity_profile and specifies the exact condition under which to use it instead (static profile regardless of window), giving the agent clear decision criteria.

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

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

The description discloses behavioral traits beyond annotations: storage as key-value pair scoped by identifier, persistence duration for anonymous sessions (24 hours) vs authenticated users, and cross-session availability. These are not available in annotations and add critical 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 four sentences, front-loaded with the primary purpose, and each sentence provides essential information (when to use, storage mechanics, persistence, companion tools). No redundancy or unnecessary detail.

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

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

Despite lacking an output schema, the tool is simple (2 required params) and the description sufficiently covers purpose, usage triggers, scoping, persistence, and pairing with recall/forget. It gives an agent everything needed to invoke appropriately.

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 descriptive examples. The description does not add substantial new parameter semantics beyond the schema, though it reiterates the kind of data to store (e.g., resolved ticker, target address). Baseline 3 is appropriate given high schema coverage.

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

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

The description uses a specific verb 'Save' with a clear resource 'data the agent will need to reuse later', and explicitly differentiates from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.' It clearly states the tool persists key-value pairs.

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

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

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples, and it contrasts with recall/forget as complementary operations. It also clarifies persistence rules for authenticated vs anonymous users, covering 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?

Beyond the readOnly/idempotent annotations, the description discloses that the tool cascades through multiple internal endpoints, degrades gracefully when LEI/FIGI services are unavailable, and explicitly returns unresolved identifiers under `unresolved`. These are meaningful behavioral details that go well beyond annotation hints.

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

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

The description is long but information-dense and logically structured via 'SUPPORTED TYPES'. It front-loads example queries that, while slightly redundant with the main purpose, help match user phrasing. Every sentence contributes value, though a few examples could be trimmed for tighter prose.

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

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

For a complex tool with no output schema, the description covers inputs, expected identifiers, failure modes (degradation), and result structure (labeled source, `unresolved` field). This gives an agent enough context to select and correctly invoke the tool even without knowing the exact 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?

While the schema gives basic type/value descriptions, the description adds substantial meaning: it specifies input formats (ticker, CIK, name vs. brand/generic), explains what each identifier is (CIK, LEI, FIGI, RxCUI), mentions source attribution, and describes the `unresolved` field. This far exceeds schema-level 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 explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input', which is a specific verb+resource and clearly distinguishes it from sibling tools as a prerequisite ID lookup. It also enumerates supported types and specific identifier systems, leaving no ambiguity about what the tool does.

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

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

The instruction 'Use FIRST whenever you have a name but need an ID' provides direct usage guidance, and the note that it replaces 2-3 manual lookups gives clear context for when to apply it. However, it does not name explicit alternative tools or specify when not to use it, 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 readOnly and idempotent hints. The description adds that it 'probes each entity' with ai_visibility_check and returns a ranked list with score/confidence/signal density, which is not in annotations. This clarifies the orchestration behavior.

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

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

Four sentences with no fluff; front-loaded with the core purpose. The use case and return description earn their 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?

No output schema, but the description explicitly states the return format (ranked list with score, confidence, signal density). It also names the underlying probe, providing context for an agent to decide if this is the right batch tool. It doesn't mention rate limits or per-probe errors, but these are minor gaps given schema coverage.

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

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

The schema covers 100% of parameters with detailed descriptions, including the entities' first-entry-as-subject behavior. The description adds no new parameter syntax but contextualizes entities as 'your brand + N competitors'.

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 'Compare AI visibility across multiple entities side-by-side', naming the resource (AI visibility) and the verb (compare). It distinguishes from siblings by mentioning 'across multiple entities' and the ranking behavior, which differentiates it from the single-entity ai_visibility_check.

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

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

It gives a concrete use case ('competitive AI-marketing audits') and an example question. It indicates that it probes each entity with ai_visibility_check, implying the alternative for single entity, but doesn't explicitly exclude other comparison tools like compare_entities.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses key behavioral aspects: the fan-out across two third-party services, graceful degradation on partial failures ('sources_failed will list it if it times out'), and the potential 5-30s delay for bundlephobia's first measurement on a new version. These details are not visible in the annotations and add significant operational 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 well-structured and front-loaded with the core purpose, followed by use cases, return value breakdown, ecosystem limitation, and failure behavior. Every sentence carries useful information, and the use of em dashes and semicolons keeps it readable despite its length. No filler or redundant content.

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

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

Given the tool's complexity (composite of two sources) and the absence of an output schema, the description thoroughly explains what is returned (summary block fields, per-advisory detail, links, alternative versions) and handles edge cases (timeouts, partial failures, ecosystem support). It provides enough detail for an agent to understand the tool's scope, latency, and output without needing additional documentation.

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

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

The input schema already describes both parameters (package and version) with 100% coverage, including scoped package acceptance and version default behavior. The description does not add new parameter-level semantics; it only implies version usage by mentioning 'latest published version' in the context, which is already stated in the schema. Hence, it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package to my project' check, specifying the two data sources (deps.dev and bundlephobia) and the types of information gathered (license, advisories, version history, bundle size, dependency count, ESM/tree-shake). This distinguishes it from sibling tools like deep_research or bet_research, which serve different domains.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an important exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' which guides users away from this tool for other ecosystems. However, it doesn't mention alternative sibling tools by name, so it doesn't fully cover when not to use relative to all siblings.

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 by listing the return fields (name, country, state/province, web pages, email domains) and the input requirement that at least one of name/country is needed, which is not enforceable from the schema alone. 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?

Three short sentences deliver the core purpose, return data, and a key precondition. Each sentence earns its place, with no filler. The description is front-loaded with the 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?

For a simple search tool with a rich output schema and complete annotation set, the description covers the essential behavior and a necessary input rule. It does not need to explain return values or safety, as those are captured in the output schema and annotations. The description is complete for the given 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?

The schema has 100% description coverage, with all six parameters documented including aliases. The description adds a cross-parameter constraint that at least one of name or country must be provided, which is not captured in the schema's required field list. This adds meaning beyond the individual property 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 a specific action ('Search universities worldwide') with a defined resource and an external API (Hipolabs). It mentions return fields, making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools, though the university focus likely sets it apart.

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

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

The description provides a usage constraint ('At least one of name or country must be provided') but does not offer guidance on when to use this tool over alternatives. No exclusions or alternative tool suggestions are mentioned, so the usage context is implied rather than explicit.

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

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

Beyond the readOnlyHint annotations, the description discloses the embedding model (BGE-base-en), windowing (500-char overlapping windows), the 200K char cap with truncation and flagging, and that results include offsets and similarity scores. This adds meaningful operational context that annotations do not convey.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence adds a distinct insight (what it does, when to use, how it works). There is no wasted text.

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 value (passages with offsets and similarity scores), limitations (200K cap, truncation flag), and a clear example workflow with ask_pipeworx_grounded, making the tool's usage and behavior well-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%, so the baseline is 3; the description adds a few useful examples (SEC 10-K body, article, long tool result) and clarifies that text is 'the text you already pulled'. However, it does not add substantial parameter semantics beyond the schema, so a 4 is appropriate.

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

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

The description uses the specific verb 'Semantic search INSIDE a fetched record', naming both input (text, query) and output (top-N passages with character offsets and similarity scores). It clearly distinguishes itself from siblings by referencing ask_pipeworx_grounded and positioning itself as the passage-level search step.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt', giving a clear use case. It also states 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document', which points to the complementary alternative and usage pattern.

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

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

The description adds meaningful behavior beyond annotations: it requires an OAuth account, states anonymous/BYO cannot persist subscriptions, notes SMS phone verification and a 10/day cap, and explains feed semantics. Annotations already cover read-only/destructive/idempotent hints, so this extra context is valuable rather than redundant.

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 not bloated: it front-loads the core action and return value, then organizes types and delivery channels compactly in a single paragraph. Every sentence contributes useful information without filler.

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

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

For a complex create operation with nested objects, multiple subscription types, and delivery options, the description is complete. It covers auth, return value, supported types, feed behavior, and alternative pull mechanisms; the schema handles fine-grained webhook details. No output schema is needed since the return type (subscription id) is stated.

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

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

Schema coverage is 100%, but the description adds interpretive context for type-specific parameters (e.g., items:['5.02'] = officer change, 'Polymarket↔Kalshi cross-venue mispricings'). This goes beyond the bare schema descriptions and helps the agent understand the meaning behind the parameter values.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream,' and clarifies the return value ('Returns the new subscription id'). It clearly distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action.

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

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

It provides clear usage context by explaining the persistent feed ('always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json') and the optional email/SMS channels. While it doesn't explicitly say 'use this instead of X for one-off queries,' the proactive-monitoring framing and mention of recent_alerts imply the 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 declare readOnly/openWorld/idempotent/non-destructive. The description adds behavior beyond that by detailing what the tool returns (category-bucketed example questions with tool+argument shape), that it draws from a live catalog of thousands of tools, and that it can be called with no arguments or a topic. 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 front-loaded with natural language queries, then a concise purpose statement, return description, parameter guidance, and usage recommendation. Every sentence serves a clear function, and the structure flows logically from 'what' to 'how' to 'when'.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is fully complete: it explains the return format, invocation modes, the meaning of the topic parameter, and the intended use case. It also situates the tool among related meta-tools, which is valuable in the broader context.

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

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

Schema has 100% coverage already, including a description of the `topic` parameter and the behavior of omitting it. The description adds example values and phrases the parameter in terms of 'focus', but this is mostly redundant with the schema and does not provide significant new semantic meaning.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs ('Returns', 'Use this FIRST') and explicitly differentiates from sibling tools by positioning itself as the starting point for agents unfamiliar with 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 guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also names alternatives (ask_pipeworx, entity_profile, compare_entities) and explains the optional topic parameter for focused vs. full-spread queries.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable context: the row is deactivated but not deleted, and historical events remain available via recent_alerts. This explains the non-destructive behavior and the side effect clearly, going beyond what annotations alone convey.

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

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

The description is two sentences and front-loads the action ('Cancel a subscription by id'). Each sentence earns its place: the second explains ownership enforcement and the deactivation side effect. No filler or redundancy.

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

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

For a simple one-parameter tool with no output schema, the description covers the core action, the ownership constraint, and the non-deletion behavior. It does not mention error cases or return values, but given the simplicity and schema coverage, it is sufficiently complete.

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

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

The input schema already fully describes the 'id' parameter (including that it is the subscription id returned by subscribe), providing 100% coverage. The description only repeats 'by id' without adding new semantic meaning, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Cancel a subscription by id.' It also clarifies the scope ('only cancel your own subscriptions') which distinguishes it from canceling others' subscriptions and from related tools like list_subscriptions and subscribe. The deactivation note further differentiates its effect from a pure delete.

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 (when you have a subscription id and want to cancel it) and mentions the ownership prerequisite, but it does not explicitly state when to use this over alternatives or exclude contexts. There is no direct comparison to subscribe or list_subscriptions, so the guidance is implied rather than explicit.

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 mark this as read-only, open-world, idempotent, and non-destructive. The description goes further by explaining the verdict vocabulary and the crucial distinction that could_not_verify means the check didn't happen (with verification_error) and must not be treated as evidence, while unsupported means no source covers it. This is essential behavioral context beyond the annotations.

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

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

The description is long but well-organized with a trigger list, purpose, routing explanation, return details, and a critical caveat. Each sentence provides value, though the list of example phrases is somewhat redundant and the text could be tightened.

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

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

Despite no output schema, the description enumerates all possible verdict values, specifies that it returns the grounded/structured value with a pipeworx:// citation and reasoning, and explains error semantics (could_not_verify vs unsupported). This gives an agent everything needed to interpret results, and the two routing paths cover the tool's full behavior.

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

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

The input schema provides full descriptions for both params (claim and tolerance_pct) with examples and defaults, so schema coverage is 100%. The description itself does not add parameter-level detail, meeting the baseline of 3

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

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

The description opens with natural-language trigger phrases and clearly states 'natural-language claim verification against authoritative sources.' It then specifies two routing paths (SEC EDGAR/XBRL for financials, grounded pipeline for other claims) and notes it replaces 4–6 sequential calls, fully distinguishing it from sibling research/query tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains when the structured financial path is used vs the grounded pipeline. However, it does not name alternative tools to use for non-claim queries, so it lacks explicit when-not guidance and alternative tool references.

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