Crontab

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds valuable context beyond this: the default model is free, passing _apiKey routes calls to Anthropic with direct billing to the user, and the return structure is disclosed ('per-model {score, confidence, signals, raw_response} + a combined view'). No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the core action, and every sentence adds meaningful information (purpose, default behavior, return format, use cases). No redundancy or fluff.

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

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

Despite no output schema, the description discloses return structure, use cases, default behavior, and billing nuances. For a tool with 4 parameters and one required, this is sufficiently complete for an agent to select and invoke it correctly. Minor omissions like rate limits don't detract significantly.

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 enhances parameter understanding by explaining the default model behavior for the 'models' parameter and the billing implication of '_apiKey', plus the disambiguation purpose of 'context'. This adds value 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 uses a specific verb ('Probe') and clearly defines the resource ('one or more LLMs for what they know about a business / brand / product / topic') and the output ('score visibility (0-100) per model'). It distinctly differentiates from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring.

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

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

Provides clear context with explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic key. However, it does not explicitly state when not to use this tool or mention alternative tools for comparison, so it lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it routes internally, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is 'one fast call'. It also implicitly discloses that it may not always be hallucination-resistant by recommending ask_pipeworx_grounded when that is needed.

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. It is front-loaded with the core 'PREFER OVER WEB SEARCH' directive, then explains what the tool does, when to use it, provides examples, and gives upgrade paths. The structure is logical and compact given the tool's central role.

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

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

Given the tool's complexity and lack of output schema, the description covers essential context: what it does, when to use, when not to use (alternatives), what it returns (structured answer with citations), and operational traits (works on every tier, one fast call). It leaves no major gaps for an agent to misuse it.

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

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

Schema coverage is 100% and the only real parameter 'question' is well documented with alias examples. The description adds value by exemplifying the kinds of queries to pass ('current US unemployment rate', 'Apple's latest 10-K') and by explaining that any natural-language factual question is acceptable. This goes beyond the schema's generic 'your question or request'.

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 gives a specific verb ('ask') and resource ('Pipeworx'), clearly stating it routes questions to 5,529 tools across 1,455 sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and from web search.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for a long list of domains, and 'START HERE for most questions'. It also gives concrete step-up alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions) and example queries to make usage 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?

The annotations already mark it read-only, open-world, and idempotent; the description adds context about its beta status, current operational equivalence to ask_pipeworx, and that it is a full working router rather than a fallback. This helps the agent judge reliability and testing 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 with the essential facts front-loaded; every sentence provides distinct information without redundancy.

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

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

The description covers what the tool does, how it relates to the stable version, when to use it, and its current testing state. Although no output schema is present, it references the same response shape as ask_pipeworx.

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 all parameters with descriptions, including alias relationships, so the description doesn't need to add parameter-level detail. It does mention 'same arguments' as ask_pipeworx, which is a cross-reference but not additional semantics.

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

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

The description clearly identifies this as a beta version of ask_pipeworx with the same universal routing functionality, specifying it handles 5,529 tools, same arguments, and same response shape. It distinguishes itself from the stable ask_pipeworx by noting experimental routing improvements and the current no-active-candidate state.

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

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

It states 'Use it exactly like ask_pipeworx when you want the newest routing,' giving explicit selection criteria. It also contrasts with the stable router by saying results are compared to decide what merges, implying when to prefer stable vs beta.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals the inner workings: routing across 5,529 tools, filling arguments, fetching data, extracting only from tool results, returning a structured object with evidence and refusal reasons, and incurring an extra LLM call. This is rich behavioral context not present in 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 each sentence contributes: it defines the mode, explains the mechanism, outlines the return structure and refusal reasons, gives use cases, and notes the cost tradeoff. It maintains a logical flow without redundancy, earning its length.

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

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

Given the tool's complexity and lack of an output schema, the description compensates by fully specifying the success and failure return shapes, including evidence, confidence, source, fetched_at, and five categorical refusal reasons. It also contextualizes the cost and place among siblings, making the tool's behavior and expectations unambiguous.

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 all six parameters, all documented as aliases for the natural-language question. The description adds value by explaining that the tool itself handles tool selection and argument filling, clarifying why a single question parameter suffices and how it is used. This goes slightly beyond the schema's simple alias documentation.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode that fetches data via the same routing as ask_pipeworx and extracts an answer using only the tool result. It distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded, evidence-based nature and the return of verbatim evidence and explicit refusals.

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 specifies when to use (for high-stakes reads where answers will be quoted, cited, or acted on, and the agent must not invent facts) and when not to use (prefer ask_pipeworx for casual lookups due to the extra LLM call cost). It names the alternative tool directly, making the decision 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?

The description is exceptionally transparent about behavior: parallel fan-out, resolver contract with confidence levels and alternatives, low-confidence short-circuit, closed-market blocking, wide-spread tradeability flag, news fallback handling, and cancellation-rule parsing. Annotations already declare readOnlyHint and destructiveHint, so the description adds significant operational context beyond that.

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 meticulously structured with CAPS-labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making it scannable and each segment purposeful. It is front-loaded with purpose and usage. However, the overall length is high and some edge-case details (e.g., exhaustive fan-out examples) could be trimmed without losing core value.

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

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

Given there is no output schema, the description must fully detail return values, and it does: result.market fields, result.analysis, result.evidence, resolver contract fields, parent_event extractor, news fallback fields, safety statuses, and cancellation-rule risk. This is a complete operational picture for a complex research 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 the baseline is 3. The description does not add much beyond the schema for the 'market', 'depth', and 'include_raw' parameters; it mostly restates the market input format already present in the schema. No additional parameter-level details are introduced in the description.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like polymarket_edges or validate_claim by focusing on per-bet research with fan-out to data sources. The 'Use for' examples further cement the intended purpose.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when the tool is appropriate. However, it does not explicitly state when not to use it or name alternative sibling 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.

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

Annotations declare read-only, idempotent, open-world hints, but the description adds substantive behavioral details: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly (AAPL, NVDA examples), sorts results by primary metric, and returns paired data with citation URIs. These go well beyond the annotations and help the agent set expectations.

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

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

Though moderately long, every sentence adds value—query examples, type-specific data sources, fiscal year nuance, sorting behavior, and output format. The structure starts with user-intent phrases, then proceeds to technical details, making it highly scannable and information-dense without redundancy.

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

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

Given there is no output schema, the description compensates by stating the return includes paired data and pipeworx:// citation URIs, covers both entity types, and mentions sorting by primary metric. It addresses complexity, data sources, fiscal year edge cases, and the efficiency benefit, making it a complete standalone reference.

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

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

Schema coverage is 100%, and the description still adds meaningful semantics beyond the schema. It explains that type='company' pulls financial metrics and type='drug' pulls adverse-event/trial counts, and clarifies that values are tickers/CIKs for companies and drug names for drugs. This contextualizes the enum and array values effectively.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call, with explicit example queries. It distinguishes itself from sibling tools like entity_profile by emphasizing multi-entity comparison and specific data sources (SEC EDGAR/XBRL, FAERS). The verb 'compare' plus resource types 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?

Provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists query patterns that trigger this tool. It also clarifies when to use company vs drug type and mentions it replaces 8-15 sequential lookups, giving clear alternatives and 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?

Description adds substantial behavioral context beyond annotations: account/permission requirements, return format (findings packet with gaps[], contradictions[], citations), never-invented policy, semantic excerpting, performance/latency expectations, and the specific meaning of depth levels. There is no contradiction with the readOnly/openWorld/idempotent annotations; the tool's live structured-data access aligns with openWorldHint.

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 structured: it front-loads the critical account requirement, then methodically covers mechanism, use cases, comparisons, depth behavior, output guarantees, and performance. Every sentence contributes necessary information for a complex tool, and there is no filler or redundant restating of the title or schema.

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

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

Given the tool's complexity, minimal schema (2 params), and absence of an output schema, the description carries substantial responsibility. It covers return structure, error/gap behavior, citation resolvability, contradictions, and performance, making the tool fully operable without external documentation. The sibling-tool comparisons complete the contextual picture.

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

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

While the schema already covers both parameters, the description enriches them significantly: 'question' is described as natural language and can be broad/multi-part, and 'depth' is expanded with detailed behavioral implications (hop count, gap recovery, contradiction scan, paid tier). This exceeds the bare enum descriptions, adding the practical meaning an agent needs to choose parameter values.

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

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

The description states a specific verb ('research') and a precise resource ('Pipeworx's 1455 STRUCTURED data sources'), and immediately distinguishes itself from open-web search and sibling tools. It explicitly differentiates from ask_pipeworx for single lookups and current news, making the tool's unique 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?

Provides explicit usage guidance: 'Best for broad/multi-part questions over structured data', with direct exclusions ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also explains depth-level trade-offs and account requirements, giving clear context on when to choose this tool over 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, idempotentHint, and destructiveHint:false, covering the safety profile. The description adds valuable behavioral context by specifying the input format ('5 fields or an @alias') and the return behavior ('Returns the parsed fields and whether it is valid'). No contradiction with annotations.

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

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

The description is a single, well-structured sentence that front-loads the primary action and includes all essential information without any fluff. Every phrase earns its place.

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

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

For a simple tool with one parameter and rich annotations, this description is complete: it states what the tool does, the input format, and the return values. No external context is missing for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the parameter 'expression' is already well documented by the schema. The description adds the '5 fields or an @alias' detail, but this is essentially already conveyed by the schema's examples. Thus the description adds marginal value over the schema.

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

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

The description clearly states the tool's purpose with specific verbs ('Parse and validate') and a specific resource ('a cron expression'), and it describes the output ('describe it in plain English', 'Returns the parsed fields and whether it is valid'). This distinguishes it from all sibling tools, none of which perform cron expression parsing.

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 intended usage is implied by the description, but there is no explicit guidance on when to use this tool versus alternatives. No mention of exclusions or when not to use it, and no reference to sibling tools like 'next_runs' that might be related.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds valuable context: it returns names, descriptions, and full input schemas with curated examples, directly callable without a second lookup. This goes beyond the annotations and clarifies the tool's output behavior, with no contradictions.

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

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

The description is three sentences, front-loaded with the core purpose, followed by usage context and output details. Every sentence earns its place, with no redundancy or fluff.

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

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

For a meta-tool, the description fully covers what it returns (tool names, descriptions, schemas), when to call it (first, when many tools available), and its key differentiator (no second schema lookup). Combined with rich annotations and schema, it leaves no critical gaps.

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

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

The schema covers 100% of parameters, including descriptions and examples for 'query' and aliases. The tool description reinforces the semantic flexibility of the query by mentioning 'describing the data or task' but adds no new parameter-level detail 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 uses a specific verb and resource ('Find tools') and lists numerous domains, making the tool's purpose unmistakable. It clearly distinguishes itself from sibling tools by positioning itself as a meta-tool for discovery rather than a domain-specific query tool.

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

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

The description explicitly states when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and provides directive guidance ('Call this FIRST when you have many tools available'). It does not name specific alternative tools, but the 'not just one answer' qualifier hints at when not to use it, earning a 4.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds valuable behavioral details beyond annotations: fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; the patent API sunset and soft-fail behavior; and the GDELT→GNews fallback for news. This gives the agent a realistic picture of what happens during execution.

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 example queries and a clear purpose statement. It then organizes additional details logically (fan-out sources, return fields, limitations). While long, every sentence adds necessary context, and the structure makes it easy to parse.

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. It enumerates each field: cik + company_name, recent_filings (with URIs), fundamentals (specific fields and ordering), patents (with soft-fail note), news (with fallback), and LEI. Given the tool's complexity and missing output schema, the description is complete and self-sufficient.

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

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

Schema description coverage is 100%, with both parameters (type and value) fully described in the schema. The description repeats the same information (ticker or CIK, names not supported) without adding extra insight or clarifications. Per the rubric, a baseline of 3 is appropriate when the schema already documents parameters fully.

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: "full cross-source profile of a US public company in ONE parallel call." It uses a specific verb (profile) and resource (US public company), and distinguishes itself from sibling tools by explicitly noting it should be preferred over chaining single-pack SEC/XBRL/news lookups for holistic queries.

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: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also specifies when not to use it (names not supported) and the alternative (resolve_entity first). This clearly establishes when to use the 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds only the use-case context (cleanup of stale/sensitive data) but no additional behavioral traits like error handling or side effects. With annotations doing the heavy lifting, this is adequate but not exceptional.

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, with the primary action first and usage guidance second. Every sentence earns its place with no redundancy.

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

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

For a single-parameter destructive operation with robust annotations (destructive, idempotent) and full schema coverage, the description fully covers what the tool does, when to use it, and related tools. No output schema is needed, and no obvious gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter as 'Memory key to delete'. The description merely restates this ('by key'), adding no extra meaning. Baseline 3 is appropriate given the schema's completeness.

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 ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes itself from sibling tools by pairing with 'remember and recall', making its role in the memory lifecycle explicit.

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 conditions ('Use when context is stale, the task is done, or you want to clear sensitive data') and mentions related tools ('Pair with remember and recall'). This gives clear guidance on when to use vs alternatives, though it doesn't explicitly name a 'when not to use' case.

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 explains the mechanism ('fetches the page, extracts title/description/key links, emits the standard llms.txt markdown format') and output ('single text blob ready to drop'). This goes beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by adding functional detail without contradicting them. It doesn't discuss potential failures or network dependencies, but the added context is strong.

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 with the core purpose upfront, followed by behavior and use cases. No wasted words; each sentence adds value. The structure is front-loaded and easy to scan.

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

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

Given the simple two-parameter tool with no output schema, the description fully covers purpose, behavior, output format, and use cases. It even specifies the output placement ('site-root/llms.txt'), which is a useful contextual detail. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema covers both parameters (url, max_links) with clear descriptions, and schema coverage is 100%, so baseline is 3. The description only references URL implicitly ('any URL') and doesn't add new information about max_links or parameter behavior, so it stays at baseline.

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

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

The description states a clear verb ('Generate') and resource ('llms.txt file'), specifies the target ('any URL') and the end result ('AI crawlers can index the site cleanly'). It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning or visibility checks.

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

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

Provides explicit use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor') which frame when to use it. However, it doesn't name alternative tools or explicitly state when not to use it.

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

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

With readOnlyHint and idempotentHint annotations, the safety profile is already covered. The description adds value by disclosing the scope (caller's subscriptions), the default filter (active only), and the exact return fields, enriching understanding 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 two sentences, front-loaded with the core purpose, and includes return fields and usage guidance without any redundant fluff. Every sentence adds value.

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

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

This is a simple read-only list tool with one optional parameter, strong annotations, and no output schema. The description covers purpose, return shape, and usage scenarios, making it 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?

The input schema provides 100% coverage for the single optional parameter include_inactive with a clear description. The tool description adds no additional parameter semantics, so the baseline score of 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the exact return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe/unsubscribe which are write operations.

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

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

The description explicitly says to use this tool to review what you're monitoring before adding more (i.e., before subscribe) or to find an id to cancel (i.e., before unsubscribe). This provides clear context and direct references to alternative actions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the output timezone (UTC ISO-8601) and optional start time, which provides some value beyond annotations, but does not disclose error handling or edge cases like invalid cron expressions. This meets the baseline for a safe read-only tool.

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

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

Two concise sentences, with the primary purpose front-loaded. Every word adds value; no fluff or repetition of schema/annotation details.

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

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

The tool is simple and the description fully captures its behavior: computing N future run times with an optional start. Schema covers parameter constraints, and annotations cover safety. No output schema is needed because the tool's return type is self-evident from the description.

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

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

Input schema has 100% coverage with clear descriptions for all three parameters. The description reinforces that the start time is optional, but adds limited new meaning beyond schema details. Baseline of 3 is appropriate since schema handles 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?

Description clearly states it computes next run times for a cron expression, using specific verb ('Compute') and output format (UTC ISO-8601). This distinguishes it from sibling tools like describe_cron, which likely explains cron syntax rather than calculating future run times.

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

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

No guidance on when to use this tool versus alternatives such as describe_cron. The description only mentions an optional start time parameter, but does not explain use cases or exclusions, leaving the agent without 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 richly discloses behaviors beyond annotations: it returns a claim_token when filed without an account, explains how to later use that token to check status/changes, mentions the 5-per-day rate limit, states it is free, and notes that the team reads digests daily. No annotation contradiction exists.

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

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

The description is longer than average, but every sentence earns its place: purpose, use cases, exclusion, token mechanics, rate limit, cost, and roadmap impact. It is front-loaded with the core purpose and structured so each sentence adds new, actionable 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?

Despite having no output schema, the description covers the key workflow: filing feedback, receiving a claim_token, reading later resolution status, and the rate-limit/free constraints. It is complete for a feedback tool with nested optional context and four parameters, and it clearly communicates the tool's closed-world scope.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable semantics beyond the schema, especially for claim_token, explaining the token lifecycle and that it should be passed alone. It also gives message-level guidance ('don't paste the end-user's prompt'), though it does not deeply elaborate on every parameter.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from sibling research/query tools by framing it as feedback to the vendor, not a data lookup or question-answering tool.

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

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

Explicit when-to-use guidance is given for each feedback type: bug, feature/data_gap, and praise. It also states when NOT to use it — for tools from a different MCP server, 'file it with that server instead' — and clarifies scope with 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This explains data provenance, privacy, and caching behavior, going 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 well-structured: it opens with the core purpose, lists specific use cases, and adds context about caching and privacy. While it could be tightened, every sentence contributes useful information and it is not unnecessarily verbose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers the return values ('top tools, top packs, total call volume') and key operational details (caching windows, data source). It is sufficiently complete for an agent to understand the tool's capabilities and limitations.

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

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

Schema description coverage is 100% for the single parameter, and the schema already explains the window meanings ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description doesn't add additional parameter semantics beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb-resource pairing that distinguishes it from other tools like discover_tools or ask_pipeworx.

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

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

The description provides explicit use cases: '(1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' It lacks explicit alternatives or when-not-to-use guidance, so it misses the top score.

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

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

The description discloses rich behavioral detail: semantic anchor thresholds (≥0.30 Jaccard), partition placeholder filter (>20% placeholder => null arb), fill check logic (realizable_edge_pp ≤ 0 means do not trade), and response structure. It complements the readOnlyHint and idempotentHint annotations without contradiction, adding significant context 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 dense and front-loaded, with a clear purpose statement followed by labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is long but every section adds critical usage detail. A small deduction for being somewhat verbose; it could be trimmed slightly without losing value.

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

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

For a complex tool with two modes, multiple filters, and a fill-check remark, the description covers all necessary context: invocation modes, parameter semantics, output fields, edge cases, and caveats. It also references an alternative for custom sizing, making it self-contained enough for an agent to use 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?

Although the schema already provides 100% parameter coverage, the description adds substantial meaning with concrete examples ('event' slug vs 'topic' seed question), explains the mode-specific behavior of each parameter, and clarifies what happens when no args are supplied. This goes far beyond the schema's basic descriptions.

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

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

The description begins with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools by naming its methodology and referencing polymarket_fill_risk for sizing, making it clear what this tool does and what it doesn't.

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also tells when to prefer event vs topic and points to an alternative tool for custom sizing, satisfying both 'when to use' and 'when not to use'.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses extensive behavioral details: caching at the KV level for 1 hour keyed on all knobs, the fact that partition arbs always return kelly_fraction_half=0 at the parent level by design, and the 24h-move warning when recent market movement exceeds the edge. This goes far beyond what annotations provide and gives the caller deep insight into edge computation and output semantics.

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 a clear purpose in the first sentence, then organized into paragraphs covering model families, response structure, tradeable-edge knobs, and diagnostics. It is long and dense, but every section adds necessary operational detail for a complex 9-parameter tool with no output schema. The structure earns its length despite being 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 must explain return values, and it does: it details the fields carried by every opportunity (edge_pp_net, kelly_fraction, market liquidity, spread, volume, 24h warning) and the top-level response structure (by_segment, fed_candidates, _diagnostics). It also explains model families and knob effects, making the tool fully understandable for an agent without further discovery.

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 has 100% parameter coverage, so the baseline is 3. The description adds value by grouping 'TRADEABLE-EDGE KNOBS' and explaining how min_liquidity/max_spread_pp drop opportunities where the edge isn't realizable, and how min_partition_leg_kelly filters partitions by per-leg Kelly. This contextualizes the parameters beyond their individual 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+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on cross-referencing Pipeworx data against market prices for daily betting decisions.

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 frames the tool as 'built for "what should I bet on today"' and notes that agents can 'discover opportunities without paging hundreds of markets.' It also provides an exclusion: Fed bets are surfaced but excluded from ranking, with a rationale about unreliable signal horizons. However, it does not explicitly name alternative sibling tools for different use cases.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond this: the 60-day snapshot TTL bound, that snapshots are only written on cache-miss (so gaps mean no scan), and that decay numbers come from daily closes of edge_pp_net (net of slippage), not intraday. It also explains response structure in detail. 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?

Though long, the description is well-structured into explicit sections (Args, RESPONSE, LIMITS). Every sentence carries substantive information: purpose, usage context, parameter meaning, response fields, and limitations. No fluff or repetition of annotations. The density is appropriate for the tool's complexity.

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

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

The tool is complex (time-series telemetry, trend classification, expired opportunities), yet the description covers all key aspects: how data is derived, what each response field means (including trend enum values), what limitations exist (TTL, cache-miss gaps), and how parameters affect the query. With no output schema and only 2 params, this description is complete enough 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%, and the schema descriptions already cover defaults and ranges. The description adds value by connecting parameters to their conceptual role: 'window (snapshot family)' clarifies that the parameter selects which polymarket_edges snapshot family to read, and the note about lookback depth being bounded by TTL gives purpose to 'days'. This pushes above the baseline 3.

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

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

The description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly states the core question it answers: 'how long has this edge existed and is it shrinking?' This clearly specifies the tool's verb (track/measure), resource (polymarket_edges snapshots), and distinguishes it from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge values.

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: it answers the persistence/decay question and explains why the distinction matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name sibling alternatives or state 'use this instead of X', but the intent is unambiguous. The lack of explicit exclusions keeps it from 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?

Beyond the readOnly/idempotent annotations, the description details exactly what the tool does internally: walks the order-book ladder, computes VWAP, slippage, fills, and a verdict. It also discloses the risk of partial basket fills converting an arb into an unhedged directional position—valuable behavioral context not inferable from the schema or annotations.

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

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

The description is long but well-structured, using SINGLE-MARKET and BASKET sections that mirror the tool's modes. Every sentence adds necessary detail for correct use, though it could be tightened by moving return-field lists into an output schema if one existed. Still, it is appropriately dense for the tool's complexity.

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

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

Given the tool's complexity (two modes, many return fields, potential edge cases) and the absence of an output schema, the description provides all essential context: it lists expected return fields, warns about thin books, names forced directional risk, and explains the threshold for use. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Although the schema already covers 100% of parameters, the description adds critical semantic detail: size_usd means max spend on buys but target proceeds on sells in single-market mode, while in basket mode it is settlement notional (shares per leg). It also explains the auto-default behavior for side in basket mode, which is not in the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings by explicitly stating it is for pre-trade validation of fill risk on polymarket books, unlike polymarket_arbitrage or polymarket_edges which generate 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?

Explicit when-to-use guidance is provided: '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, giving clear context without 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?

The description goes well beyond the readOnly/idempotent annotations by detailing how the tool surfaces non-equivalent bet shapes, temporal alignment, and skip counters. It explains what compatibility_warning means in two distinct scenarios, providing rich behavioral context that annotations do not cover.

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

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

The description is lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Each section adds necessary detail for a complex tool, but some redundancy (e.g., re-explaining compatibility_warning) slightly reduces conciseness.

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 covers the response structure, spread calculation, safety fields, and edge cases. It provides enough context for an agent to correctly invoke the tool and interpret results, even without a formal output schema.

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

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

With 100% schema coverage, the description adds value by explaining the two modes and the precedence of explicit parameters over topic mapping. It also provides concrete examples of allowed topics and explicit ticker/slug formats, enriching the schema's baseline 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings by its specific cross-venue focus. It names the resource and the exact operation (spread computation), making its 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 explains two usage modes (topic shortcuts and explicit ticker/slug) and provides explicit context on when results are meaningful (aligned temporal periods, equivalent bet shapes). It implicitly tells users to avoid relying on pre-mapped topics when compatibility_warning fires, but it does not explicitly name alternative tools for intra-venue 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 declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds valuable context beyond annotations by explaining scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the relationship with remember/forget. It does not detail return format, but for a read-only lookup that is acceptable.

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

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

The description is three sentences, front-loaded with the core action, and adds usage context, scoping, and tool relationships without any fluff. Every sentence contributes meaning and no repetition of structured data exists.

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 is nearly complete. It covers purpose, usage, scoping, and tool relationships. It stops short of describing the exact return value format, but the examples make the expected output clear enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the parameter description already explains omitting the key to list all keys. The main description adds illustrative examples of what keys might contain, but this is supplemental rather than essential. The baseline of 3 is appropriate when the schema carries the parameter semantics.

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

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

The description uses specific verbs 'retrieve' and 'list' with a clear resource (previously saved values/keys) and distinguishes itself from sibling tools by referencing 'remember' and 'forget'. It also provides concrete examples of stored content (ticker, address, research notes), making the purpose unmistakable.

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

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

The description clearly states when to use the tool: to look up context the agent stored earlier 'without re-deriving it from scratch', which is an explicit usage context. It also relates to siblings (remember, forget) but does not explicitly state alternatives or when not to use it, leaving a small gap.

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 states that setting mark_read:true flags returned events as read, which changes state on the feed. This directly contradicts the annotation readOnlyHint:true, which marks the tool as read-only. Therefore, the description contradicts the annotation, and per rubric, behavioral transparency must be score 1.

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 4 sentences, front-loaded with the primary purpose, then return values, filtering, and additional notes. Each sentence adds new information without fluff, earning 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?

The description covers the return fields, filtering options, mark_read side effect, polling behavior, and an alternative HTTP endpoint. It lacks explicit pagination or error details, but given the schema and annotations, it's largely 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?

With 100% schema coverage, the baseline is 3. The description adds extra value beyond the schema by explaining the practical use of type (e.g., 'sec_8k') and the effect of mark_read on subsequent polls. It does not cover unread_only or limit in detail but the schema covers them, so a 4 is justified.

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 'Pull fired events from your subscription feed,' a specific verb+resource combination that clearly distinguishes it from sibling tools like list_subscriptions or recent_changes. It further specifies the return payload (source, citation_uri, raw event) and the data origin ('alerts the evaluator has written').

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 context for when to use the tool: it mentions filtering by type/since and that 'Polls work fine,' implying it is suitable for repeated retrieval. It also points to an alternative method for scripts and dashboards (the GET endpoint), enriching usage context, though it does not explicitly name sibling tools or state when not to use them.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses fallback behavior (GDELT preferred, GNews when rate-limited or 5xx), soft-failure of patents due to PatentsView API sunset, and the return structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs). 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 every sentence earns its place: it front-loads with user intents, then covers sources, fallbacks, date formats, return structure, and alternative tool. It is well-structured and avoids 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 tool with multiple sources, fallbacks, and date formats, the description is highly complete. It explains return values (changes[], total_changes, URIs), source-specific behavior, and provides an explicit alternative, compensating for the lack of an output schema.

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

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

Schema coverage is 100%, but the description adds meaningful detail beyond the schema: it explains `since` accepts ISO dates or relative shorthand with examples, recommends '30d'/'1m' for monitoring, and clarifies that `value` can be a ticker or zero-padded CIK. This enhances parameter understanding.

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

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

The description clearly states it provides a change feed for a company over a time window, with specific verbs like 'returns' and 'fans out' to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from the sibling entity_profile by explicitly saying to use that tool for static profiles.

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 usage context with example queries ('What's new with X', 'latest on Y') and gives a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This tells when to use this tool vs. an alternative.

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

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

Annotations already provide safety hints (idempotent, not destructive, not read-only). The description adds valuable context about persistence (authenticated vs. anonymous sessions) and scoping by identifier. It does not explicitly state overwrite behavior, but idempotentHint implies it, so no contradiction or major gap.

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 core purpose, then usage, then storage details. Each sentence contributes essential information with no redundancy or filler.

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

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

For a simple two-parameter tool with no output schema, the description fully covers purpose, usage, persistence behavior, scoping, and sibling relationships. Nothing important is missing.

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

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

Schema coverage is 100% with descriptive examples for both 'key' and 'value'. The description adds general usage context but does not explain parameter syntax beyond what the schema already provides. Baseline 3 is appropriate when the schema carries the load.

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

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

The description uses a specific verb ('Save data the agent will need to reuse later') and clearly identifies the resource (key-value store scoped by identifier). It distinguishes itself from siblings by explicitly mentioning persistence across conversations/sessions and pairing with recall/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 when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also references alternatives by saying 'Pair with recall to retrieve later, forget to delete,' making the usage context 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?

The description goes well beyond the annotations (readOnly, openWorld, idempotent) by detailing internal cascading lookups, labeling identifiers with their source, explicitly listing unresolved identifiers, and describing graceful degradation of LEI/FIGI enrichment. This provides valuable behavioral context not inferable from annotations alone.

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

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

The description is dense and well-structured with a clear purpose, usage statement, and supported types. It is somewhat verbose with an extensive list of example phrasings at the start, but every section earns its place by adding unique value. Could be tightened, but overall it is well-organized.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers input formats, output content, source attribution, unresolved handling, fallback behavior, and even use-case context (replacing multiple lookups). The agent can confidently invoke this tool without needing additional documentation.

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

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

Although the schema already describes both parameters, the description adds substantial meaning by explaining the distinct behavior for each supported type (company vs drug), specifying valid input formats (ticker, CIK, name; brand/generic), and outlining the expected output structure. This far exceeds 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 defines the tool's purpose: resolving user-spoken names to canonical/official identifiers needed by other tools. It provides a specific verb ('resolve') and resource ('name to identifier'), along with concrete examples and supported types, making it easily distinguishable from siblings like entity_profile or compare_entities.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces multiple manual lookups. However, it does not explicitly mention when not to use it or name alternative tools for cases like building a full profile, so it's clear but lacks exclusionary 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 readOnly/idempotent/non-destructive, so the description adds process detail: it 'probes each entity' with ai_visibility_check and 'returns ranked list with score, confidence, signal density per entity.' This goes beyond the safety profile and explains the aggregation 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?

Two sentences, no redundancy. The first sentence front-loads the core function, the second provides the use case and expected output. Every sentence serves a purpose without unnecessary elaboration.

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 explicitly lists the return fields (score, confidence, signal density). The schema covers parameter constraints like 2-8 entities and models. The tool's complexity is adequately addressed for an agent to select and invoke it correctly, though it doesn't mention edge cases like rate limits or cost.

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 provides 100% coverage with descriptions for all 4 parameters, including the first-entity-as-subject convention. The description does not add additional parameter semantics beyond what the schema states, so it earns the baseline score for full schema coverage.

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

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

The description clearly states a specific action: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the ranking by score and surfacing most/least recognized.

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' with an example query. It implies that for a single entity one should use ai_visibility_check, but does not explicitly state exclusions or alternatives. The context is strong enough to guide appropriate use.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses performance caveats ('bundlephobia's first measurement on a new version can take 5-30s'), graceful degradation ('sources_failed will list it if it times out, the rest still returns'), and ecosystem limitations. This is actionable behavioral context not present in 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: purpose, when-to-use, return payload, ecosystem scope, and failure behavior are all front-loaded. It's longer than average but every sentence adds critical information. Minor deduction for length, but no word is wasted.

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

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

With no output schema, the description fully specifies the return summary block fields (is_latest, license, etc.), per-advisory detail, links, and alternative versions. It also covers error/timeout behavior and ecosystem scope. This is comprehensive for a tool of this complexity.

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

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

Schema coverage is 100% and both parameters have clear descriptions in the schema, so baseline is 3. The description reinforces that version defaults to latest and mentions version history as part of output, but doesn't add syntax or format meaning beyond the schema. It notes scoped packages are accepted, which is already in the schema.

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

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

The description opens with a clear composite purpose: 'Composite "should I add this npm package to my project" check in ONE call' — a specific verb (check) and resource (npm package decision) that distinguishes it from sibling tools like scan_competitor_ai_presence. It also enumerates the exact data sources (deps.dev, bundlephobia) and output types.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides a clear exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive. The description adds substantial context beyond this: embedding model (BGE-base-en), cosine similarity over 500-char windows, 200K char cap with truncation flagging, and character offsets for verbatim quote verification. No contradiction with annotations.

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

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

Three dense sentences, front-loaded with the core purpose. Every sentence adds value: usage context, pairing with sibling, technical details. No fluff.

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

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

Despite lacking an output schema, the description fully explains the return format (top-N passages with offsets and scores), parameter roles, input limits and truncation behavior, and integration with a key sibling tool. This is complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic meaning beyond the schema: 'text' is 'text you already pulled', 'query' is a natural-language query with examples, and 'get back the top-N passages' clarifies how 'limit' behaves. This elevates it above the baseline.

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

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

The description clearly states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and describing its complementary role. The examples (SEC 10-K, article) make the purpose tangible.

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

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

Provides explicit 'Use when...' guidance: when the record is too big to cram into the prompt. It also explains how it pairs with ask_pipeworx_grounded, giving clear context for when to choose this tool over alternatives like fetching the whole document.

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

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

Annotations already indicate this is a write operation (readOnlyHint false) and idempotent (idempotentHint true). The description adds important auth requirements (Pipeworx OAuth account) and delivery constraints (phone verification, 10/day cap). However, it omits the webhook delivery channel entirely, misleadingly implying only feed/email/sms are available. This is a gap in behavior disclosure.

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

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

The description is a single, dense block with three logically ordered sentences: purpose, requirements/types, and delivery channels. Every sentence adds information, and it is front-loaded with the core action. Slightly long but efficient for the complexity.

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

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

Given the high complexity (nested params, enums, no output schema), the description covers many essential aspects but leaves notable gaps: webhook delivery is omitted, error handling is not discussed, and the meaning of 'idempotent' behavior is left to annotations. It is adequate but not fully complete for this complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples and clarifications beyond the schema, such as 'items:["5.02"] = officer change' and the 'topic:"fed"' example for polymarket_edge, plus details on delivery options like feed always being on. This exceeds baseline value.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and the target resource ('live-data event stream'), and notes it returns the subscription id. This distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description gives clear context: it explains what the subscription does, the required OAuth account, and the supported subscription types. It does not explicitly name alternatives or exclusion criteria, but the context is enough to understand when to use it.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the response structure (category-bucketed example questions), the source (live catalog of thousands of tools), and the additional value of showing exact tool+argument shapes. This adds meaningful 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 a single dense paragraph, but every sentence contributes useful information: use cases, output details, invocation variants, and alternatives. It is somewhat long but appropriately so for an onboarding tool.

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

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

With no output schema, the description fully explains what the tool returns, how to use it, what parameters do, and when to use it. It also covers the relationship to sibling meta-tools, making the description 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?

The input schema already provides a complete description of the single `topic` parameter, including allowed values and the default behavior when omitted. The tool description reinforces this with examples but does not add substantive new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with the exact tool and argument shape for each, serving as an onboarding entry point. It distinguishes itself from sibling tools like discover_tools by focusing on 'what can I ask' and mentions specific meta-tools to learn about.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also describes the two invocation modes (no args vs. topic) and lists example focus areas, leaving no ambiguity about when to use this tool.

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

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

Annotations already indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds critical behavioral details: ownership restrictions ('you can only cancel your own subscriptions') and the exact effect on the row ('deactivated (not deleted)'), plus a pointer to 'recent_alerts' for historical events. This goes 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 two sentences that lead with the core action ('Cancel a subscription by id'), then add essential constraints and consequences in subsequent clauses. Every phrase adds new information, with 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?

For a simple tool with one parameter and no output schema, the description covers the key aspects: the action, ownership restrictions, and the non-destructive deactivation behavior. It lacks an explicit note about the return value or error cases, but given the simplicity and the annotation coverage, this is a minor gap. Referencing recent_alerts helps with follow-up context.

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

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

The input schema already provides a full description for the sole parameter 'id' as 'Subscription id (uuid) returned by subscribe.' The description merely repeats 'by id' without adding extra semantic detail, so it does not compensate beyond the schema's 100% 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 function: 'Cancel a subscription by id.' It specifies the resource (subscription) and the action (cancel/unsubscribe), and distinguishes it from sibling tools like 'subscribe' or 'list_subscriptions' by indicating it's for cancellation and mentions ownership.

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 context on when to use the tool: 'Ownership is enforced — you can only cancel your own subscriptions' gives a prerequisite and scope. It also notes that historical events remain available via 'recent_alerts', which suggests an alternative for viewing past data. However, it does not explicitly name 'subscribe' or 'list_subscriptions' as alternatives, so it lacks explicit when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds crucial behavioral context: the exact return verdicts, the critical distinction between 'could_not_verify' (pipeline failure, not evidence) and 'unsupported' (no source covered), and the reasoning/verbatim evidence behavior. This significantly enriches the agent's understanding 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 dense but every sentence earns its place: query examples, routing logic, return verdicts, the critical caveat about could_not_verify, and the efficiency benefit. It is well structured, front-loaded with the purpose, and free of filler.

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

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

Given the tool has only 2 parameters, no output schema, and moderate complexity, the description does an excellent job of explaining return values, verdict semantics, error handling, and routing. It covers all key aspects an agent needs to invoke the tool correctly and interpret results.

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

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

The input schema already provides 100% coverage, including the tolerance_pct override semantics and default behavior. The description does not add any additional meaning to the parameters that isn't already in the schema; it is at 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 identifies the tool as natural-language claim verification against authoritative sources, with concrete example phrasings. It distinguishes itself from sibling Q&A/research tools by specifying the claim-verification purpose and the two routing paths (structured SEC fast path vs. grounded pipeline).

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

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

It explicitly states when to use the tool: whenever the agent needs to check whether something a user said is factually correct. It also explains the fallback behavior for any non-financial claim, giving clear context. However, it does not name alternative tools or provide explicit when-not-to-use exclusions, 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.