Paypal

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds useful behavioral context (default model, BYO key for Anthropic, per-model output structure) but does not significantly expand beyond what annotations imply. The bar for extra value is lowered by annotations, so a 3 is appropriate.

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

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

The description is two sentences plus parameter explanations, highly information-dense with zero fluff. It front-loads the core purpose and lists use cases efficiently. 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?

Despite 4 parameters and no output schema, the description explains the output structure (per-model {score, confidence, signals, raw_response} + combined view) and hints at usage context. This is complete enough for an AI agent to understand inputs and expected outputs.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description adds value by explaining the default model, the optional API key purpose, and the context parameter's role in disambiguation. This goes beyond schema basics, justifying 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 probes LLMs for knowledge about an entity and returns a visibility score (0-100). It distinguishes itself from siblings by specifying its unique function: AI marketing audits, brand checks, competitive monitoring. The verb 'probe' and resource 'LLMs' with scoring output make the purpose highly specific.

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

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

The description explicitly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and indicates when to provide an API key for additional models. However, it does not explicitly mention when not to use the tool or compare it to alternatives like 'deep_research' or 'entity_profile'. The context is clear but lacks exclusions.

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, idempotentHint, and openWorldHint annotations, the description discloses that the tool never creates, modifies, deletes, or takes any action, returns citations for every factual claim, does not ask clarifying questions, handles aliases like $TICKER, and returns an error for nonsensical questions. This is rich behavioral context that cannot be inferred from the annotations alone.

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 and front-loaded: the preference over web search and core capability appear first, followed by examples, alternatives, and behavioral caveats. It earns most of its length, but the final phrase 'for exploring what’s on this MCP server, use explore or similar' is vague and slightly undermines the otherwise precise structure.

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

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

With no output schema, the description carries the full burden of explaining return behavior: it promises a structured answer with stable pipeworx:// citation URIs and citations for every factual claim. It also covers error behavior, alias handling, read-only guarantees, and alternatives. An agent has enough context to decide when to invoke this tool and what to expect back.

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 documents the single required question parameter and its aliases with 100% coverage. The description adds examples of acceptable questions and notes that aliases like $TICKER are resolved, but it does not substantially extend parameter-level meaning beyond what the schema provides. The baseline of 3 is appropriate because the schema handles the parameter documentation.

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

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

The description states a specific purpose: it routes questions to one of 5,767 tools across 1,506 verified sources and returns structured answers with stable pipeworx:// citation URIs. The scope is clear and the description explicitly contrasts itself with sibling tools like ask_pipeworx_grounded, entity_profile, and validate_claim.

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 opens with 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', then gives explicit alternatives: ask_pipeworx_grounded for multi-source synthesis, deep_research for code questions, entity_profile for single-entity deep dives, validate_claim for verification, and discover_tools for tool discovery. It also lists trigger phrases and concrete examples, making when-to-use decisions unambiguous.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond annotations by explaining that candidate routing improvements are enabled live when under test, that no candidate is currently active, and that this is a fully working router rather than a fallback stub. 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 front-loaded with the tool's identity and beta nature, and each sentence contributes either usage guidance or transparency. It is somewhat dense with parentheticals and a specific date, but it remains efficient for the nuance it covers.

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 natural-language router with safe annotations and fully documented parameters, the description is nearly complete. It references 'same response shape' without specifying what that shape is, but it points clearly to ask_pipeworx as the behavioral reference, which is sufficient given the sibling 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 description coverage is 100%, and all six parameters are documented as aliases for the natural-language question. The description adds only 'same arguments' via the ask_pipeworx reference, which does not materially improve on the schema. A baseline score of 3 is appropriate given the 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 identifies this as a beta variant of the ask_pipeworx universal router and explains that it shares the same tools, arguments, and response shape. It distinguishes itself from ask_pipeworx by the experimental routing improvement angle, though it does not use a strong imperative verb for the tool's core action and does not differentiate from ask_pipeworx_grounded.

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

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

The description explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing,' and contrasts it with the stable router for comparison. It does not explicitly list exclusions or mention ask_pipeworx_grounded, but the intended experimental usage is clear.

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

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

Annotations already signal read-only, idempotent, and open-world behavior, and the description goes well beyond them by disclosing the refusal mechanism, exact refusal_reason values, the evidence format, the extra LLM call cost, and the hard constraint that answers come only from the tool result. No annotation contradiction.

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

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

The description is dense but every sentence contributes: purpose, behavior, return shape, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with the primary purpose and does not waste words, though the length is on the higher side for maximal scanning efficiency.

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 compensates by specifying the success return shape, the refusal shape, the potential refusal_reason values, and the conditions for choosing this tool over its sibling. An agent has everything needed to invoke it appropriately and interpret its results.

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

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

Schema description coverage is 100%, with the question parameter and its aliases fully documented. The tool description adds no parameter-specific semantics beyond stating that routing fills arguments, but with full schema coverage the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with a specific extraction behavior distinct from ask_pipeworx. It names the resource and the underlying routing mechanism, so an agent can tell what the tool does without confusion.

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 the tool ('whenever an answer will be quoted, cited, or acted on'), gives concrete example domains, and directly compares to ask_pipeworx with a preference for casual lookups. This leaves no ambiguity about tool selection.

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

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

Annotations mark it as readOnly, openWorld, idempotent, and non-destructive, but the description goes far beyond by detailing blocking mechanisms (low-confidence, closed markets), safety short-circuits, resolution-rule risk, and caveats like wide-spread liquidities. This richness is exactly what annotations cannot capture.

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 verbose and covers extensive details—classifiers, fan-out examples, response shapes, resolver contract, safety mechanisms, and many edge cases. While this comprehensiveness is valuable for a complex tool, it sacrifices conciseness. Not all sentences are strictly necessary; a more structured format could improve scanability.

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 high complexity (multiple fan-out sources, varied response fields, safety intercepts), the description is remarkably complete. It explains all return value structures (result.market, result.analysis, result.evidence, resolver contract, parent_event extractor, news fields, tradeability notes). There is no output schema, but the description fills the gap thoroughly.

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

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

Schema coverage is 100%, so parameters are well documented. The description adds significant context beyond the schema: it explains the difference between 'quick' and 'thorough' depth, the meaning of 'include_raw', and how the resolver contract works. This extra detail earns a score above the baseline of 3.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with concrete examples of inputs ('should I bet on X') and outputs (evidence packet, market-vs-model comparison). It distinguishes from sibling tools that focus on different aspects like arbitrage or edge tracking.

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 lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides classifier examples. However, it does not explicitly mention when NOT to use this tool or direct to alternatives when the bet is not suitable, though the sibling list provides context.

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

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

Annotations declare read-only, idempotent, non-destructive behavior. The description adds specifics: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), fiscal year handling, sorting by primary metric, and return of paired data with URIs. No contradictions.

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

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

The description is a single paragraph with dense but valuable information. Slightly long but every sentence contributes meaning. It is well-organized with examples first then details.

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

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

Given no output schema, the description adequately explains return values ('paired data + citation URIs'). It covers both entity types and sorting behavior. Could be more specific about response structure, but sufficient for use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying input examples (tickers/CIKs for company, names for drug) and specifying data scope (latest 10-K). This extra context justifies 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 it performs side-by-side comparison of 2–5 companies or drugs, with specific data sources and examples. It distinguishes itself from sibling tools like entity_profile by emphasizing preference over sequential lookups.

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

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

The description explicitly lists example queries and states 'ALWAYS PREFER over sequential single-pack lookups'. It provides input format guidance but does not explicitly cover when not to use it, though it is well-implied.

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

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

Annotations already mark the tool read-only, open-world, and idempotent; the description adds substantial behavioral context: auth requirements, paid tier for thorough, parallel facet routing, gaps[] never invented, hop fields, resolvable citation URIs, contradictions[] scan, semantic excerpting, and latency expectations.

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?

Though lengthy, the description is dense and front-loaded, opening with the account requirement and the sibling alternative before detailing behavior. Every sentence carries operational value, from citation resolvability to excerpting and latency.

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

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

With no output schema, the description fully covers the return packet: verbatim evidence, confidence, source, fetched_at, citation URI, gaps[], contradictions[], hop field, and timing. It also covers routing, depth semantics, and exclusions, leaving no critical operational gap.

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

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

Schema description coverage is 100% and both parameters are thoroughly documented in the schema itself, including depth enum meanings and question format. The description mostly restates what the schema already says, so the baseline of 3 applies without material addition.

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 (research/decompose/route/return) with a concrete resource: Pipeworx's 1506 structured data sources. It explicitly differentiates itself from siblings with 'this is NOT open-web search' and by naming the alternative ask_pipeworx.

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

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

Gives explicit when-to-use guidance (broad/multi-part structured questions) and when to prefer ask_pipeworx (single lookup, breaking news, not signed in). Also specifies account/tier requirements and depth behavior, leaving no ambiguity about selection.

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

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

Annotations indicate read-only and idempotent behavior. The description adds that results include full schemas and curated examples, ready to call directly, and that no second schema lookup is needed—disclosing behavior beyond what annotations provide.

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

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

Single paragraph with clear front-loading of purpose, followed by use cases, return details, and usage advice. Every sentence adds value; 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?

Given no output schema, description explains return value (top-N tools with names, descriptions, schemas). Could specify output structure (e.g., array of objects) but is sufficient for a discovery tool. Slight gap in output format detail.

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% (all 6 parameters described). The description adds context that 'query' accepts aliases and explains its role, but this largely reinforces schema info. Baseline 3 is appropriate as description does not significantly augment parameter 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 finds tools by describing data or task, lists specific data domains (e.g., SEC filings, FDA drugs), and distinguishes from sibling tools by positioning itself as the first call for discovering available tools before executing specific tasks.

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 to use when needing to browse, search, or discover what tools exist, gives concrete examples, and instructs to call it FIRST when exploring options. Does not explicitly state when not to use but context implies it is for discovery, not execution.

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 read-only/idempotent/non-destructive; the description adds valuable behavior: patents soft-fail, empty sections are 'real no data', private companies return resolved:false with notes, and sources_used/sources_failed report what actually returned data. 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 densely organized and front-loaded with user triggers and the override rule before the detailed return contract. Some redundancy with the schema exists, but most length is justified by the need to document outputs in the absence of an output schema.

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?

Because there is no output schema, the description must and does enumerate return sections, URI formats, sort order, failure modes, and source-reporting fields. It also covers edge cases like private companies and expected empty FDA sections, making it complete for an agent to call correctly.

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

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

Schema coverage is 100% and the schema already documents both type and value thoroughly. The description reinforces zero-padded CIKs, tickers, names, and type interchangeability, but does not add substantial new semantic meaning beyond the schema.

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

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

The description opens with concrete user intents ('Tell me about X', 'research Acme') and a precise scope: 'full cross-source profile of a US public company in ONE parallel call.' It names the fan-out sources and returned fields, so an agent can easily tell it apart from generic research tools.

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

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

It gives an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies acceptable input forms and private-company behavior. It does not explicitly name sibling alternatives like compare_entities or deep_research, so exclusion guidance is slightly implicit.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Delete' is consistent. However, the description does not add additional behavioral context beyond the annotation, such as irreversibility or error handling. With annotations present, this is acceptable but minimal extra value.

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

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

The description is two sentences with no wasted words. It front-loads the purpose and then provides usage guidance, making it easy to scan and understand quickly.

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 deletion tool with one parameter and no output schema, the description covers purpose, usage scenarios, and tool relationships. It could mention success/failure behavior, but the basic completeness is high given the tool's simplicity.

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

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

Schema coverage is 100% with a single 'key' parameter described in the schema as 'Memory key to delete'. The description adds no extra meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and resource (memory by key), and distinguishes itself from siblings 'remember' and 'recall' by mentioning them.

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

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

The description provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also advises pairing with 'remember' and 'recall', giving context on when to use this tool. Minor lack of when-not-to-use, but overall strong 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, covering safety. The description adds behavioral details beyond annotations: it fetches the page, extracts title/description/key links, and emits standard markdown format. This provides process-level transparency without contradiction.

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

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

The description is a single paragraph that front-loads the main purpose, then explains the process, and ends with use cases. While not extremely concise, every sentence serves a purpose and adds value. It is well-structured and readable.

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

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

For a tool with no output schema and two parameters, the description adequately explains the output format ('single text blob ready to drop at site-root/llms.txt') and lists use cases. It provides enough context for the agent to understand the tool's purpose and result, though omitting potential error cases or edge conditions prevents a perfect score.

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 significant meaning beyond the schema's parameter descriptions; it only implicitly references 'url' and 'max_links' in the context of the tool's operation. No additional syntax, format, or constraints are provided.

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

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

The description clearly states the tool's action: generate an llms.txt file for any URL. It uses specific verbs like 'fetches', 'extracts', 'emits', and lists concrete use cases (client site indexing, personal projects, competitor auditing), distinguishing it from sibling tools that focus on visibility checking or scanning.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitors), offering clear context for when to use this tool. However, it does not explicitly mention when not to use it or exclude alternatives among siblings, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. Description adds return fields and default behavior (active only). No contradictions, but no additional behavioral details beyond annotations and usage hint.

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

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

Two concise sentences: first defines function and return fields, second gives actionable guidance. No redundant or extraneous 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 simple tool with one optional parameter and no output schema, the description fully covers purpose, return structure, and usage intent. No gaps identified.

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

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

Schema provides 100% description for the single parameter include_inactive. Description reinforces purpose by mentioning 'active subscriptions' and tying the parameter to finding ids to cancel, adding contextual value beyond schema.

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

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

Clear verb 'list' with specific resource 'subscriptions' and scope 'caller's active'. Differentiates from sibling tools like subscribe and unsubscribe by focusing on listing rather than creation or deletion.

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: 'to review what you're monitoring before adding more or to find an id to cancel'. Implicitly ties to sibling tools subscribe and unsubscribe, but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds return field details but no new behavioral traits (e.g., authentication, rate limits). Consistent but not additive.

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?

Single sentence with clear action and result. Efficient and front-loaded with 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?

Output schema exists, so return values are implicitly covered. Description mentions key fields. Lacks mention of authentication prerequisites, but schema provides that. Adequately complete.

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

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

Schema description coverage is 100%, so each param is already documented. The description clarifies invoice_id is the key identifier but adds no new semantics beyond schema.

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

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

The description clearly states the tool retrieves full invoice details by ID, with specific return fields (line items, amounts, dates, status). Distinguishes from siblings like paypal_get_order and paypal_list_invoices.

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

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

No explicit guidance on when to use vs alternatives. Agents must infer from context: use when invoice ID is known. Sibling names (paypal_list_invoices) suggest an alternative for listing, but not stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the return content (buyer info, items, amounts, fulfillment status), which goes beyond the annotations. No contradictions.

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

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

The description is a single, clear sentence with no wasted words. It immediately communicates the tool's purpose and output.

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, high schema coverage, presence of an output schema, and annotations covering safety, the description is complete. It tells the agent what the tool does and what it returns.

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%—all four parameters have descriptions. The tool's description adds an example of an order_id but does not explain parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('full details of a PayPal order by ID'), includes an example ID, and lists the returned data (buyer info, items, amounts, fulfillment status). It clearly distinguishes from sibling tools like paypal_get_invoice.

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

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

The description states what the tool does but does not provide guidance on when to use it versus alternatives, nor any prerequisites or exclusions. For a read-only lookup tool, this is minimally adequate.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, and destructiveHint false, so the description adds minimal behavioral context beyond listing return fields. No contradictions, but the description does not deepen transparency.

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

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

Two succinct sentences with the main action front-loaded. No filler, every sentence adds value.

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

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

With rich annotations and complete schema, the description is adequate. It clarifies the output fields. However, it omits potential pagination or filtering details, but given the tool's simplicity and the presence of an output schema, it is reasonably complete.

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

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

Schema coverage is 100%, and all parameters are documented in the schema. The description adds no extra meaning about parameters beyond what the schema provides, warranting the baseline score 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 clearly states the verb 'List' and the resource 'chargebacks and claims against your account.' It also specifies the returned fields (IDs, amounts, statuses, reasons), distinguishing it from sibling tools like paypal_list_invoices or paypal_list_transactions.

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

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

The description provides no guidance on when to use this tool versus others (e.g., paypal_list_invoices). It does not mention prerequisites, alternatives, or scenarios, which would be helpful given the numerous sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds return field context but does not disclose pagination, rate limits, or authentication requirements beyond what the schema provides.

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) and front-loaded with the primary action and return data. Every sentence earns its place without redundancy.

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

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

Given the tool has 5 parameters and an output schema, the description adequately states what the tool does and returns. However, it omits mention of pagination (page, page_size) and the sandbox parameter, which are present in the schema but could be highlighted for completeness.

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 description does not need to add parameter details. It provides no additional meaning beyond the schema.

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

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

The description clearly states the verb 'List' and the resource 'your PayPal invoices', and specifies return fields (numbers, amounts, statuses, dates). The sibling tools include paypal_get_invoice for a single invoice, making the purpose distinct and 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 says 'Use to track billing and outstanding payments,' providing a usage context. However, it does not explicitly state when not to use this tool or mention alternatives like paypal_get_invoice for individual invoices.

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. The description adds minimal extra context beyond stating return fields, so it is adequate but does not significantly enhance transparency beyond annotations.

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

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

The description is concise with three short sentences, front-loaded with purpose, and contains no fluff. Slightly more structure could improve readability, but it is efficient overall.

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

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

Given the tool has 5 parameters and an output schema exists, the description adequately covers return fields and use case. However, it omits potential details like pagination, limits, or time zone handling, making it acceptable but not robust.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description alludes to date range but adds no meaningful semantics beyond what is in the schema, meeting the baseline.

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

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

The description clearly states 'Find PayPal transactions within a date range' with a specific verb and resource, and mentions return fields. However, it does not explicitly differentiate from sibling tools like paypal_get_invoice or paypal_list_invoices.

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 a use case context ('audit payments or track cash flow') but offers no guidance on when not to use this tool or how it compares to alternative PayPal list tools among 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 only indicate this is a non-read-only operation; the description adds meaningful behavioral context: filing without an account returns a claim_token, the token can be used later to check resolution status, there is a rate limit of 5 per day, and feedback is free and outside tool-call quotas. It does not detail side effects like data storage or account behavior, but the provided info goes well 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 dense and somewhat long, but every sentence contributes: it covers purpose, usage triggers, exclusions, message formatting, token flow, rate limits, and cost. It is front-loaded with the core purpose and structured logically. While it could be broken into bullets, the paragraph format remains scannable and information-dense without 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 feedback tool with no output schema, the description covers all necessary aspects: when to use, what to include, how to follow up via claim_token, rate limits, and the feedback pipeline. It also addresses edge cases like handling tools from other MCP servers. The return behavior is sufficiently explained through the claim_token mechanism, making the tool's behavior fully predictable.

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

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

Schema coverage is 100%, with each parameter described. The description enhances this by explaining the claim_token use case ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), reinforcing the message format ('don't paste the end-user's prompt'), and emphasizing the need to describe issues in terms of Pipeworx tools/packs. This adds practical clarity beyond the schema's field descriptions.

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

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

The description opens with a clear action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clarifies the tool's purpose as feedback submission and enumerates specific categories (bug, feature/data_gap, praise), distinguishing it from the many research and query sibling tools. This is a concrete verb+resource definition with strong sibling differentiation.

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

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

The description explicitly states when to use this tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: if the tool came from a different MCP server, file it with that server instead. This gives both positive and negative usage guidance, exceeding basic expectations.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds that data is self-aggregating from CF analytics-engine, no PII, and cached 5min-1h. No contradictions found.

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 but comprehensive, with bullet points for use cases and clear sentences. Every sentence adds value without redundancy.

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

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

The description explains the output (top tools, packs, volume) and caching, but does not specify the exact output format (e.g., JSON structure). Since no output schema exists, a bit more detail on response structure would improve completeness.

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' has 100% schema coverage with enum. The description enriches it by explaining that shorter windows surface hot trends and longer show steady-state demand, adding meaning beyond the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window, with specific use cases listed. This distinguishes it from sibling tools like discover_tools and ask_pipeworx.

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

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

Three explicit use cases are provided, giving clear guidance on when to use the tool. However, it does not explicitly state when not to use it or mention alternatives like ask_pipeworx for direct questions.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds deep behavioral context: detection algorithms, Jaccard similarity (0.30 threshold), placeholder filtering (>20% placeholder fraction), fill check against CLOB depth, and edge case handling (realizable_edge_pp ≤ 0 no trade). No contradictions.

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

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

The description is lengthy but well-organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the main purpose and mode distinctions. While detailed, some repetition could be trimmed; still earns its length for a complex tool.

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

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

Despite no output schema, the description thoroughly explains the response structure: opportunities[] with fields, partition_check object in event mode, and fill check subfields. Covers modes, filters, edge cases, and fallback tool usage. Complete for a data-finding tool.

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

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

Schema descriptions are brief ('Single-event mode', 'Cross-event mode'), but the tool description adds extensive semantics: examples of slugs, partition checks, Jaccard similarity, fill check details. It enriches understanding far beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and explains each, differentiating it from sibling tools like polymarket_fill_risk.

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 each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Includes examples and directs to polymarket_fill_risk for custom sizing, providing clear 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 goes well beyond annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing the three model segments, methodology, output fields (edge_pp_net, kelly_fraction), caching behavior, diagnostic info, and Fed bet exclusion. 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 detailed and front-loaded with purpose. Structure is logical (segments, outputs, knobs, response format). Some technical depth (sport-specific alphas) may be excessive, but overall 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?

Despite no output schema, the description fully covers response structure (by_segment, fed_candidates, _diagnostics) and opportunity fields (edge_pp_net, kelly_fraction). Caching, failure modes, and knob behaviors are addressed, making it complete for an agent.

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

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

With 100% schema coverage, baseline is 3, but the description adds significant nuance: explains tradeable-edge filters (min_liquidity, max_spread_pp), interactions like min_partition_leg_kelly vs min_kelly, slippage context, and default behaviors. Provides value beyond schema.

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

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

The description states a specific verb ('Scan top Polymarket markets and return opportunities') and resource (Polymarket markets), and distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement. The phrase 'what should I bet on today' clarifies its 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 clearly conveys when to use the tool ('discover opportunities without paging hundreds of markets') and provides tradeable-edge knobs for configuration. However, it does not explicitly exclude cases where alternatives (e.g., polymarket_edge_tracker) would be more appropriate.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, and destructiveHint false. The description adds significant behavioral context: response structure (tracked, expired, snapshot_dates), limits (60-day TTL, snapshot start, decay computation from daily closes), and interpretation of signed edge_pp_net. 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?

While the description is lengthy, it is well-structured and front-loaded with the core purpose. Each sentence adds useful information (e.g., response fields, limits, edge interpretation). Some minor redundancy could be trimmed, but overall 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?

Despite lacking an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), including field semantics and interpretation. It also covers limitations (history depth, decay computation). The tool is fully contextualized.

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

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

Schema coverage is 100% and the description adds default values (14 days, 1wk) and valid ranges (2-30 for days). It also explains the 'window' parameter as snapshot family, which is not fully detailed in the schema. This adds marginal value beyond the schema, justifying a score above baseline.

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

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

The description opens with a specific verb+resource ('Edge persistence and decay telemetry') and clearly distinguishes from sibling tools like polymarket_edges by focusing on time-series and decay. It answers a concrete question about edge longevity, leaving no ambiguity about what the tool does.

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

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

The description implicitly explains when to use the tool ('a fresh wide edge and a 3-week-old wide edge are different trades'), which guides usage context. It does not explicitly name alternatives or when-not-to-use, but the purpose is sufficiently clear to infer appropriate scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: that it walks the order book ladder, computes VWAP fill price, slippage, and max fillable amounts, and in basket mode checks all legs, identifies thin legs and forced directional risk. 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 lengthy but well-structured, starting with the core purpose, then required parameters, then mode-specific details, and finally usage guidance. While every sentence adds value, it could be slightly more concise without losing essential detail. Still, the structure is logical and front-loaded.

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

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

Given the absence of an output schema, the description fully details return fields for both modes, including verdict, slippage, fill details, thin legs, and forced directional risk. It also explains the risk scenario (partial fills leading to directional exposure), making the tool's behavior and outputs completely understandable without an output schema.

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

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

Schema coverage is 100%, but the description adds significant context: explains single-market vs basket mode parameter requirements, default values for side and size_usd, and clarifies the meaning of size_usd in basket mode (settlement notional S). It goes beyond schema documentation to make parameter semantics clear.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth, specifying two distinct modes (single-market and basket) and detailing their outputs. It differentiates from siblings by positioning itself as a prerequisite risk check before acting on arb signals or large trades.

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 ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the rationale (theoretical overround not capturable on thin books, partial fills convert arb into directional position). This provides clear, actionable guidance for agent 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?

The description goes far beyond the readOnly/idempotent annotations, disclosing that pairing is keyword-based and unverified, that compatibility_codes may be non-empty even when matches exist, that temporal_alignment null does not mean aligned, that Kalshi fees are not modeled so spreads are gross, and that unknown legs are never paired. This is exceptionally transparent and adds value the annotations cannot express.

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

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

The description is long and dense, but nearly every sentence carries a distinct operational fact and there is no padding or repetition. It is front-loaded with the core purpose and mode distinction before diving into safety fields and caveats, though the dense single-block structure could be easier to scan.

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

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

For a tool with three optional parameters, no output schema, and rich runtime ambiguity, the description is remarkably complete: it covers response shape, warning codes, skipped-pair categories, temporal alignment semantics, fee treatment, and the rarity of real spreads. An agent has enough information to call this tool and interpret its results correctly.

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

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

The schema already documents all three parameters with 100% coverage, including the override semantics for kalshi_event_ticker and polymarket_event_slug. The description adds the crucial mode-level behavior that both modes run the identical token-overlap matcher and therefore share the same disclosures, plus the conceptual distinction between pre-mapped topics and explicit pairing.

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 precise definition: a cross-venue spread between Kalshi and Polymarket for the same resolving question, and immediately distinguishes it from a generic arbitrage tool by describing two concrete modes and the matching logic. This clearly differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges even though those are not named.

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 explains when to use each mode — `topic` for pre-mapped shortcuts, explicit ticker/slug for custom pairings — and warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped does not mean tradeable. It does not name alternative tools or state exclusions like 'use X instead when...', which keeps it at a 4 rather than a 5.

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

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

Annotations already declare read-only and idempotent. Description adds scoping detail (based on identifier) and lifecycle context (pair with remember/forget). No contradiction, adds value beyond annotations.

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

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

Concise, front-loaded, every sentence adds value. No filler.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It explains functionality, scoping, and sibling relationships.

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 the single parameter fully. Description clarifies that omitting the key lists all keys, adding behavioral context not in schema.

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

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

The description explicitly states the tool retrieves a value saved via remember or lists all keys when argument is omitted. It clearly identifies the verb-resource pair and distinguishes from siblings like forget and remember.

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 guidance: use to retrieve stored context without re-deriving. Mentions scoping and pairing with remember/forget. Could be more explicit about when not to use but is adequate.

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, idempotentHint, and destructiveHint. The description adds valuable behavioral details: the mark_read flag to acknowledge events so subsequent calls show only newer ones, and the structure of returned events (source, citation_uri, payload). 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 somewhat verbose (multiple sentences) but well-structured: purpose first, then details, then alternative. A more concise rewrite could improve readability without losing information, hence a 3.

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

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

Despite no output schema, the description explains return fields (source, citation_uri, payload) and all parameter behaviors, including mark_read semantics. It also provides an alternative endpoint for scripts/dashboards, making it fully self-contained for a read-only tool.

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

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

Since schema coverage is 100%, the baseline is 3. The description adds extra context for mark_read by explaining its effect on subsequent calls, and mentions filtering by type and since. This slight enhancement justifies 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 fired events from a subscription feed, returning recent alerts with specific fields (source, citation_uri, payload). It uses specific verb+resource (pull/recent alerts) and distinguishes itself from sibling tools, none of which directly handle alerts.

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 usage context by mentioning that polling works fine and offering an alternative endpoint (GET alerts.json) for scripts and dashboards. It does not explicitly state when not to use this tool but implies appropriate 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?

Discloses data sources (SEC EDGAR, GDELT, GNews fallback, USPTO), fallback behavior (soft-fail for PatentsView sunset), and return structure (changes grouped by source, total_changes count, citation URIs). Annotations readOnlyHint, idempotentHint, etc. are consistent; no contradictions.

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

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

The description is thorough but could be slightly more concise. However, it uses front-loaded examples, then sources, then parameter specifics, making it easy to scan. Every sentence adds value.

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

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

Despite no output schema, the description clearly states what is returned (changes grouped by source, total_changes count, pipeworx:// citation URIs). For a read-only tool with three well-documented parameters, 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 coverage is 100%, and the description adds meaningful context: explains `since` accepts ISO date or relative shorthand, `value` is ticker or CIK, `type` is only 'company'. Provides relative shorthand examples and the implication for data windowing.

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

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

The description starts with concrete use-case examples ("What's new with X", "latest on Y") and explicitly distinguishes itself from the sibling tool entity_profile. It clearly states it is a change feed for a company, covering SEC filings, news, and patents.

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 (when asked about recent changes) and when not (for static profile, use entity_profile). Includes example query patterns and parameter suggestions like '30d' for typical monitoring.

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

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

Discloses key behavioral traits: key-value store, scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Aligns with annotations (idempotent, non-destructive), adding concrete details.

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

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

Concise, well-structured, and front-loaded. Every sentence adds value: purpose, usage, behavior, and pairing with siblings. No wasted words.

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

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

Complete for a simple key-value tool. Covers purpose, usage, persistence, scoping, and connection to sibling tools. No gaps given the context.

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

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

Schema coverage is 100% and parameter descriptions are clear. The description adds meaningful context with example key patterns and value types, slightly exceeding the baseline 3.

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

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

The description clearly states the tool saves data for reuse across conversations, with specific examples (ticker, address, preference). It effectively distinguishes from sibling tools recall and forget.

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 ('when you discover something worth carrying forward') and pairs with recall/forget, providing clear guidance on alternatives.

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

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

The description adds significant behavioral detail beyond the readOnly/idempotent annotations: graceful degradation when LEI/FIGI enrichment fails, explicit `unresolved` reporting instead of omission, and behavior when a name matches multiple instruments (returns `figi_candidates` and asserts nothing). It also discloses that the tool cascades through multiple internal lookup endpoints. No contradiction with annotations exists.

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

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

The description is long but organized with clear sections for supported types, behavioral caveats, and fallback behavior. Each sentence adds information an agent needs, and the core purpose is front-loaded with natural-language examples. The density is justified by the tool's complexity.

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

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

Even without an output schema, the description anticipates agent confusion: it specifies returned fields like `figi_candidates` and `unresolved`, labels identifiers by source, and covers edge cases such as non-US issuers and non-equity instruments. An agent has enough context to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining the meaning of input values with examples, the difference between ticker-implied and name-search lookups, ISIN-to-LEI behavior, and the exact entity-name-only rule for bond issuers. This materially helps an agent construct correct calls.

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

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

The description states a specific verb and resource: resolve a user-spoken NAME to canonical/official identifiers. It lists concrete query phrasings and supported entity types, which distinguishes it from sibling tools like entity_profile or compare_entities. The opening examples make the tool's purpose immediately identifiable.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear routing rule. It also distinguishes between company and drug lookups, enumerates accepted input forms, and warns against passing full noun phrases for bonds. This is actionable guidance for when to invoke the tool versus alternatives.

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

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

Annotations indicate read-only, idempotent, and non-destructive. Description adds details on probing, ranking, and output format (score, confidence, signal density), which supplements the annotations without contradiction.

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

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

Two sentences conveying process, use case, and output. No redundant information; every phrase earns its place.

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

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

For a tool with no output schema, the description fully explains the output structure (ranked list, scores). Given the 4 parameters and 100% schema coverage, the description is complete.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining the entities array's first entry as 'subject', models' supported values and defaults, _apiKey usage, and context purpose.

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

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

Description clearly states verb 'compare' and resource 'AI visibility across entities', and distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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 suggests use for competitive AI-marketing audits with a concrete question example. Implicitly excludes single-entity checks by referencing ai_visibility_check, but does not explicitly state when not to use.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. Description adds valuable behavioral context: composite call with fan-out, partial failure degradation, bundlephobia timeout of 5-30s, and sources_failed reporting. This goes well beyond annotations.

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

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

Well-structured with key purpose first, then usage, then details. Slightly long but every sentence adds value. Could be tightened slightly for conciseness but still efficient.

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

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

Despite no output schema, description thoroughly explains return structure: summary block with fields, per-advisory detail, links, and alternative versions. Also covers partial failures and fallback behavior, making it complete for agent understanding.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description adds that version is optional and scoped packages are accepted, but this is minimal additional value beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states it's a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs like 'scan' and 'check', and distinguishes itself from siblings which are unrelated to package scanning.

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

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

Explicitly states when to use: whenever an agent asks about safety, popularity, size, or cost of adding an npm package. It also notes NPM-only in v1 and directs other ecosystems to deps.dev:version directly, providing clear alternative guidance.

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

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

Discloses embedding model (BGE-base-en), chunking method (500-char overlapping windows), character cap (200K chars with truncation flag), and return info (passages with offsets and scores). Annotations already declare read-only/idempotent; description adds rich technical detail beyond annotations.

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

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

Three sentences front-load the core purpose, then add technical details and pairing advice. Every sentence adds value; no fluff. Ideal length for quick comprehension.

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

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

Despite no output schema, description fully covers return values (top-N passages, offsets, similarity scores). Mentions truncation behavior and pairing with sibling. Sufficient for an agent to use correctly with limited context.

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

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

Schema coverage is 100% with good descriptions. Description adds minimal extra value: examples for query parameter and reaffirms 200K char limit. No nested objects, no enums. 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?

Specific verb 'search inside' with concrete examples (SEC 10-K body, article) and resource 'fetched record'. Clearly distinguishes from sibling 'ask_pipeworx_grounded' by stating they pair together. No ambiguity.

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: 'record too big to cram into the prompt' and 'saves context'. Mentions pairing with ask_pipeworx_grounded. Lacks explicit when-not or alternative tools, but the guidance is strong enough.

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

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

Annotations indicate a write operation (readOnlyHint=false) and non-destructive+idempotent behavior. The description adds crucial details: returns new subscription id, OAuth requirement, per-type parameters, delivery mechanics, and webhook signing/auto-disable. No contradictions.

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

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

The description is long but well-structured: core purpose first, then requirements, subscription types with examples, and delivery channels. Every sentence provides unique value; 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?

Given the tool's complexity (3 params, nested objects, 5 types, no output schema), the description covers prerequisites, parameter behavior, delivery options, output, and edge cases (e.g., webhook auto-disable). It is fully sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, and the description enhances each parameter with concrete examples (e.g., items codes for sec_8k, topic for polymarket_edge) and operational details for delivery fields (verification, rate limits). This adds meaning beyond the schema.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id', clearly identifying the action and resource. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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 specifies prerequisites ('Requires a Pipeworx OAuth account'), types of subscriptions, delivery channels, and limitations (e.g., SMS cap, webhook auto-disable). It provides clear context for when to use this tool versus alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive, open-world behavior. The description adds that it returns categorized examples with exact tool+argument shapes drawn from the live catalog, which is valuable 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 a single well-structured paragraph that begins with example queries, then explains the output format and usage. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description clearly defines the return format (category-bucketed example questions with tool+argument shapes). It also covers use cases, the optional parameter, and when to use the tool first, providing complete context for effective invocation.

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

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

The schema description for the single optional parameter is complete (100% coverage). The description adds context by listing the possible values (e.g., 'finance', 'pharma') and explains the behavior when omitted ('full spread').

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 is the onboarding entry point, answering questions like 'What can I ask Pipeworx?' and returns category-bucketed example questions. It distinguishes itself from siblings by being the first tool to use when unfamiliar with Pipeworx capabilities.

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

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

Explicitly recommends using this tool FIRST when the agent does not know what Pipeworx can do, and to learn how to call meta-tools. It also describes when to use the optional topic parameter to focus the results.

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 are present, but the description adds critical behavioral context: the row is 'deactivated (not deleted)' and 'historical events stay available'. It also mentions ownership enforcement, which is beyond annotation info.

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

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

Two sentences, front-loaded with the primary action, no waste. Every sentence adds value.

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

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

The tool is simple (1 required param, no output schema). The description covers purpose, ownership, and effect (deactivation). No gaps.

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

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

Schema description coverage is 100%, so the description adds little extra meaning beyond 'by id'. The schema already explains 'Subscription id (uuid) returned by subscribe.' Baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb (cancel) and resource (subscription). It also distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 'Ownership is enforced — you can only cancel your own subscriptions', providing clear context for when to use. It lacks explicit when-not-to-use or alternative tools, but the context is adequate.

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, open-world, idempotent, and non-destructive. The description adds significant operational context beyond that: the meaning of 'could_not_verify' (check did not happen, carries verification_error, must not be shown as evidence) and 'unsupported' (no source exists). This is critical, non-obvious behavior clearly disclosed. No contradiction.

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

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

The description is dense but well-organized. It leads with purpose and trigger phrases, then explains routing, output format, caveats, and efficiency gain. Every section earns its place—especially the imperative warning about 'could_not_verify'—without redundancy. It is clearly structured and not padded.

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 must explain return values, and it does: the verdict enum, grounded/structured value, pipeworx:// citation, reasoning, and the error semantics for 'could_not_verify'. It also covers the two-parameter schema and the routing logic. For a tool of this complexity, this is a highly complete description.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents 'claim' and 'tolerance_pct' thoroughly with examples. The description adds some context about percent-delta math and the approximately_correct grading, which relates to tolerance_pct, but it does not materially enhance understanding of the parameters beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with explicit natural-language trigger phrases and states a specific verb-object: 'natural-language claim verification against authoritative sources.' It clearly identifies the resource (claims) and action (validate/verify), distinguishing it from sibling tools like ask_pipeworx_grounded or deep_research by its verdict-focused, evidence-based 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?

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance for financial vs. non-financial claims. However, it does not name alternatives or give 'when not to use' exclusions, so it stops short of full 5.

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