rickmorty

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds meaningful behavior beyond annotations: default model is free, calling Anthropic requires a BYO key and 'you pay Anthropic directly for those calls,' and the return payload includes per-model {score, confidence, signals, raw_response} plus a combined view. This extra context justifies a score above 3, though it doesn't fully detail rate limits or cancellation behavior.

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

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

The description is three sentences with no filler. It front-loads the core purpose and output format, then covers cost and use cases. Every sentence adds distinct value, making it concise and well-structured.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description covers all essential aspects: purpose, use cases, parameters (especially models and _apiKey), return format, and cost implications. The annotations cover safety. No major gaps remain for an agent to decide when and how to invoke the tool.

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

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

Schema description coverage is 100%, so a baseline of 3 is appropriate. The description adds useful semantics beyond the schema by naming the default model (Workers AI Llama-3.3-70b), clarifying that it is free, and explaining that `_apiKey` is required only for Anthropic and that the user pays directly. This enhances understanding of the `models` and `_apiKey` parameters beyond their schema descriptions.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This specifies the verb (probe), resource (LLMs), and output (visibility score). It also distinguishes itself from siblings like scan_competitor_ai_presence by noting per-model scores and a combined view.

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

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

The description provides clear use-case context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives or exclusions, but the use cases are specific enough to guide an agent. This is above baseline but stops short of a 5 because no sibling comparison is offered.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds meaningful behavioral context: it routes to one of 5,529 tools, fills arguments, returns a structured answer, and provides stable pipeworx:// citation URIs. It also notes works on every tier and one fast call, which are important non-obvious operational traits.

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

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

The description is longer than average but front-loads the most critical directive ('PREFER OVER WEB SEARCH') and uses bullet-like examples effectively. Some redundancy exists ('START HERE' reinforces earlier statements, and 'Use whenever...' examples overlap with the opening), but the overall structure is organized and purposeful, earning a high score.

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

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

For a high-complexity, general-purpose routing tool with no output schema, the description is remarkably complete. It explains what it returns (structured answer with stable pipeworx:// citation URIs), how it works internally (routes to the right tool, fills arguments), when to prefer it, and when to escalate. No critical gaps remain for an agent to invoke it 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% with all six parameters described as aliases of 'question', so the baseline is 3. The description adds value by giving concrete examples of valid natural-language questions ('current US unemployment rate', 'Apple's latest 10-K'), which clarifies the intended semantic range of the 'question' parameter beyond the schema's generic examples.

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 ask_pipeworx as the default entry point for factual questions, with a specific verb 'routes' and resource scope across 5,529 tools and 1,455 sources. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the fast, general-purpose option.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE', 'Use whenever the user asks...') and when-not-to-use guidance by naming step-up alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It also covers breaking-news exceptions, making the decision framework exceptionally clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context about the beta status, candidate routing tests, current no-op state, and that results are compared against stable router. 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 moderately long but each sentence serves a purpose: what it is, current state, usage guidance, and reassurance about fallback. It is well-structured and front-loaded with the core identity. Slightly verbose for a simple tool but justified by the nuance of beta status.

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 (beta router with dynamic behavior) and lack of output schema, the description covers the current state, usage, and response shape ('same response shape'). It could be slightly more explicit about what happens when a candidate is active, but the current no-op status is clear.

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

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

Schema covers 100% of parameters with detailed alias descriptions. The description mentions 'same arguments' but doesn't add specific syntactic or semantic details beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly identifies this as 'Beta version of ask_pipeworx', a universal router with the same 5,529 tools and response shape. It distinguishes from siblings by explicitly naming ask_pipeworx and noting the experimental edge. The verb 'ask' and resource 'pipeworx' are clear.

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

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

It explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It implies ask_pipeworx is the stable alternative and clarifies this is a full working router, not a fallback. However, it doesn't explicitly say 'use ask_pipeworx for stable results' as a 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: it explains the extraction uses ONLY the tool result, describes the exact return structure including evidence quotes and confidence, and enumerates explicit refusal reasons with values. No contradiction 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 front-loaded with the core purpose ('Hallucination-resistant answer mode') and then compactly covers routing, return schema, refusal reasons, usage context, and cost tradeoff. Every sentence provides distinct value; no filler or redundant repetition.

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 compensates by specifying both success and refusal return objects, including fields like evidence, confidence, source, and refusal_reason. It also explains cost and sibling preference, making the tool's context and limitations complete for the agent.

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

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

Schema description coverage is 100% and all six parameters are aliases for 'question', so the schema already fully explains the single required input. The description adds no additional parameter details, but with complete schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' that routes through the same tool selection as ask_pipeworx, then extracts the answer only from the tool result. It explicitly distinguishes from ask_pipeworx by grounding and refusal behavior, and makes the distinction from casual lookups clear.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', along with concrete examples. It also states when not to use: 'prefer ask_pipeworx for casual lookups' and quantifies the cost tradeoff ('Costs one extra LLM call'), giving clear selection criteria.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations. It discloses parallel fan-out, classifier categories, resolver contract with match confidence, parent-event extraction, news fallback flags, low-confidence short-circuit, closed-market handling, wide-spread illiquidity warnings, and resolution-rule risk with audited arb-bot ledgers. This is rich behavioral context that annotations alone do not provide.

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

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

The description is long but front-loaded with purpose and use cases, then organized into clearly labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence contributes to operational understanding; the length is justified by the tool's complexity, though it could be trimmed slightly.

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

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

With no output schema, the description compensates by detailing all result fields: market (best_bid/ask, liquidity, price change), analysis (model prob, edge), evidence, resolver contract (match_confidence, alternatives), parent_event, news fields, and safety statuses. It also covers error paths and fallback behavior, making it complete for an agent to trust and handle results.

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

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

Schema coverage is 100% and each parameter already has a detailed description. The tool description adds examples for the market parameter (slug, URL, question text) but doesn't add new semantics for depth or include_raw beyond the schema docs. The extra context in the description is mostly about behavior, not the parameters themselves.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb, resource, and single-call promise. It clearly states the input forms (slug, URL, question text) and distinguishes its use from siblings by framing use cases like 'should I bet on X' and 'is there edge in Z', which differ from arbitrage or validation tools.

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

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

The description explicitly names use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also gives fan-out examples for different bet types. However, it does not explicitly name sibling tools to avoid or state when not to use it, though the context makes those distinctions clear.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, result sorting by primary metric, and return of citation URIs. This adds substantial behavioral context without contradicting annotations.

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

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

The description is dense but well-structured: trigger examples first, then usage preference, then type-specific details, then output characteristics. Every sentence adds value with no fluff, and key guidance is front-loaded.

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

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

For a tool with complex behavior and no output schema, the description covers triggers, entity count limits, alternative approaches, data sources, fiscal-year nuances, sorting, and return format. It is fully self-contained for an agent to invoke correctly.

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

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

Despite 100% schema coverage, the description enriches parameter meaning by explaining what each 'type' value does (company pulls 10-K financials; drug pulls adverse-event counts) and gives examples for 'values'. This goes beyond the schema's basic field descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with specific verbs ('compare', 'rank') and resources. It distinguishes itself from sibling tools by explicitly positioning against sequential single-entity 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?

Provides explicit trigger phrases ('Compare X and Y', 'which is bigger') and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies when to use company vs drug types, giving unambiguous usage direction.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses substantial behavioral traits: account/payment requirements, depth-specific mechanisms (gap recovery, lead chasing, contradictions[]), output packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] behavior, citation_uri resolvability, semantic excerpting, and expected latency ranges. No contradiction with annotations.

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

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

The description is long but information-dense; every sentence carries unique operational details. It is front-loaded with the account requirement and alternative, and uses semicolons and examples to structure complex behavior. While slightly verbose, it avoids redundancy and earns its length for such a multifaceted tool. A score of 4 acknowledges the length but rewards the efficient packaging.

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 (1455 sources, 5529 tools, parallel routing, depth levels, output packet, gaps, contradictions, citations) and the absence of an output schema, the description must explain return values and limitations. It fully covers expected outputs, cited evidence format, resolution guarantees, and practical constraints like latency and account tiers. It also addresses edge cases (breaking news returning empty gaps), making it highly 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% (both parameters have descriptions), so baseline is 3. The description enriches parameter semantics with concrete details: quick=3 facets, standard=5 (adds gap recovery + contradictions), thorough=8 (adds iterative hop). It also clarifies that 'question' can be broad/multi-part, which aligns with the schema's description but adds depth on how decomposition works. 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 the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It distinguishes itself from siblings by explicitly saying it is 'NOT open-web search' and contrasting with ask_pipeworx for single lookups and breaking news. The verb 'research' and resource are specific, and the scope is well-defined.

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.' It also mentions account requirements and alternatives for unsigned users ('If you are not signed in, use ask_pipeworx instead'). It gives concrete examples of suitable queries, making usage criteria clear.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: it explains the return format (top-N tools with names, descriptions, full input schemas, curated examples) and that results are ready to call directly with no second schema lookup. It does not explicitly mention side effects, but given the annotation coverage, this is sufficient.

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: purpose, domain list, and behavioral/usage guidance. The domain list is long but useful for quick scanning. The description is front-loaded with purpose and efficiently combines return behavior with a call-to-action. Slightly verbose with the exhaustive data-domain list, but every piece serves a 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?

The tool is a meta-discovery tool with no output schema, so the description compensates by explaining what the return payload includes (names, descriptions, full input schemas with examples) and that no second lookup is needed. It also provides a clear use case (call first when many tools are available). It does not mention pagination or error behavior, but for this tool type, the coverage is strong.

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 including aliases for query and the limit parameter. The description does not add meaningful parameter-level semantics beyond what the schema provides; the phrase 'describing the data or task' loosely maps to the query parameter but is already captured in the schema description. 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 starts with a specific verb+resource: 'Find tools by describing the data or task.' It clearly enumerates the covered domains and explicitly frames itself as a discovery/meta tool, distinguishing it from the sibling tools that perform specific tasks (e.g., deep_research, validate_claim).

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies when-not-to-use: 'not just one answer' indicates that if you already know the exact tool, you should call it directly. However, it does not name specific alternative tools or provide an explicit exclusion list, so it falls just short of a 5.

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

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

While annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavior: it fans out across multiple sources, returns specific fields with limits (up to 5 filings), discloses the USPTO PatentsView sunset with soft-fail, and mentions GDELT→GNews fallback. No contradiction with annotations.

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

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

The description is long but front-loaded with example queries and a clear directive. Each clause about return fields and fallbacks is informative, though some details (e.g., the specific fundamentals list) could be trimmed if an output schema existed. 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?

With no output schema, the description thoroughly enumerates all return components (CIK, filings, fundamentals, patents, news, LEI) and their sources/limits. It also covers error behavior (soft-fail), which is essential for an agent to know.

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

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

The schema already describes both parameters and their format. The description reinforces the ticker/CIK format and adds the 'US public company' scope, which is not in the schema. It also provides concrete examples, though the opening examples use names that conflict with the later 'names not supported' warning.

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

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

The description opens with concrete user phrasings, then defines the tool as 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools like resolve_entity and single-pack lookups by emphasizing the holistic aggregation and the preferred usage for holistic questions.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives an alternative: 'use resolve_entity first if you only have a name.' This provides both positive and negative usage guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds the context that it deletes 'previously stored memory' and mentions 'sensitive data', but does not go beyond what the annotations and the verb 'delete' already imply. 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 two sentences, front-loaded with the action, and includes essential usage context. No wasted words or redundancy.

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

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

The tool is simple with one parameter and no output schema. The description covers purpose, usage, and relationships to siblings. It does not cover edge cases like deleting a non-existent key, but that is minor 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?

The schema covers the single 'key' parameter with 100% description coverage. The description only says 'by key', adding no new parameter-level detail beyond the schema. A baseline score is appropriate since the schema does the heavy lifting.

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 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes from sibling tools like remember and recall by focusing on deletion, making its purpose unambiguous.

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

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

The description explicitly provides usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also points to complementary tools 'remember and recall', giving clear guidance on when this tool is appropriate 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the operational workflow: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also states the output is a single text blob for site-root placement, which adds meaningful behavioral context.

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

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

Three sentences front-load the primary purpose, provide usage context, and describe output format. Every sentence earns its place; no fluff or redundant restatement of the name or title.

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 (2 params, no nested objects), has rich annotations, and the description covers purpose, usage, and output format. No output schema exists, but the description explains exactly what the returned blob contains. This is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with clear parameter descriptions for 'url' and 'max_links'. The description's mention of 'extracts title/description/key links' implicitly relates to max_links, but it doesn't explain parameter syntax, constraints, or defaults beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes this from siblings by focusing on llms.txt generation, and specifies the output format and audience (AI crawlers). No ambiguity about what the tool accomplishes.

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

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

The 'Useful for' section lists concrete use cases (client sites, own projects, competitor auditing), providing clear context for when to invoke this tool. It does not mention alternatives or exclusions, so it stops short of a full 5, but the guidance is actionable.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description adds value by specifying the return fields, default active-only behavior, and caller scoping. It goes beyond just restating the safety profile.

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, and no redundant text. Every sentence contributes purpose, return details, and usage guidance.

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

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

With no output schema, the description explicitly lists the returned fields, default behavior, and use cases. The one parameter is fully described in the schema, making the overall tool description complete for its 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% for the single parameter include_inactive, with a clear schema description. The tool description does not add extra parameter context, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It also distinguishes from siblings like subscribe/unsubscribe by focusing on the read-only listing action.

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

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

It provides explicit when-to-use scenarios: review monitoring before adding more or find an id to cancel. It doesn't explicitly name alternatives, but the usage context is clear given 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 are all false and provide no meaningful safety context, so the description fully carries the behavioral burden. It discloses the claim_token workflow, rate limiting (5 per identifier per day), daily reading by the team, and the fact that it's free and doesn't count against quota—valuable details 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 longer than average but every sentence serves a purpose: purpose, usage, exclusions, token workflow, team signal, rate limit, quota. It is front-loaded with the core purpose and well-structured, though slightly verbose.

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

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

With no output schema, the description covers the important return behavior (claim_token for anonymous filing) but does not explicitly state what a successful submission returns when an account is present. Despite this minor gap, it covers context, exclusions, and operational constraints 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 description coverage is 100%, so the schema already documents every parameter. The description adds an example of claim_token usage ('pipeworx_feedback({claim_token:"pwfb_…"})') but this largely duplicates the schema's own description. No substantial new meaning is added.

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 ('Tell the Pipeworx team') and resource ('something broken, missing, or needs to exist'), immediately clarifying the tool's function. It enumerates feedback types (bug, feature/data_gap, praise) which distinguishes it from all sibling tools that are research or subscription related.

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

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

Explicit 'Use when' conditions are given for each feedback category, including examples like 'tool returns wrong/stale data' and 'tool you wish existed isn't in the catalog'. It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and instructs users on what to do otherwise, leaving no ambiguity.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This goes beyond annotation hints and gives the agent important freshness and privacy details.

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

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

The description is three sentences: a main statement, a list of use cases, and a data-source/caching note. It is front-loaded and every sentence earns its place, with no fluff or redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers the core behavior, use cases, data source, privacy, and caching. It is sufficiently complete for an agent to decide to invoke the tool and set expectations.

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

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

Schema coverage is 100% for the single 'window' parameter, so the description does not need to compensate. The description only repeats the window options without adding new meaning beyond the schema's own enum and explanations, aligning with the baseline for high schema coverage.

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

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

The description clearly states the tool returns trending usage data ('top tools, top packs, and total call volume') from other AI agents over a recent window. This is a specific verb+resource combination that distinguishes it from siblings like discover_tools or 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 provides three explicit use cases ('Useful for: (1) discovering... (2) confirming... (3) seeing whether...'), which gives clear context for when to use the tool. However, it does not mention when not to use it or name alternatives, so it stops short of a 5.

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

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

Annotations declare read-only, non-destructive behavior, but the description adds substantial behavioral context: the >3pp threshold for partition signals, placeholder filtering (>20% fraction returns null), the Jaccard ≥0.30 semantic anchor, skipped_low_similarity output, and the fill-check pricing against CLOB depth with thin_legs. No contradiction with annotations.

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

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

Although lengthy, every sentence contributes unique information. The structure uses clear section-like headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex logic, and the opening sentence immediately states the tool's purpose. This density is appropriate for a tool with two modes and multiple edge cases.

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

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

Given the tool's complexity and absence of an output schema, the description covers all essential aspects: input modes, thresholds, filtering rules, response structure (opportunities[], partition_check, gap_pp, suggested_trade), and the fill-check caveat. It also documents failure modes (skipped_low_similarity, null arb signal) and cross-event advantages. No obvious 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?

Even though schema description coverage is 100%, the tool description adds meaningful semantics: it explains the conceptual difference between event and topic modes, provides concrete example values ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), notes that full URLs are accepted, and describes how parameters map to distinct scan strategies.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (trending_scan, event, topic) and differentiates from sibling tools by naming the exact technique and scopes.

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 tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names a direct alternative: 'For custom sizing use polymarket_fill_risk', and provides a critical negative-use case (do not trade when realizable_edge_pp ≤ 0).

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 context: caching at the KV level for 1 hour keyed on all knobs, detailed response structure (by_segment, fed_candidates, _diagnostics), model-specific logic (e.g., lognormal barrier, Kelly caps, favorite-longshot bias corrections), and warnings like 'your edge may already be in the price.' This goes far 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?

The description is dense but well-organized with bolded section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It front-loads the core purpose in the first sentence. While it's a long paragraph, every sentence earns its place given the tool's complexity. Minor inconsistency: claims FIVE MODEL FAMILIES but only lists four (crypto_price, news_momentum, partition_overround, basket trade).

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 is exceptionally complete for a complex tool with no output schema. It explains all three response segments, model family details, parameter behavior, diagnostics (funnel counters, filter_skips), caching, and caveats (Fed signal unreliability). The agent gets a full mental model of what to expect and how to interpret empty segments.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the rationale behind key parameters: slippage_pp (zero-fee exchange but bid/ask eats 20-50bp), min_liquidity/max_spread_pp (tradeable-edge filters), and min_partition_leg_kelly (interaction with partition overlround Kelly behavior). This enriches understanding beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly defines the tool's purpose and distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker by emphasizing Pipeworx data disagreement and model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT).

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today"' and explains when to use it (discover opportunities without paging hundreds of markets). It also provides context on what is excluded (Fed bets) and why. However, it does not explicitly name alternative tools or state when NOT to use this tool in favor of a sibling.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds significant behavioral details: the 60-day snapshot TTL limit, that snapshots are written only on cache-miss (gaps mean no scan), decay computed from daily closes of edge_pp_net (not intraday), and the signed meaning of edge_pp_net (negative = SELL YES). This goes well beyond annotations and fully discloses operational constraints.

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 starts with the core purpose and question, then lists arguments, response fields, and limitations in a logical flow. Every sentence adds necessary information, with no fluff or tautology. It is front-loaded with the most important context (what problem it solves) and uses clear labels like 'RESPONSE:' and 'LIMITS:' to structure the information.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly explains the return structure: tracked[] entries with full time-series, first_seen, trend categories, and decay rate; expired[] with lifespan_days; and snapshot_dates[]. It also covers limitations like TTL and snapshot gaps. This is comprehensive for a 2-parameter tool with complex telemetry output.

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

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

Schema coverage is 100% for both parameters, with descriptions for days and window already specifying defaults and ranges. The tool description mostly echoes the schema ('days (lookback, default 14, max 30)' and 'window (snapshot family, default "1wk")'), adding only a slightly clearer term 'snapshot family'. Since the schema already does the heavy lifting and the description adds minimal new meaning, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: tracking edge persistence and decay from daily polymarket_edges snapshots. The phrase 'Answers "how long has this edge existed and is it shrinking?"' directly conveys its purpose and differentiates it from sibling tools like polymarket_edges which likely focuses on current edges. The specific verb 'answers' and resource 'polymarket_edges snapshots' make it unambiguous.

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

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

The description provides clear context for when to use the tool: when assessing whether an edge is new or decaying, with the example that a fresh wide edge and a 3-week-old wide edge are different trades. It does not explicitly name alternative tools to use instead, but the purpose implies it is for historical/telemetry analysis rather than current edge lookup. No explicit exclusions are given.

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, open-world, idempotent, non-destructive. The description adds substantial behavioral context beyond that: it describes internal logic ('walks the ladder'), return values (top_of_book, vwap_fill_price, etc.), and risk semantics (partial basket fills convert an arb into an unhedged directional position). It also explains the meaning of verdicts and the forced_directional_risk field. This is a rich, honest disclosure of behavior that goes far beyond the annotation hints.

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

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

The description is long, but every sentence earns its place for a complex two-mode tool. It is well-structured with capitalization labels (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) that improve scannability. It could potentially be tightened, but the density is justified by the number of return fields and mode-specific rules.

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

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

With no output schema, the description must explain return values, and it does thoroughly: for single-market it lists top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict; for basket it lists theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers edge cases (thin books, partial fills) and the dominant loss mode. Given the tool's complexity, this description is complete and self-sufficient.

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

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

Schema coverage is 100%, but the description adds critical mode-dependent semantics. For size_usd it clarifies 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also explains side defaults for basket (auto based on partition sum) and the accepted values. These clarifications are essential for correct invocation and are not fully conveyed by the schema alone.

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 and informative purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates this tool from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges, and describing what this tool adds (checking fill feasibility). The verb 'check' plus the resource (Polymarket CLOB depth) makes 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 usage guidance: 'REQUIRES one of market or event', 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket) and when each is appropriate. The guidance directly points to alternatives (sibling tools) and gives a rule of thumb, making it easy for an agent to decide when to invoke this tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters in detail. It even explains what happens when bet shapes are non-equivalent, providing the agent with crucial edge-case knowledge.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). The opening sentence is an effective summary, and every section provides essential information. However, the final sentence repeats a point already made ('pre-mapped ≠ tradeable'), adding slight redundancy.

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

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

With no output schema, the description compensates by detailing the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning conditions) and the meaning of temporal_alignment. It also explains skipped_cross_type/subtype counters. This is exceptionally complete for a tool of this complexity.

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

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

The input schema lists parameters with brief descriptions, but the tool description enriches them substantially: it explains the 'topic' shortcut list, the override precedence of kalshi_event_ticker/polymarket_event_slug, and provides concrete examples like 'KXFED-26OCT'. This goes well beyond the schema and significantly helps the agent construct valid calls.

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

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

The description opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then details two invocation modes (topic shortcuts and explicit event identifiers), clearly distinguishing itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on cross-venue comparison rather than single-venue trading signals.

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

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

The description gives clear guidance on when spreads are meaningful ('when the bet shapes are equivalent that delta is a real signal') and warns that most pre-mapped topics return compatibility_warning and are not tradeable. However, it does not explicitly name alternative tools for same-venue arbitrage or single-venue edge detection, so it falls short of a full 5 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds valuable context by describing scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the relationship to remember/forget, exceeding the annotations' coverage.

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

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

The description is concise and front-loaded: the first sentence states the core function, followed by usage context, scoping, and sibling relationships. Each sentence earns its place, and there is no redundant phrasing or filler.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all essential aspects: core functionality, return behavior (value vs. list of keys), scoping, and companion tools. It is complete enough for an agent to use confidently.

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

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

The schema already describes the 'key' parameter well (100% coverage), but the description adds relatable examples ('user's target ticker, an address, prior research notes') that clarify what kinds of values are typical to store and retrieve. This goes beyond the schema's generic description without being verbose.

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

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

The description states the exact action ('Retrieve a value previously saved via remember, or list all saved keys') with clear resource and scope, and distinguishes from siblings by explicitly naming 'remember' and 'forget' as complementary tools. The purpose is unambiguous and immediately actionable.

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

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

It provides clear usage context ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and explains the optional key argument behavior. It does not explicitly list alternatives or when-not-to-use scenarios, but the context is clear enough to guide 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 only state read-only and idempotent, but the description adds crucial behavioral details: the persisted feed, the mark_read side effect (so the next call only shows newer events), and the contents of each returned alert (source, citation_uri, raw payload). This goes well beyond what annotations provide and is fully transparent about the side effect.

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

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

The description is four sentences, front-loaded with the primary purpose, and every sentence adds useful information. It avoids redundancy and includes the HTTP alternative without bloat.

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 explains the return payload, filter parameters, mark_read state behavior, polling suitability, and an alternative access method. It fully covers what an agent needs to use the tool correctly and safely, with no major 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?

The input schema already provides complete descriptions for all five parameters (100% coverage). The description adds a small example (filter by type 'sec_8k') and clarifies the mark_read effect, but these are marginal additions over the schema. Baseline 3 is appropriate since the schema carries the heavy lifting.

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

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

The opening sentence 'Pull fired events from your subscription feed' clearly states the verb and resource, and 'Returns the most recent alerts the evaluator has written to your persisted feed' specifies the scope and source. This distinguishes it from siblings like list_subscriptions and recent_changes.

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

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

The description gives clear context by explaining filter options, the mark_read behavior, and that polling works fine. It also mentions an alternative HTTP endpoint 'for scripts and dashboards', which provides context for when to use this tool interactively versus that feed. However, it does not explicitly exclude or contrast with 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses key behavioral traits: fans out in ONE parallel call, GDELT→GNews fallback ('GNews when rate-limited or 5xx'), and USPTO soft-fails due to API sunset. It also explains the return structure (changes[] grouped by source, total_changes, citation URIs). This is exceptionally transparent.

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

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

The description is dense but every sentence earns its place, covering purpose, sources, fallback, parameter formats, output, and alternative tool. It is somewhat long, but the structure is logical and front-loaded with example queries. It could be more compact, but information density justifies the 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 having no output schema, the description clearly explains the return format (changes[] grouped by source + total_changes + citation URIs). It also addresses potential failure modes (GDELT fallback, USPTO soft-fail) and parameter edge cases. Given the tool's complexity, this description is remarkably complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical nuance by giving examples of `since` formats ('2026-04-01' or '7d') and recommending '30d' or '1m' for typical monitoring. While minor, this goes beyond the schema's field descriptions by providing usage guidance.

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

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

The description states the tool provides a 'change feed for a company in the last N days/weeks/months' and explicitly names the sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from entity_profile by stating 'Use entity_profile instead when you want the static profile...' This is a specific verb+resource with clear 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 opens with natural-language triggers like 'What's new with X' and 'latest on Y', giving clear when-to-use cues. It explicitly advises using entity_profile for static profiles, and notes the parallel-call benefit. This provides strong alternatives and practical context.

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

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

Beyond the annotations, the description adds key behavioral context: key-value scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions, and the pairing with recall/forget. It doesn't mention overwrite behavior, but the annotation idempotentHint already covers repeatability.

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

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

Four sentences, front-loaded with the core purpose, followed by use cases and key details. Every sentence earns its place; no wasted words.

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

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

For a simple 2-parameter tool with no output schema and good annotations, the description delivers complete context: purpose, usage, storage model, persistence, and relationship to siblings. Nothing essential is missing.

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

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

Input schema covers 100% of parameters with clear descriptions and examples. The description adds no new parameter-level semantics, so it earns the baseline of 3.

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

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

The description opens with a specific and clear statement: 'Save data the agent will need to reuse later.' It identifies both the action (save) and the resource (data for reuse), and it differentiates itself from siblings by explicitly mentioning pairing with 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?

Provides explicit usage guidance with examples ('Use when you discover something worth carrying forward...') and names alternatives ('Pair with recall to retrieve later, forget to delete'). It implies when not to use (when you need retrieval or deletion) but does not provide an explicit exclusionary statement.

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

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

The annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, but the description adds substantial context: it discloses that unresolved identifiers are stated explicitly under `unresolved`, that LEI/FIGI enrichment degrades gracefully if external sources are unavailable, and that each call cascades through multiple internal endpoints. This 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 longer than the ideal but is well-structured: it starts with example queries, states the core purpose, then uses 'SUPPORTED TYPES' to organize company vs. drug details, and ends with degradation/cascade notes. Every sentence adds value, but the density of information makes it slightly less concise than the 5-point benchmark.

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 two entity types and multiple data sources, the description is highly complete. It covers input formats, output identifiers, source provenance, failure handling (unresolved fields), and graceful degradation. There is no output schema, so the description adequately explains what the tool 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?

The input schema already describes both parameters completely (type with enum, value with format examples). The description repeats the accepted inputs ('ticker, CIK, or company name' for company; 'brand or generic name' for drug) but adds no new semantic details beyond what the schema provides. Therefore, baseline 3 is appropriate.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with concrete examples like 'What's the ticker for…' and 'find the CIK for…'. It explicitly lists supported types (company, drug) and the identifiers returned, making its purpose unambiguous. It also distinguishes itself from sibling tools by emphasizing it provides IDs other tools require as input.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups, clarifying its utility. However, it does not name specific alternative tools or state when not to use it, so it stops short of a full when/when-not comparison.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds meaningful context: that it probes each entity with ai_visibility_check, ranks results, and returns score/confidence/signal density. It also hints at auth needs via the _apiKey parameter, which is beyond structured annotations.

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

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

Three concise sentences: front-loaded with the main action, then the method, then the use case and output. Every sentence adds value with zero redundancy.

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

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

With no output schema, the description adequately explains return values (ranked list, score, confidence, signal density) and the probing flow. It doesn't detail score calculation or potential latency, but for a comparison tool this is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces that the first entity is the subject and entities are compared, but adds little beyond the schema's parameter descriptions. It does clarify the 'your brand + N competitors' framing, which is a slight enhancement.

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 compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility'). It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (generic) by explicitly mentioning it probes each entity and ranks by score.

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 a clear use case ('competitive AI-marketing audits') and an example query, implying when to use this vs a single-entity tool. However, it does not explicitly name alternatives or state when not to use it, so a small gap remains.

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

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

The description adds meaningful behavior beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) by disclosing partial failure degradation, a 5-30s first measurement latency, and the sources_failed field. It also describes the return structure, which is essential since there is no output schema. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, usage, return fields, ecosystem scope, and failure/latency behavior. It is front-loaded with the core purpose and structured logically, avoiding 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 no output schema, the description enumerates the exact return fields (summary block, advisories, links, versions), explains edge cases (first measurement latency, partial failures), and clarifies ecosystem boundaries. This is sufficient for an agent to understand and invoke the tool correctly.

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

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

The input schema already covers both parameters with descriptions and 100% coverage: package name and optional version with default to latest. The description does not add significant parameter-specific meaning beyond this; it reinforces the npm context but relies on the schema for detailed semantics, which is acceptable given high schema coverage.

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

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

The description clearly states the tool's purpose: a composite one-call check for evaluating an npm package, aggregating license, advisories, and bundle metrics from deps.dev and bundlephobia. It distinguishes itself from siblings like bet_research or validate_claim by specifying this is a package-focused analysis for npm only, with clear mention of the ecosystem limitation.

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

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

Explicit usage examples are provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also offers an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This directly tells when to use this tool vs alternatives.

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

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

The description goes well beyond the annotations by disclosing technical behaviors: BGE-base-en embeddings, cosine over 500-char overlapping windows, a 200K char cap with truncation flagging, and that results include character offsets and similarity scores for verification. This is rich behavioral detail that annotations alone would not convey.

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

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

The description is long but every sentence adds new information: purpose, usage context, technical mechanism, output details, and truncation behavior. It is front-loaded with the core purpose and structured coherently, though slightly dense in the middle with technical specifics.

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 fully explains what the tool returns (top-N passages with character offsets and similarity scores), how it integrates with other tools, and its limitations (truncation cap). No critical operational context is missing for an agent to decide and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptive parameter text, so the baseline is 3. The description adds extra meaning by explaining how text is processed (500-char windows, embeddings), which affects the interpretation of the 'limit' parameter and the nature of matches. It also reinforces the query format with examples, providing context beyond the schema.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which clearly specifies the verb (search), resource (a fetched record/text), and scope (inside a specific document). It further distinguishes itself from sibling tools like ask_pipeworx by emphasizing 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also names a related sibling, ask_pipeworx_grounded, and explains the complementary workflow, giving clear when-to-use and alternative context.

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

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

The description discloses prerequisites (OAuth account, phone verification), limits (SMS 10/day cap), security details (webhook signing secret, auto-disable after 10 consecutive failures), and states the return value. This goes far beyond the annotations and provides rich operational context without contradicting them.

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

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

Dense but well-structured: it starts with purpose, then requirements, then type examples, then delivery channels. Each sentence provides necessary operational detail without redundancy or filler, making it easy for an agent to parse the most important information 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?

Given the tool's complexity (3 parameters, nested objects, 5 types, multiple delivery channels), the description covers auth requirements, type-specific params, delivery options, and return value. The schema fills in the remaining enum values and webhook details, so together they provide a complete picture for correct 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 description adds substantial meaning to the parameters with concrete examples: sec_8k with items:["5.02"], polymarket_edge with topic:"fed", fred_series with series_id, and detailed delivery constraints (E.164 phone, verified phone, webhook HMAC signing). This complements the schema's descriptions and clarifies actual usage.

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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id', specifying the verb (create) and resource (subscription). It also differentiates from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action.

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

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

The description provides useful context: it requires a Pipeworx OAuth account, explains supported types with examples, and lists delivery options. However, it does not explicitly mention alternatives like list_subscriptions or unsubscribe, and it omits patent_grant and clinical_trial from the overview of supported types, which are present in the schema enum.

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, and idempotentHint. The description adds valuable context that output is drawn from the live catalog of thousands of tools and includes exact tool+argument shape per question, enhancing transparency beyond the structured fields.

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 with example queries, output format, and usage guidance, but every sentence contributes value—purpose, output, call pattern, and when to use. It is more than minimal but not bloated, maintaining structure with clear divisions.

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

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

Even without an output schema, the description thoroughly explains what the tool returns (category-bucketed questions with tool names and argument shapes) and how to invoke it. Combined with strong annotations covering safety and idempotency, the context is complete for a tool with one optional parameter.

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 with 100% coverage, listing allowed values and meaning. The description adds example focus areas ('finance', 'pharma', 'betting') but does not introduce new semantic constraints, so the baseline 3 for high schema coverage is appropriate.

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

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

The description clearly identifies this as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings like discover_tools by positioning it as the first stop for unknown 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 states to use this FIRST when the agent doesn't know what Pipeworx can do, and mentions it can also teach how to call meta-tools (ask_pipeworx, entity_profile, etc.). Provides clear guidance on varying the call (no args vs. topic) with concrete examples.

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

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

The description goes beyond annotations by explaining that ownership is enforced (only your own subscriptions), that the row is deactivated rather than deleted, and that historical events remain accessible via recent_alerts. These behavioral details are not captured in the annotations and are critical for correct use.

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 compact sentences, front-loaded with the primary action, followed by key constraints and side effects. Every clause adds value without redundancy, making it highly efficient.

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

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

For a simple one-parameter mutation tool, the description covers purpose, ownership, deactivation behavior, and relationships to recent_alerts. With idempotent and non-destructive hints provided by annotations, this is complete enough for an agent to use correctly without additional documentation.

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

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

The input schema already provides 100% coverage for the single required parameter id, with a clear description: "Subscription id (uuid) returned by subscribe." The tool description adds no additional parameter-specific meaning beyond confirming the id is used, so the baseline score of 3 stands.

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: "Cancel a subscription by id." It identifies the specific resource (subscription) and the operation (cancel), and it distinguishes itself from siblings like subscribe and list_subscriptions. The ownership enforcement and deactivation detail further clarify its precise role.

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 does not explicitly name alternatives or exclusions, but it implies usage context: the tool is for canceling a subscription, and the mention of recent_alerts for historical events gives a hint about related tool usage. This is clear context without explicit when-not-to-use guidance, so a 4 is appropriate.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) by detailing return verdicts, the distinction between 'could_not_verify' and 'unsupported', and the warning that 'could_not_verify' must not be treated as evidence. It also discloses internal routing and fallback behavior, which is rich contextual behavior.

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

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

The description is longer than typical but well-structured. It front-loads trigger phrases, then explains the two routing paths, return values, and critical warnings. Every section serves a purpose, but the density could be slightly trimmed without losing meaning, so it's a 4 rather than a 5.

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

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

There is no output schema, so the description must explain return values and edge cases. It does this thoroughly: lists verdicts, actual value, citation, reasoning, and clarifies special statuses (could_not_verify vs. unsupported). It also covers routing, tolerance semantics, and consolidates multi-step behavior, making the tool self-contained and complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the tolerance_pct parameter semantics: default behavior (implied by wording, capped at 5), range (0.5–50), and a specific use case (hallucination detection with 1–2). This additional guidance elevates the score.

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 function: natural-language claim verification with specific trigger phrases like "fact check" and "verify the claim." It distinguishes this tool from siblings by emphasizing it is the consolidated fact-checking path, replacing multiple sequential calls.

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

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

The description explicitly states when to use it: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains routing based on claim type (company-financial vs. other). However, it does not explicitly mention when NOT to use it or name alternative tools, so it falls short of a 5.

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