agify

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond those: the default model (Workers AI Llama-3.3-70b) is free, while using Anthropic requires a BYO '_apiKey' and direct payment to Anthropic. It also discloses the return structure, enhancing transparency.

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

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

The description is three sentences, front-loaded with the main purpose, then details on the default model, cost implications, return format, and use cases. Every sentence adds value with no redundancy, making it highly concise and well-structured.

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

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

With no output schema, the description appropriately explains the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers all parameters, use cases, and cost/behavior details. It doesn't define 'signals' or score calculation, but for a probe tool this is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful detail beyond the schema: it clarifies the default model, explains that '_apiKey' enables Anthropic probing at the user's own cost, and notes that 'context' helps disambiguate common names. This supplements 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 clearly states the tool's function: probing LLMs about a business/brand/product/topic and scoring visibility on a 0-100 scale. This uses a specific verb ('probe') and resource ('LLMs'). However, it does not explicitly differentiate from the sibling tool 'scan_competitor_ai_presence', which arguably overlaps in purpose.

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

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

The description gives clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This indicates when to use the tool, though it does not mention exclusions or when to prefer a sibling tool. It provides context but no explicit alternatives.

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

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

The description discloses behavior beyond the read-only annotations: the tool routes, auto-fills arguments, handles queries through an agent, and returns stable pipeworx:// citation URIs. This is useful, concrete transparency. The final sentence is slightly awkward/obscure, but the overall behavioral disclosure 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?

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'), then gives domain cues, mechanism, examples, and a starting directive. It is longer than minimal, but every sentence adds useful selection or invocation context. A slight grammatical oddity in the final sentence prevents 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?

Given the lack of an output schema and the tool's broad nature, the description covers scope, trigger phrases, examples, dispatch behavior, argument filling, and return format with citation URIs. It does not explain behavior on ambiguous or unanswerable queries, nor how to route between the sibling ask_pipe variants, but it is sufficiently complete for correct selection in most factual-query scenarios.

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?

All six parameters are already documented in the schema — five as aliases and one as the natural-language question — so the baseline is 3. The description contributes beyond the schema by adding real-world example queries and trigger phrases that clarify the expected content and specificity of the `question` 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 clearly states a specific verb ('prefer', 'routes') and resource: it is an answer router that handles factual questions about real-world data by dispatching to one of 5,596 tools and returning citation URIs. It distinguishes itself from web search, but it does not differentiate itself from the sibling ask_pipeworx_beta, ask_pipeworx_grounded, or deep_research.

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

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

It gives explicit trigger language ('what is', 'look up', 'get the latest', 'current'), provides concrete examples, and states 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. However, it offers no when-not-to-use guidance and does not name any sibling alternatives, leaving the selection boundaries relative to related tools somewhat implicit.

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

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

The annotations already indicate read-only and non-destructive behavior, and the description adds meaningful behavioral context: this is an experimental edge, candidate routing improvements may be live, no candidate is currently active, and it is a full working router with no fallback wrapper. This goes beyond the structured hints and contains no contradiction.

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

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

The description is dense but efficient: first sentence defines the tool, second gives the current operational state, and subsequent text covers invocation and experimental behavior. Each sentence contributes relevant information with the beta/current-state info front-loaded.

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

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

For a free-form question-only tool with read-only annotations and 100% schema coverage, this description is largely complete: beta behavior, current state, invocation guidance, and response-shape stability are covered. The only minor gap is that actual returned answer format is delegated to 'same response shape' as ask_pipeworx rather than described in this definition, and there is no 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%, with parameters documented as aliases for the question input. The description only adds that the tool shares ask_pipeworx's arguments and does not add semantics beyond the schema. Baseline 3 is appropriate because the schema already covers the parameter details.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx and states that it is a universal router with the same 5,596 tools, arguments, and response shape. It differentiates it from ask_pipeworx by the candidate routing improvements and experimental edge, though the core 'ask a question / get an answer' action is expressed via the router concept and comparison to ask_pipeworx rather than independently.

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 selection guidance: use it exactly like ask_pipeworx when you want the newest routing, and results are compared against the stable router. It also clarifies current state—no candidate is active, so it currently matches ask_pipeworx exactly—which directly helps a caller decide whether and how to invoke 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/openWorld/idempotent annotations, the description discloses key behaviors: it extracts only from the fetched result, returns a defined success shape with evidence and refusal reason, enumerates every refusal_reason value, and states the exact cost tradeoff of one additional LLM call. 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 front-loaded with the core purpose and includes only decision-relevant information: behavior, return shape, refusal conditions, use cases, and cost tradeoff. Every sentence earns its place, and the structure moves from what the tool does to when it should be chosen.

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, but the description compensates fully by specifying the success return payload and the refusal payload with all refusal_reason enum values. Combined with 100% schema coverage for parameters and the annotations, the agent has everything needed to correctly select and invoke this 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%: all six parameters are documented as aliases for the same natural-language question. The description adds the context that the tool fills arguments internally, but it does not add meaning beyond what the schema already provides. The baseline of 3 is appropriate.

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

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

The description states a specific, named mode ('hallucination-resistant answer mode for high-stakes reads') and explains exactly what it does: routes like ask_pipeworx, fetches data, and extracts an answer strictly from the tool result. It clearly differentiates this tool from its sibling ask_pipeworx based on groundedness versus casual lookups.

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

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

Usage guidance is explicit: use this tool when an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples like financial verdicts and legal claims. It also gives the when-not case, explicitly preferring ask_pipeworx for casual lookups and noting the extra LLM cost.

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

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

The description goes far beyond the readOnly/idempotent annotations by detailing internal behavior: fan-out parallelism, resolver confidence levels, low-confidence short-circuiting, closed-market status, spread warnings, cancellation-rules risk, and news fallback handling. This gives the agent a deep understanding of what to expect and what is unsafe.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Each section provides operational value, though the overall length is near the upper bound for a tool description; it could have been slightly trimmed.

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

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

There is no output schema, so the description carries the full responsibility of explaining return values and edge cases. It thoroughly documents the response shapes, resolver metrics, parent_event data, news fallback fields, safety short-circuits, and cancellation-rule risk. For a complex tool, this is highly complete.

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

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

The schema already fully documents all three parameters with descriptions and examples, covering 100% of the parameters. The description repeats the market slug/URL/question text formats but does not add new parameter-level semantics beyond what the schema provides. Baseline is appropriate at 3.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools by defining its scope (polymarket bets, data packs, market-vs-model comparison) and by naming concrete use cases like 'should I bet on X' and 'what does the data say about Y'.

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 ('Use for "should I bet on X"...') which tells the agent when to invoke the tool. It also implies it is preferable to doing multiple lookups, but it does not explicitly name alternatives or exclusions (e.g., 'for arbitrage use polymarket_arbitrage'), so it falls just short of the strongest 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, establishing the safety profile. The description goes well beyond annotations by disclosing what data is pulled (latest 10-K, FAERS counts), how off-calendar fiscal years are handled, sorting by primary metric, and the return format (paired data + pipeworx:// citation URIs). This rich behavioral context adds significant value and does not contradict any 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 contributes unique value: trigger phrases, usage preference, type-specific data details, fiscal-year handling, sorting behavior, and efficiency claim. It is front-loaded with examples and structured logically. It could be slightly tightened, but the density of useful information justifies the length.

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

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

With no output schema, the description takes on the burden of explaining return behavior, and it does so by mentioning paired data, citation URIs, and sorting. It also covers both entity types and addresses a known complexity (off-calendar fiscal years). Minor gaps remain, such as how errors are handled or whether values are tickers vs names for drugs, but the provided context is solid for a tool of this complexity.

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

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

The input schema covers both parameters with types, enums, min/max, and examples, achieving 100% coverage. The description adds domain-specific semantics beyond the schema: it explains that type='company' pulls latest 10-K financials and type='drug' pulls FAERS/trial data, and that results are sorted by primary metric. This enhances understanding of how parameter values influence behavior, though the schema already provides baseline clarity.

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: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also distinguishes itself from siblings by explicitly contrasting with 'sequential single-pack lookups' and by detailing type-specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). This leaves no ambiguity about the tool's core function.

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 trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger...') and a strong preference rule ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'). It also clarifies that it handles off-calendar fiscal years, giving context for when results may look unconventional. However, it does not explicitly mention alternatives like entity_profile for single-entity lookups, so the 'when-not' guidance is somewhat implied rather than fully explicit.

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

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

Richly discloses beyond annotations: account/pricing requirements, parallel decomposition across sibling tools, latency ranges, findings-packet contents, never-invented gaps, citation semantics including when citations are fetchable, semantic excerpting, and contradiction scans for certain depths. No conflict 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?

Every sentence is dense and useful, but the description is a long, semicolon-heavy paragraph that leads with account prerequisites rather than the core purpose. It is not bloated, but it is less concise and less front-loaded than ideal.

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 that there is no output schema, the description compensates by describing the findings packet, citation behavior, gaps handling, latency, depth modes, and account requirements. It is sufficiently complete for a complex tool with only two parameters.

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

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

Schema coverage is 100% so the baseline is 3. The description enhances this by clarifying that questions can be broad/multi-part and that 'thorough' depth requires a paid plan, though the depth parameter itself is already well-explained 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?

States a specific verb+resource: grounded multi-source research across 1,465 structured data sources in one call, explicitly clarifying what it is not (open-web search) and what it returns. The description clearly differentiates it from the single-lookup sibling ask_pipeworx.

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

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

Gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, not for single lookups, and explicitly routes unsigned-in users to ask_pipeworx. It also states the account/payment precondition and the alternative behavior.

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 read-only/idempotent annotations, the description discloses that results include names, descriptions, full input schemas with curated examples, and are 'ready to call directly, no second schema lookup needed.' This is valuable behavioral detail that goes beyond the annotations. It does not cover pagination or rate limits, but annotations already convey the safety profile.

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

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

Three sentences with clear front-loading of purpose and usage. The list of domains is long but serves to illustrate scope. Minor redundancy with schema examples but overall compact.

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 interface and no output schema, the description sufficiently covers the tool's behavior and return format. It could mention default limit or output shape, but the description's mention of top-N and included schemas is adequate.

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 fully documents the query parameter and aliases. The description adds a high-level sense of query usage but does not go beyond the schema's parameter 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?

Description clearly states the tool 'finds tools by describing the data or task' and enumerates a broad set of domains, distinguishing it from sibling tools that perform specific tasks. The verb 'find' plus resource 'tools' makes the purpose unambiguous.

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

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

Explicitly instructs to 'Call this FIRST when you have many tools available and want to see the option set,' providing clear when-to-use guidance. It also says 'Use when you need to browse, search, look up, or discover what tools exist,' giving context relative to 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?

Even though annotations already mark readOnly/openWorld/idempotent, the description adds rich behavioral detail: enumerates data sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), notes the USPTO PatentsView API sunset 'May 2025 — soft-fails until reactivated,' and explains the parallel fan-out and fallback chain. It also describes the exact return fields, which is essential given the lack of an output schema.

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 fairly long but well-structured and front-loaded with usage examples. Every sentence carries useful information—usage guidance, output details, source limitations, and parameter constraints. It is slightly redundant with the schema's parameter descriptions, but not enough to drop below a 4.

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 enumerates all returned data: cik + company_name, recent_filings with URIs, fundamentals, patents, news, and LEI. It also covers edge cases like soft-failure for USPTO and GDELT→GNews fallback, making the tool's behavior predictable and complete for an agent.

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

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

Schema description coverage is 100% and both parameters are thoroughly described in the schema (type enum and value with ticker/CIK examples and 'names not supported'). The description repeats these details (examples 'AAPL' and '0000320193') but adds no new parameter-level meaning beyond the schema, so it gets the baseline score.

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

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

The description clearly states the tool's function with a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and references resolve_entity for name-only inputs.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives a when-not-to-use note: 'names not supported (use resolve_entity first if you only have a name).' This clearly guides selection among sibling tools.

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

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

Annotations already declare destructiveHint and idempotentHint, and the description adds context about what gets destroyed ('previously stored memory by key', 'sensitive data'). This is useful beyond the annotations and does not contradict them, though it does not add details on auth or side effects.

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

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

Three concise sentences: statement of function, usage context, and pairing with related tools. Every sentence earns its place with no redundancy or fluff; it is front-loaded with the core action.

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 one-parameter schema, rich annotations, and no output schema, the description fully covers the essential context: what it does, when to use it, and how it relates to siblings. No important gaps remain for a delete 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%, with the property 'key' described as 'Memory key to delete'. The description adds no new semantics beyond saying 'by key', so it provides baseline value but no extra parameter guidance.

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

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

The description uses a specific verb 'Delete' and resource 'previously stored memory by key', clearly distinguishing it from sibling tools like remember and recall. It is not a tautology and states exactly what action is performed.

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

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

The description provides explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, but does not explicitly state when not to use or name alternative tools for exclusion, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context by detailing the fetch-extract-emit workflow and the exact 'single text blob' output, which 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 three sentences long and highly efficient: main action, process/output, then use cases. Every sentence earns its place, and it is front-loaded with the core purpose.

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

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

For a simple read-only tool with complete schema and supportive annotations, the description covers purpose, process, output format, and use cases. It even describes the output as 'ready to drop at site-root/llms.txt', which compensates for the absence 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?

The input schema has 100% description coverage for both url and max_links, so the schema carries the parameter documentation. The description does not add extra parameter-level semantics, warranting the baseline score of 3.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb+resource. It also explains the process (fetch, extract, emit) and the output format, making it unmistakable and distinct from sibling tools like ai_visibility_check.

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

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

The description provides three concrete use cases: getting a client's site indexed, drafting your own llms.txt, and auditing a competitor. It gives clear context for when to use it, but does not explicitly mention alternatives or exclusion criteria, so it falls short of a 5.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds meaningful context by listing the returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the scope to the caller's own subscriptions, 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 two sentences: the first states the core purpose and return fields, the second gives a usage suggestion. It is concise, front-loaded, and contains no unnecessary words.

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

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

For a simple read-only listing tool, the description includes the return fields, the scope (caller's subscriptions), and usage guidance. The schema covers the only parameter, making the description sufficient 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?

The schema has a single optional parameter include_inactive with a description explaining its meaning, providing 100% schema coverage. The tool description does not add additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb 'List' and resource 'subscriptions'. It also distinguishes from siblings like subscribe/unsubscribe by mentioning use cases for review before adding or canceling.

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

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

The description explicitly provides usage context: use it to review what you're monitoring before adding more subscriptions, or to find an ID to cancel. This implies the alternatives (subscribe/unsubscribe) and guides the agent on when to select 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?

With all annotation hints false, the description carries the full burden and does so well. It discloses rate-limiting ('Rate-limited to 5 per identifier per day'), the claim_token feedback loop for later follow-up, and that it is free and doesn't count against tool-call quota. No contradiction with annotations.

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

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

The description is long but every sentence earns its place—covering scope, usage, security, rate limits, and follow-up. It front-loads the core purpose and organizes the guidance logically, though some sentences could be tightened without losing meaning.

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

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

With no output schema, the description thoroughly explains return behavior (claim_token, later status read), usage constraints (rate limit, quota), and the follow-up mechanism. The nuances of feedback categories are well covered, making it complete for the tool's complexity.

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

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

The schema already covers all 4 parameters with descriptions (100% coverage), so baseline is 3. The description adds value by specifying claim_token usage with exact syntax ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), advising users not to paste the end-user's prompt, and instructing them to describe issues in terms of Pipeworx tools/packs.

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

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

The description explicitly states 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates the exact categories (bug, feature/data_gap, praise). It also clearly distinguishes its scope to only Pipeworx-served tools, separating it from other MCP server connectors.

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

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

It provides explicit when-to-use conditions for each feedback type and an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also gives a practical disambiguation hint ('Not sure? 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 mark read-only, idempotent, and non-destructive. The description adds valuable context beyond these: data is 'self-aggregating', derived from 'CF analytics-engine', contains 'no PII', and is 'cached 5min-1h depending on window'. This explains the aggregate nature, privacy, and freshness 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 compact and well-structured, with each sentence earning its place: a hook question, the core output, a bulleted use-case list, and a data caveat. It is front-loaded and has zero filler.

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

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

For a simple read-only analytics tool with one optional parameter and no output schema, the description covers purpose, use cases, data provenance, privacy, and caching. This is sufficient context for an agent to decide when to use the tool and what to expect from the result.

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 'window' parameter, including default and interpretation. The description merely echoes the window values and does not add any new semantic meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool 'returns the top tools, top packs, and total call volume over a recent window', which is a specific verb+resource+scope. The opening line 'What other AI agents are calling on Pipeworx right now' distinguishes it as an aggregate usage signal, distinct from sibling tools like discover_tools or recent_alerts.

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

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

The description lists three explicit use cases: discovering hot data sources, confirming a canonical tool choice, and aligning use case with agent demand. This provides strong context for when to use it, though it doesn't explicitly mention alternatives or when-not-to-use, lacking the full 'when-not/alternatives' guidance for 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?

The description extensively discloses behavior beyond the annotations: it walks child markets, applies similarity thresholds, filters placeholder slugs, checks live CLOB depth, and differentiates theoretical vs realizable edge. No contradiction with the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) exists; in fact, the description adds detailed context that the 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 long but every sentence carries operational weight. It uses clear section breaks (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. The structure helps the agent navigate a complex tool without wasted text.

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

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

With no output schema, the description fully specifies the return shape (opportunities[], partition_check, fill_check) and covers edge cases like low similarity, placeholder fractions, and thin books. Given the tool's complexity and two modes, the description is remarkably 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?

Despite 100% schema coverage, the description adds substantial meaning to both parameters: event is defined with slug/URL formats and recommendations, topic is explained with search behavior and examples. It goes far beyond the schema by explaining the consequences of each parameter and providing decision guidance.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with explicit mode distinctions (trending_scan, event, topic). It names the specific resource and verb, and the differentiation from siblings like polymarket_edges is implicit through the unique methodology.

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

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

The description provides explicit guidance on when to call with no args, when to use event vs topic, and even when not to trade (realizable_edge_pp ≤ 0). It also points to an alternative tool (polymarket_fill_risk) for custom sizing, making the usage context and exclusions very 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 adds substantial behavioral context beyond the annotations: caching behavior ('Cached 1h at the KV level'), response diagnostics (_diagnostics with funnel counters), the 24h-move warning, and the rare-by-design nature of concentrated longshots with degraded gates. It also explains why fed candidates are excluded from ranking, which is crucial behavioral insight. No contradiction with readOnlyHint=true.

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 highly structured with clear section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Every sentence adds information relevant to invoking or interpreting the tool. It is not bloated, but its length demands careful reading, so it misses a 5 for being somewhat dense.

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

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

With no output schema, the description fully compensates by detailing the response structure: by_segment contents, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), the diagnostic object, and caching. It even explains edge cases like empty segments and the unreliable fed signal, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the schema already documents all 9 parameters. The description adds value by grouping them into 'TRADEABLE-EDGE KNOBS' and explaining their intent (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable'), and by clarifying min_partition_leg_kelly's special per-leg behavior. This goes beyond the baseline by connecting parameters to the tool's filtering philosophy.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings by detailing the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and the response segmentation, making its unique value proposition 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?

The description provides a clear use case ('Built for "what should I bet on today"') and explains when to apply tradeable-edge knobs (e.g., min_liquidity/max_spread_pp for realizable edges). It also warns against relying on fed candidates ('unreliable at meeting-month horizons'). However, it does not explicitly name alternative tools, so it stops short of full when/when-not alternative guidance.

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

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

The description adds substantial behavioral context beyond the annotations: the 60-day snapshot TTL, dependency on when snapshotting was enabled, cache-miss behavior causing data gaps, and the fact that decay numbers are computed from daily closes (not intraday). It also fully explains the response structure, including edge cases like expired opportunities.

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

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

The description is dense but every sentence serves a purpose. It opens with a clear purpose statement, then quickly defines the key question, parameters, response structure, and limitations. The structure is logical, with explicit labels for arguments and response fields, making it 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?

With no output schema, the description takes full responsibility for explaining the return values, which it does comprehensively: tracked[], expired[], and snapshot_dates[] with their subfields and meanings. It also covers data limitations, historical depth, and computational details, leaving no critical gaps for a tool of this complexity.

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

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

The input schema already provides 100% coverage for both parameters (days, window) with clear descriptions, including defaults and allowed values. The description's Args line adds no new information beyond restating the schema. Thus, the baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay from daily polymarket_edges snapshots. It distinguishes itself from siblings like polymarket_edges by focusing on historical persistence rather than current edge values, and the specific question it answers is explicitly stated.

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

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

The description provides clear context on when to use this tool (to assess how long an edge has existed and whether it's shrinking) and why that matters (a fresh wide edge differs from an old wide edge). It does not explicitly name alternative tools or state when not to use it, but the use case is strongly implied.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral disclosure: it 'walks the ladder,' returns specific fill metrics (top_of_book, vwap_fill_price, slippage_pp), and names 'forced_directional_risk' legs. It also warns about partial basket fills converting an arb into unhedged directional positions, providing deeper behavioral context beyond the annotations.

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

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

The description is long but front-loaded and efficiently structured: one-sentence purpose, then REQUIRES, then clear sections for SINGLE-MARKET and BASKET, ending with usage context. Every sentence adds value, detailing return values and risk rationale. No filler or redundant 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?

With no output schema, the description properly explains return values for both modes, including per-leg fill detail and thin_legs[]. It covers all parameters, mode-specific behavior, and the tool's role in an arb workflow. Given the tool's complexity (two modes, 4 params), the description is fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful parameter interpretation beyond the schema: it explains how `size_usd` is interpreted differently in single-market vs basket mode (max spend/target proceeds vs settlement notional shares per leg) and how `side` auto-defaults in basket mode based on partition sum. This extra semantic context justifies a 4.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools (polymarket_arbitrage, polymarket_edges) by focusing on fill risk and explicitly states its role as a pre-trade risk check. The two modes (single-market and basket) are clearly outlined.

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 includes explicit usage direction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why it should be used (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), providing both when and why context.

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

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

Beyond the read-only annotations, the description richly discloses behavior: it explains compatibility_warning conditions (non-equivalent bet shapes, unmatched events), temporal_alignment as a validity check, and skipped_cross_type counters. It also warns that pre-mapped topics often return warnings, which is valuable behavioral insight with no annotation contradiction.

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

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

The description is comprehensive but lengthy, packed with detailed field explanations and safety conditions. It is front-loaded with the core purpose but could be structured more concisely (e.g., using sections) to improve scannability. Every sentence adds value, but the density is high.

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

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

Without an output schema, the description assumes the responsibility of explaining the response shape, which it does thoroughly (leg-by-leg prices, spread array, compatibility_warning, temporal_alignment, skipped counters). It covers edge cases and limitations, making the tool fully understandable for an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the override behavior of explicit parameters over topic-mapped sides and the overall mode concept. This enriches parameter understanding beyond simple 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 states a specific, well-defined purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from likely sibling tools (e.g., Polymarket-only tools) by emphasizing the cross-venue comparison and the two modes of operation.

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

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

The description provides clear usage context with two explicit modes (topic shortcuts and explicit event pairings) and a caution that most pre-mapped topics return compatibility_warning, setting expectations for when the tool is useful. It does not explicitly contrast with alternative tools, but the coverage is strong enough to warrant 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 declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds value by disclosing the return behavior ('Returns predicted age and confidence count based on name frequency data'), which goes beyond the annotations.

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

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

The description is two sentences and 21 words, immediately stating the core purpose and return value. Every word contributes meaning, 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 one-parameter tool with an output schema and strong annotations, the description adequately covers the prediction logic and what is returned. It does not discuss edge cases like uncommon names or data sources, but given the low complexity and existing schema, this is not a critical gap.

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

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

The schema already describes the 'name' parameter as 'First name to predict age for' with examples, so schema coverage is 100%. The description merely repeats 'first name' without adding new syntactic or semantic details, thus offering no additional value beyond the schema.

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

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

The description uses a specific verb 'Estimate' and clearly identifies the resource ('someone's age from their first name') and method ('using global statistics'). It distinguishes itself from the sibling tool predict_age_country by specifying global scope, so the agent knows the difference.

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 phrase 'using global statistics' implies this tool is the global variant, contrasting with predict_age_country among siblings. However, it does not explicitly state when not to use it or provide direct alternative references, so it misses the full 'when/when-not' 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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context by specifying the return behavior (predicted age and regional confidence count) and the country-scoped nature of the prediction. It does not contradict annotations and provides sufficient transparency for a simple read operation.

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

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

The description is two concise sentences. The first sentence front-loads the core function, and the second states the return values. There is no filler or redundant 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?

For a simple tool with annotations and an output schema, the description is largely complete: it explains what the tool does and what it returns. The only gap is the absence of explicit usage guidance relative to sibling tools, but this is a minor omission given the clarity of the function and the presence of structured metadata.

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 of both parameters with clear descriptions. The tool description adds no new semantic detail beyond the schema; the country examples ('US', 'FR', 'JP') are repeated from the schema. The phrase 'regional confidence count' hints at the country_code's role, but this is already implied by the schema's 'to localize the prediction.'

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

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

The description uses the specific verb 'estimate' with the resource 'age from first name' and the scope 'within a specific country', clearly distinguishing it from the sibling tool predict_age. It also provides examples of country codes and states the return values (predicted age and regional confidence count), making the purpose unambiguous.

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

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

The description implies usage when a specific country is known ("within a specific country"), but it does not explicitly state when to use this tool versus alternatives like predict_age. No exclusions or alternative recommendations are mentioned, so guidance is implicit rather than explicit.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping details ('Scoped to your identifier') and the behavior of omitting the key to list all keys, going beyond the annotations without contradicting them.

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

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

Two sentences with no wasted words. The main action is front-loaded, followed by usage context and scoping. Every clause 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 single-optional-parameter read tool with rich annotations, the description covers purpose, usage, scoping, and sibling relationships. No output schema exists, but the described return behavior ('value' or 'list all keys') is sufficiently clear for this tool's simplicity.

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

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

Schema coverage is 100% and already describes the key parameter including omission behavior. The description adds concrete examples of key contents ('user's target ticker, an address, prior research notes'), which provides semantic guidance 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 'Retrieve a value previously saved via remember, or list all saved keys' – a specific verb and resource. It explicitly distinguishes from sibling tools like remember (save) and forget (delete), 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 says 'Use to look up context the agent stored earlier' and names complementary tools 'remember' and 'forget', providing strong usage context. It lacks an explicit 'when not to use' exclusion, but the alternative of re-deriving information is implied with 'without re-deriving it from scratch'.

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 declare readOnlyHint: true, implying no state side effects. Yet the description explicitly describes mark_read:true as 'flag returned events read so the next call only shows newer ones,' which mutates the feed's read state. This is a direct contradiction between the description and the annotations, warranting a score of 1 per the rubric.

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 slightly longer than ideal (five sentences) but every sentence contributes meaningful detail: the core action, return contents, filtering, mark_read side effect, and alternative endpoint. It is front-loaded and avoids fluff, earning a 4.

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

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

Given the tool has 5 optional parameters and no output schema, the description effectively covers the return payload (source, citation_uri, raw event payload) and key behaviors (mark_read filtering, polling suitability). It lacks explicit ordering/clustering details but is otherwise complete enough for an agent. The annotation contradiction slightly undermines context, but the description itself is robust.

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

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

The schema already covers all parameters at 100% coverage, establishing a baseline of 3. The description adds extra value by providing a concrete type example (sec_8k), reinforcing the ISO timestamp format for since, and explaining the downstream consequence of mark_read (next call shows newer events). This exceeds the baseline.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly distinguishes itself from sibling tools like list_subscriptions or recent_changes by focusing on reading persisted alerts. The mention of filters and return payload further clarifies its unique role.

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

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

The description gives clear context: it's for reading your own subscription feed, supports polling, and notes an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly name sibling tools or provide when-not-to-use scenarios, only mentioning an alternative access method, so it stops short of a full 5.

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

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

Annotations already provide readOnlyHint and idempotentHint, but the description adds substantial behavioral detail: it fans out to multiple APIs, falls back from GDELT to GNews on rate limits, and discloses the PatentsView sunset with soft-fail. It also mentions citation URIs and structured output, going far beyond annotation basics.

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 remarkably dense—every sentence provides operational detail (sources, fallback, input syntax, output shape). It front-loads likely user queries and structures information logically with semicolons and examples. No wasted words, though it could be slightly shortened without losing meaning.

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

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

This is a complex tool with multiple external APIs and fallback logic, and there is no output schema. The description fully covers input formats, data source behavior, fallback specifics, output structure (changes[], total_changes, citation URIs), and the appropriate alternative tool. It provides all necessary context for correct invocation.

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

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

The schema covers all three parameters at 100%, so baseline is 3. The description adds extra value by recommending specific since values ('30d' or '1m') and providing clear examples for value ('AAPL' or zero-padded CIK). This exceeds the baseline without being redundant.

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 defines the tool as a 'change feed for a company in the last N days/weeks/months' and specifies the exact data sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes from the sibling tool entity_profile by naming it explicitly for static profiles, leaving no ambiguity about scope.

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 opens with concrete user intents ('What's new', 'latest on', etc.) and clearly states when to use this tool. It explicitly directs users to entity_profile instead for static profile needs, providing a clear alternative and avoiding misuse.

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

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

Beyond the annotations, the description adds useful context: memory is a key-value pair scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain data for 24 hours. However, it does not disclose what happens when the same key is saved again (overwrite vs. error), which would have been valuable given the idempotentHint.

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

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

The description is compact—three sentences—but every sentence earns its place: it states what the tool does, when to use it, how storage works, and which sibling tools to pair it with. There is no redundant or filler content.

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

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

For a simple two-parameter tool with strong annotations and no output schema, the description covers purpose, usage, memory scope, persistence rules, and pairing with recall/forget. It is sufficiently complete for an agent to know when and how to invoke this tool correctly.

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

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

The input schema already covers both parameters with clear descriptions and examples (e.g., 'target_ticker', 'user_preference'), giving full 100% coverage. The description reinforces the key-value nature and scoping by identifier, but it adds limited new parameter-specific meaning beyond what the schema already communicates.

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: 'Save data the agent will need to reuse later.' It clearly distinguishes itself from sibling tools like recall and forget by framing itself as the write operation in the memory workflow, and it even names those counterparts.

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

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

It provides explicit when-to-use guidance with concrete examples like 'a resolved ticker, a target address, a user preference, a research subject' and explains the motivation ('so you don't have to look it up again'). It doesn't explicitly state when not to use it, but it clearly communicates appropriate contexts and correlates with recall/forget as complementary tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value beyond these by explaining graceful degradation ('LEI/FIGI enrichment degrades gracefully'), internal cascading ('cascades through several lookup endpoints internally'), and visibility into unresolved identifiers ('stated explicitly under unresolved'). No contradiction with annotations.

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

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

The description is front-loaded with example queries and a clear purpose statement. While it is verbose, every sentence adds distinct information (supported types, sources, degradation behavior, unresolved identifiers). It could be slightly more compact, but the structure is logical and efficient for the information density.

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

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

Given the tool's complexity (multi-source entity resolution) and lack of output schema, the description fully compensates by detailing return components (identifiers labelled by source, unresolved list), sources used (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), and edge cases (degradation, ISIN-to-LEI mapping for non-US issuers). Annotations cover idempotency and safety, leaving no critical gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description significantly enriches parameter meaning: for 'type' it details what identifiers each entity provides (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient for drug). For 'value' it expands acceptable inputs (ISIN, company name, ticker, etc.) with specific examples like 'CH0038863350' and coverage of non-US issuers.

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 like 'resolve' and provides example queries ('What's the ticker for...', 'find the CIK for...'), making the tool's action clear. It explicitly states the supported types (company, drug) and distinguishes the tool from siblings by recommending 'Use FIRST whenever you have a name but need an ID.'

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 indicates when to use the tool (when you have a name but need an ID), details input formats (ticker, CIK, ISIN, name for company; brand/generic for drug), and notes that resolve_entity replaces 2-3 manual lookups. However, it does not explicitly state when NOT to use it or list alternative tools, though the sibling context implies differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral detail beyond annotations: it states that the tool 'Probes each entity ... with ai_visibility_check', 'ranks by score', and 'Returns ranked list with score, confidence, signal density per entity'. This gives concrete insight into the orchestration logic and output structure, going beyond the safety profile 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 three sentences, each earning its place: the first states the core action, the second explains the mechanism and ranking, the third provides a use case and return format. No unnecessary words or redundant repetitions of schema content.

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

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

The tool has no output schema, so the description appropriately includes the return shape ('ranked list with score, confidence, signal density per entity'). It also covers purpose, mechanism, and use case. Minor gaps exist—such as not explaining model selection semantics or potential rate limits from multiple probes—but those are documented in the schema and annotations, respectively. Overall complete for the tool's complexity.

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

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

Schema coverage is 100% with detailed descriptions for all four parameters, including the first-entity-as-subject convention for 'entities'. The description adds minimal parameter-specific meaning beyond the schema—it restates the entity role ('your brand + N competitors') and mentions the probing action, but does not clarify model selections, _apiKey usage, or context semantics 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 clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side'. It uses a specific verb ('Compare') and resource ('AI visibility'), and differentiates itself from the sibling tool ai_visibility_check by focusing on multiple entities rather than a single one. The phrase 'side-by-side' and mention of 'competitors' also distinguishes it from generic 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 provides a clear use case: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use the tool versus a single-entity check, but does not explicitly name alternatives such as ai_visibility_check for single-entity scenarios. This is clear context without explicit exclusions, aligning with a score of 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 declare this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond those: it discloses fan-out to two services, the specific returned fields, and the partial failure grace behavior including bundlephobia's 5-30s first measurement and 'sources_failed' field. 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 front-loaded with the core purpose, then flows through usage, return structure, ecosystem constraints, and failure behavior. It's dense but every sentence adds useful information; no filler.

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

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

Despite lacking an output schema, the description enumerates the summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory details, links, and alternative versions. It also covers timeout behavior and degraded partial results, making it highly 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?

Input schema covers both parameters at 100% with clear descriptions. The description reinforces that the package is npm-specific but does not add syntax/format details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a composite npm package dependency check, naming deps.dev and bundlephobia as fan-out sources. It uses a specific verb+resource phrase and distinguishes it from sibling research/analysis tools by its focus on npm packages.

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".' Also provides an exclusion: 'NPM ecosystem only in v1' and directs other ecosystems to 'deps.dev:version directly,' offering 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 state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial operational detail: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)' and explains output includes character offsets for 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?

The description is dense but every sentence earns its place: purpose, usage, pairing, technical details, and input constraints. It is front-loaded with the core purpose and is appropriately sized for a tool with nuanced behavior and no output schema.

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

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

With no output schema, the description explains the return value: 'top-N passages with character offsets and similarity scores'. It also covers edge cases (truncation and flagging) and provides a workflow context with ask_pipeworx_grounded, making the description complete for the tool's complexity.

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

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

Schema covers 100% of parameters with descriptions. The description adds meaning by giving concrete examples of what 'text' can be ('a SEC 10-K body, an article, a long tool result') and clarifies that the text is already pulled from a record. It also implies search behavior via 'top-N passages', enriching the query parameter's intent.

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

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

The description opens with 'Semantic search INSIDE a fetched record', clearly stating the verb (search) and resource (a fetched record). It distinguishes itself from sibling tools by emphasizing it operates on already-fetched text and by explicitly pairing with ask_pipeworx_grounded for grounding over relevant passages.

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

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

The description provides explicit usage guidance: 'Use when the record is too big to cram into the prompt' and explains how it saves context. It also names the alternative ask_pipeworx_grounded and describes the intended workflow ('fetch with the gateway, ground over the relevant passages instead of 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 non-read-only, idempotent, open-world, non-destructive. Description adds valuable operational context: authentication requirement, persistence limitation, SMS verification and cap, and feed availability. 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?

Well-structured with purpose first, then requirements, supported types, and delivery options. All sentences carry relevant information, though a bit dense with inline examples. Competitively concise 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?

For a tool with nested objects and no output schema, description covers purpose, return value, auth requirements, types, and delivery constraints. Does not explicitly reference sibling lifecycle tools but provides enough to operate effectively.

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

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

Schema description coverage is 100%, so the schema provides comprehensive parameter details. The description adds minimal new semantics; examples mirror the schema but do not clarify anything not already documented. Baseline 3 is appropriate.

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

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

Description clearly states the action ('Create'), the resource ('proactive monitoring subscription to a live-data event stream'), and the return value ('Returns the new subscription id'). It distinguishes from sibling tools like list_subscriptions (listing) and unsubscribe (removing) by focusing on creation.

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 usage context: requires OAuth account, notes anonymous/BYO cannot persist, and details delivery channels (always-on feed with pull alternatives, optional email/sms with constraints). Does not explicitly reference sibling management tools but gives sufficient context for when to use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context beyond that: it describes the return format ('category-bucketed example questions... exact tool + argument shape'), the optional `topic` focusing behavior, and that results are 'drawn from the live catalog'. 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 long, dense sentence with many clauses and parentheticals. It conveys a lot of useful information without obvious fluff, but could be more readable with bullet points or shorter sentences. It earns a score above average but not top-tier.

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

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

There is no output schema, so the description carries the burden of explaining return values—which it does ('Returns category-bucketed example questions... each with the exact tool + argument shape'). It also covers the optional parameter behavior and the intended use case. For a read-only onboarding tool with clear annotations, this is complete.

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

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

Schema description coverage is 100% for the single `topic` parameter, so the schema already documents the allowed values and the omit behavior. The description adds only minor context (e.g., focusing, 'finance', 'pharma' examples) that is largely redundant. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Returns category-bucketed example questions' with 'the exact tool + argument shape'. It positions itself as 'the onboarding entry point' and distinguishes from siblings like ask_pipeworx by saying 'Use this FIRST' for learning what Pipeworx can do.

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

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

It gives an explicit when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains when to pass `topic` vs omit it. However, it does not name alternatives or explicitly say when-not-to-use other tools, so it falls slightly 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?

The description adds valuable behavioral context beyond the annotations: ownership enforcement, soft-delete semantics (deactivated, not deleted), and preservation of historical events via recent_alerts. This complements the existing idempotentHint and destructiveHint annotations without contradiction.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds relevant information. No wasted words; concise and well-structured.

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

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

For a simple one-parameter tool with no output schema, the description covers all necessary context: ownership restriction, the deactivation behavior, and downstream consequences. It is fully adequate for the tool's complexity.

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

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

Schema coverage is 100% for the single 'id' parameter, which is described as 'Subscription id (uuid) returned by subscribe.' The description merely reinforces this by saying 'Cancel a subscription by id,' adding no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states the action clearly with 'Cancel a subscription by id,' using a specific verb and resource. It differentiates from sibling tools like subscribe and list_subscriptions by explaining the deactivation behavior and connection to recent_alerts.

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

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

The description provides clear context for when to use this tool: to cancel a subscription, with the key constraint that only one's own subscriptions can be canceled. It doesn't explicitly name alternative tools, but the behavioral nuance (deactivate vs delete) helps the agent choose appropriately.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context beyond those hints: it explains the routing behavior, the exact semantics of `could_not_verify` (check did not happen, not evidence for/against) and `unsupported`, and describes the return format with citation and reasoning. This is more than sufficient and does not contradict 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 and front-loaded with trigger phrases and a clear purpose statement. Each section (routing, verdicts, error semantics) earns its place, though the opening enumeration of user phrasings could be trimmed. Overall, it is appropriately sized 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 routes, six verdicts, error semantics) and lack of an output schema, the description is remarkably complete. It explains return values, special verdict meanings, and the operational context (replaces multi-step pipeline). Nothing critical is missing for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the default behavior of `tolerance_pct` ('implied by wording, capped at 5') and offering practical guidance like 'set 1–2 for hallucination detection.' This enriches the schema's parameter 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 natural-language trigger phrases and clearly states the tool performs 'natural-language claim verification against authoritative sources.' It also distinguishes its role from siblings by describing the two routing paths (financial vs. grounded) and the specific verdict types returned. This is a specific verb+resource pairing with strong differentiation.

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

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

The description explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further details when the SEC EDGAR path vs. the grounded pipeline applies, and notes that it replaces 4–6 sequential calls, indicating this is the high-level tool. However, it does not name sibling alternatives (e.g., ask_pipeworx_grounded), so guidance is clear but not fully exclusive.

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