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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: routing to over 5,000 tools, filling arguments, returning structured answers with stable pipeworx:// citation URIs, and being a single fast call. This goes beyond the annotations, though it doesn't discuss rate limits or error handling, which would elevate it to a 5.

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 relatively long, but it is well-structured with a clear imperative at the start ('PREFER OVER WEB SEARCH'), followed by use cases, examples, and differentiation guidance. Every sentence serves a purpose, though some repetition could be trimmed. The front-loading is effective.

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 (5,563 tools, 1462 sources) and no output schema, the description covers the essential aspects: routing behavior, citation format, usage guidance, and differentiation from siblings. It could be more complete by mentioning potential limitations or error scenarios, but it is 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?

The input schema has 6 parameters, all aliases for the same question string, with 100% schema coverage. The description provides examples of valid questions and categories of use, but does not add significant meaning beyond what the schema already describes. The schema handles parameter semantics well, so the description provides marginal added value.

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

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

The description clearly states that the tool routes questions to a large set of authoritative sources and returns structured answers with citations. It explicitly says 'PREFER OVER WEB SEARCH' and lists many use cases. It also distinguishes from sibling tools like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists specific query types. It also identifies when to use alternatives (ask_pipeworx_grounded, deep_research) and the conditions for stepping up, which is excellent differentiation.

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=true, openWorld=true, idempotent=true, destructive=false), the description adds significant context: it is a beta version with candidate routing improvements, currently identical to the stable router, used for testing new routing strategies, and has the same response shape and tool set. 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 concise, consisting of three sentences that front-load the beta nature and identity with the stable version. Every sentence provides essential information: what it is, its current state, and how to use it. 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?

Given the complexity (a beta router with many tools, no output schema), the description covers the key aspects: purpose, usage, current state, and relationship to the stable version. It lacks details about the output format or error scenarios, but since it is identical to ask_pipeworx and the agent can reference that, it is largely complete. A minor gap for a fully comprehensive 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%, with all six parameters (q, text, input, query, prompt, question) documented as aliases for the natural language question. The tool description does not add parameter-specific details beyond noting 'same arguments' as ask_pipeworx. Since the schema already fully describes the parameters, the description adds minimal value here, earning a 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?

Clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,563 tools and arguments. Distinguishes from siblings by specifying it is the experimental edge, while stable ask_pipeworx and ask_pipeworx_grounded are different variants. The description explicitly explains what the tool does and its current state (no candidate active, matches stable).

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. Also clarifies that it is a full working router, not a fallback, and that currently it matches the stable version. Provides clear when-to-use and alternative distinction.

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 true and destructiveHint false. The description adds significant context beyond annotations: it explains the refusal mechanism with specific reasons (not_in_source, no_tool_match, etc.), the extraction process, and the exact return format including evidence. 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 comprehensive yet concise, with no wasted sentences. It front-loads the core purpose and trade-offs, then provides detailed behavior and return format in a structured way. 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?

Given the tool's complexity (6 params, no output schema, but high annotation coverage), the description is complete: it covers purpose, alternatives, usage guidelines, behavioral details, refusal reasons, and return structure. There are no gaps for an agent to make false assumptions.

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 explaining that the question parameter accepts multiple aliases (query, q, prompt, text, input), which is a useful semantic detail not captured in the schema. It also implies the question is in natural language. However, the description does not elaborate on the content or style of the question beyond that.

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

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

The description explicitly states this is a 'hallucination-resistant answer mode for high-stakes reads', specifying the verb 'ask_pipeworx_grounded' and resource 'Pipeworx', and clearly distinguishes it from the sibling tool 'ask_pipeworx' by detailing the grounded extraction process and refusal mechanism.

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

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

The description provides explicit guidance on when to use this tool ('high-stakes reads', 'financial verdicts, legal claims, medical lookups, public statements') vs the alternative ('prefer ask_pipeworx for casual lookups'), and even notes the cost trade-off ('one extra LLM call'). This fully differentiates from 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 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral details: return format (findings packet with evidence, confidence, source, timestamps, stable citations, gaps, contradictions), hop fields, semantic excerpting, time expectations (15-90s), and depth mechanics. No contradictions with annotations.

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

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

The description is dense and front-loads critical info (account requirement, alternative tool). However, it is quite long with technical detail (e.g., 'gap recovery', 'contradictions[] scan', 'semantically excerpted') that, while valuable, could be tightened. Still earns a 4 for being well-structured despite verbosity.

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 return values (evidence, confidence, source, timestamps, citations, gaps, contradictions, hop field) and explains edge cases (e.g., 'never invented', citation_uri only when fetchable). Given the tool's complexity and large sibling set, the description is thorough and leaves no critical 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 coverage is 100% with good descriptions for both parameters. The tool description adds nuance (e.g., 'Broad/multi-part is fine' for question, explains depth facets and iteration) but does not significantly expand beyond what the schema already provides. Meets baseline but adds marginal value.

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

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

The description clearly identifies the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources ... in ONE call.' It specifies the verb ('research'), resource ('structured data sources'), and differentiates from siblings like ask_pipeworx and open-web search, making the purpose unmistakable.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also mentions account requirements and paid tiers, giving clear context for usage decisions.

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 declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds significant behavioral context: fans out across multiple sources in one parallel call, notes the patents API sunset (soft-fails until reactivated), explains the news fallback (GDELT→GNews), and lists all returned fields. 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 substantial but every sentence adds value. It is front-loaded with example queries, then lists data sources and return fields. While not terse, it efficiently conveys all necessary information without redundancy. A slightly more structured format (e.g., bullet points) could improve scannability.

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

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

No output schema exists, so the description fully compensates by enumerating all return components (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news with fallback, LEI). It covers edge cases (patent soft-fail, name requirement) and performance (parallel call).

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 meaning by clarifying that 'type' only supports 'company' (with 'person/place coming soon') and that 'value' must be a ticker or zero-padded CIK, reinforcing that names are not supported. This context exceeds the schema descriptions.

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

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

The description explicitly states it returns a full cross-source profile for US public companies, with concrete example queries ('tell me about X', 'research Acme') and a detailed list of returned data (SEC, XBRL, patents, news, LEI). It clearly distinguishes from sibling tools like resolve_entity (name resolution) and compare_entities (comparison).

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

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

The description instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicitly states 'names not supported (use resolve_entity first if you only have a name).' This provides clear when-to-use and when-not-to-use with an alternative.

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

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

Annotations already indicate 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?

Annotations already indicate read-only, idempotent, non-destructive. The description adds extensive behavioral detail: returned fields (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning with two cases, temporal_alignment, skipped_cross counters). This far exceeds 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?

The description is dense but well-structured: definition first, then modes, then response fields, then safety clarifications. Every sentence adds necessary information, though slightly verbose for the amount of detail.

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

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

Given the tool's complexity (cross-venue, multiple modes, safety conditions), the description covers inputs, outputs, error cases, temporal alignment, and limitations comprehensively. No output schema exists, but description explains return structure sufficiently.

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 explaining the topic parameter lists the 10 macros, and that explicit tickers override topic-mapped sides. Examples in schema reinforce this.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and separates this from sibling tools like polymarket_arbitrage by focusing on spread computation.

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

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

The description explains when to use the tool, including pre-mapped topics for quick access and explicit parameters for custom pairs. It warns that most pre-mapped topics currently return compatibility warnings, implying when not to rely on shortcuts. However, it does not explicitly contrast with alternative tools for similar tasks.

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 discloses key behaviors beyond the annotations: it cascades through multiple internal endpoints, degrades gracefully when GLEIF or OpenFIGI are unavailable (returning EDGAR identifiers), and explicitly returns unresolved identifiers under an 'unresolved' field. This adds significant behavioral context that annotations alone do not provide, and does not contradict any annotation.

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 immediate examples and a strong usage directive ('Use FIRST'). Every sentence adds distinct value—input formats, output details, degradation behavior, and source coverage. Despite its length, it is efficiently structured and avoids redundancy, earning its place 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?

Given the tool's complexity (multi-source entity resolution), the absence of an output schema, and two required parameters with an enum, the description provides thorough coverage: it explains the full return value structure, source provenance, graceful degradation, and what unresolved identifiers look like. No gaps remain for the intended use case.

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?

Despite the input schema already having 100% description coverage, the description enriches parameter semantics by explaining what each value type resolves to (e.g., ISIN resolves to legal entity via GLEIF, ticker implies company with LEI/FIGI enrichment). It also details the output structure (CIK, ticker, LEI, ownership, etc.) and the fallback behavior, adding value well beyond the schema's terse descriptions.

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

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

The description clearly states it resolves a user-spoken name to canonical/official identifiers, with explicit examples like 'What's the ticker for…' and 'look up the ID for…'. It specifies supported types (company, drug) and distinguishes the tool's role as a first step when a name is known but an ID is needed, setting it apart from sibling tools like compare_entities or entity_profile.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also details the input formats (ticker, CIK, ISIN, name for companies) and the cascading internal lookups that replace manual multi-step resolution, giving strong contextual cues for tool selection.

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

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

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.