dogsapi

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

Annotations already declare readOnlyHint: true and openWorldHint: true. The description adds meaningful behavioral details: default model is free, passing `_apiKey` incurs direct Anthropic costs, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This enriches the annotation profile 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?

Three sentences, each earning its place: first states the core function, second covers default model and key handling, third explains return format and use cases. Front-loaded with the primary purpose, 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?

With no output schema, the description appropriately discloses return shape ('per-model {score, confidence, signals, raw_response} + combined view'). It covers parameters, defaults, costs, and use cases. Slightly more detail on what 'signals' means would raise it to 5, but as-is it is adequate for a 4-parameter tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying the default for 'models' (Workers AI Llama-3.3-70b, free) and the cost implication of '_apiKey' ('BYO key — you pay Anthropic directly'), which goes beyond the schema's 'optional' label.

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 action ('Probe one or more LLMs') and resource ('business / brand / product / topic') with a clear output ('score visibility (0-100) per model'). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on LLM knowledge scoring and explicitly listing use cases (AI-marketing audits, pre-launch brand checks).

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

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

The description provides clear usage context with 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives or exclusions, but the use cases imply when to reach for this tool over siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond those hints: it routes to one of thousands of tools, fills arguments, returns structured answers with stable citation URIs, works on every tier, and performs in 'one fast call.' It also explicitly notes that it already covers breaking-news via the *-news-feeds packs, which clarifies its live-data behavior.

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

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

The description is dense but well organized, front-loading the core directive ('PREFER OVER WEB SEARCH') and then layering use cases, examples, and alternatives. Every section earns its place, though it could be slightly trimmed without losing meaning. The explicit 'START HERE' and 'Step up only when needed' framing make the structure easy to follow for an agent.

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

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

For a tool with no output schema, the description explains what the agent will receive: a structured answer with stable pipeworx:// citation URIs. It covers when to use it, when not to use it, alternatives, examples, tiers, and live-news coverage. Nothing an agent needs to invoke the tool correctly is missing, and the sibling differentiation 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?

The input schema covers 100% of parameters, including six documented aliases all mapping to 'question.' The description adds real value by providing domain examples ('current US unemployment rate', 'adverse events for ozempic', '5-day forecast for Tokyo') that show the breadth of acceptable input. With full schema coverage, the description does not need to define parameter formats, but its examples reinforce correct usage.

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

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

The description states a clear, specific function: routes natural-language questions to the appropriate one of 5,708 tools across 1,494 sources and returns structured answers with stable pipeworx:// citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as different modes, so an agent knows exactly what ask_pipeworx does and what it does not.

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 and actionable: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions — this is the default entry point.' It lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much') and gives concrete examples. It also states when to step up to alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers with verbatim evidence, and deep_research for broad/multi-part questions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it is experimental, may have candidate routing improvements enabled live, may differ from stable ask_pipeworx during tests, and currently matches ask_pipeworx exactly. This goes beyond annotations and avoids surprises.

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

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

The description is somewhat wordy but every sentence adds value: identification, current state, usage guidance, and reassurance that it is a full working router. The most important distinguishing information ('beta', 'candidate routing') is front-loaded. Minor redundancy exists around matching ask_pipeworx exactly, but overall it is structured effectively.

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 that is a beta variant of a sibling with identical behavior, the description covers the essentials: current state, behavioral differences (none right now), usage intent, and relationship to the stable router. It does not repeat return-value details because the response shape is stated to match ask_pipeworx. The explanation of experimental status and comparison purpose is sufficient for an agent to call 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%, with 'question' and its aliases already documented in the input schema. The description only refers to 'same arguments' without adding new semantic meaning or usage nuance for the parameters. Baseline 3 is appropriate since the schema carries the load.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,708 tools, arguments, and response shape. It distinguishes it from the stable sibling by emphasizing its experimental, candidate-routing nature. It could be more explicit about the underlying action ('answers questions' or 'routes queries'), but the title and router framing make the purpose reasonably clear.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes that no candidate is active right now so it currently matches ask_pipeworx exactly. This gives concrete guidance on when to choose the beta. It doesn't discuss when NOT to use it relative to ask_pipeworx_grounded, but it does address the most relevant alternative.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior, and the description adds substantial context beyond that: the exact success return shape, the refusal return shape with enumerated refusal_reason values, the constraint that answers come only from the tool result, and the extra LLM call cost. This fully discloses behavior without contradicting the annotations.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, success/refusal contract, use cases, and cost tradeoff. The most important distinction (grounded vs. ungrounded) is front-loaded, and the refusal reasons are compactly enumerated.

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

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

Despite having no output schema, the description fully documents the return value and refusal contract, so an agent knows exactly what to expect. It also covers routing, aliases in the schema, cost implications, and the comparison to siblings, making it complete for reliable invocation and interpretation.

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: every property is described as an alias for question, and the question property has a clear natural-language description. The tool description does not need to add parameter-level details, so the baseline of 3 is appropriate; there is no gap to compensate for.

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 is a hallucination-resistant answer mode that extracts the answer using only the tool result, explicitly differentiating it from ask_pipeworx. It also names the sibling ('Same routing as ask_pipeworx') and the key distinction: groundedness and refusal behavior. This is a specific verb–resource pairing with clear 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 gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples. It also tells the agent when NOT to use it: prefer ask_pipeworx for casual lookups, citing the extra LLM call cost. No inference is needed.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds extensive behavioral context: resolver contract (match_confidence, alternatives, suggestions), safety short-circuit for low-confidence matches, closed-market handling, wide-spread illiquidity warnings, and cancellation-rule parsing. This goes far beyond what annotations provide.

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

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

The description is long but well-structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Each section adds operational value, though some content (like exhaustive fan-out examples) could be trimmed without losing core guidance. It's information-dense and organized, making it usable despite 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?

For a tool with no output schema and complex behavior, the description is remarkably complete. It covers response shapes, error/status paths (low_confidence_match, market_closed_or_inactive), resolver warnings, parent-event extraction, news fallback fields, and resolution-rule risk. The agent is equipped to interpret results and handle edge cases safely.

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

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

Schema coverage is 100% for all 3 parameters. The description augments this with concrete fan-out examples (e.g., BTC bet → coingecko + fred + gdelt+gnews) and clarifies the market parameter's accepted formats (slug, URL, or question text) even though the schema already states this. The examples help agents anticipate data sources and response shapes.

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

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

The description opens with a clear, specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further details resolving, classifying, fanning out, and returning an evidence packet, distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

It explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. While it doesn't name alternatives or exclusion criteria, the context is clear enough that an agent knows when 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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: it names data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), specific metrics pulled, handling of off-calendar fiscal years, sorting by primary metric, and the return of citation URIs. This goes far 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?

The description is long but every sentence carries useful information: trigger phrases, core function, preference over alternatives, per-type behaviors, sorting, and output format. It is front-loaded and organized, but the density makes it slightly less scannable 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?

Despite lacking an output schema, the description clearly explains what the tool returns (paired data + citation URIs) and covers both entity types in depth. It handles complexity well—two modes, multiple metrics, fiscal-year nuances—making it complete for an agent to decide whether and how to invoke it.

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

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

The schema already documents both parameters with 100% coverage, providing the baseline of 3. The description adds meaningful value by specifying exactly what data each 'type' retrieves (e.g., 10-K revenue/net income/cash/long-term debt vs. FAERS adverse-event counts), and giving examples for the 'values' array. This helps the agent choose valid inputs beyond the schema's basic enum and array constraints.

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 trigger phrases and states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' which clearly identifies the verb (compare) and resource (entities). It also distinguishes itself from 'sequential single-pack lookups,' making it unmistakable what this tool does relative to siblings.

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 the explicit directive 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' and provides concrete query examples like 'X vs Y' and 'rank these companies.' This tells the agent exactly when to use this tool and what to avoid.

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 behavior beyond the annotations: account/plan gating, parallel routing to thousands of tools, return packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), gaps[] for unanswered facets, contradictions[], semantic excerpting, and expected latency. It also notes that citations are only included when actually resolvable. This goes far beyond the readOnly/openWorld/idempotent hints.

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

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

The description is long, but every sentence carries operational value: account gate, fallback routing, core definition, use cases, mode semantics, return structure, citation guarantees, and timing. It is front-loaded with the most important operational constraint and avoids 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?

With no output schema, the description needs to explain return values, and it does: findings packet, evidence/confidence/source/fetched_at, stable citations, gaps[], contradictions[], semantic excerpting, and latency. It also covers prerequisites, alternatives, and multi-hop behavior, so an agent has enough context to select, invoke, and interpret results.

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

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

Schema coverage is 100%, but the description genuinely enriches both parameters: question is explained as natural-language and broad/multi-part with examples, and depth is tied to paid plans, hop counts, gap recovery, and contradiction detection. The description makes the depth choices actionable, which the bare enum does not.

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 function: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources' in one call, and explicitly says it is 'NOT open-web search'. It also clearly distinguishes what deep_research is for versus ask_pipeworx, so an agent can differentiate it from siblings without opening schemas.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), explicit when-not-to-use guidance ('For a single lookup use ask_pipeworx'; 'For BREAKING ... prefer ask_pipeworx'), and a clear account prerequisite with fallback. It even names the alternative tool and explains why it would work better.

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 and idempotentHint, and the description adds important behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains output format and convenience, going beyond annotations. 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?

Four sentences, front-loaded with the core purpose, then usage guidance, then return behavior. The domain list is long but necessary for clarity. Every sentence earns its place; it is efficient without being terse.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (tool names, descriptions, full schemas with curated examples) and gives clear invocation strategy. It covers query examples, return details, and when to use, making it self-sufficient for the agent.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters, including aliases. The description mentions 'top-N' which relates to the limit parameter, but does not add significant semantic detail beyond what the schema provides. Baseline 3 is appropriate as 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: 'Find tools by describing the data or task.' It enumerates many domains (SEC filings, FDA drugs, etc.), making the resource scope concrete. As the only discovery tool among siblings, it distinguishes itself well, and the directive 'Call this FIRST' further clarifies its 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?

Provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It doesn't explicitly name alternatives or when-not-to-use, but the 'FIRST' heuristic implies a priority and the domain list gives practical trigger examples.

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

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

Beyond the read-only/idempotent annotations, the description discloses the parallel fan-out across sources, return structure (filings with URIs, fundamentals sorted by period_end), fallback logic (GDELT→GNews), and the patent API sunset soft-fail. This gives the agent a rich behavioral model.

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

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

Although long, every sentence carries essential information: usage examples, core value, source fan-out, return fields, fallbacks, and input constraints. It's structured for scanning and front-loaded with use cases. No wasted words.

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

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

For a multi-source tool with no output schema, the description fully explains return values (fields, URIs, sorting), source behavior, limitations, and error modes (patent soft-fail). Combined with strong annotations and complete schema, the agent has everything needed to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical examples ('AAPL', '0000320193'), clarifies 'zero-padded CIK', and reiterates the name limitation with a resolution path. This exceeds schema detail enough to warrant 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 states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from siblings by naming the alternatives (SEC/XBRL/news lookups) and explicitly states when to prefer this tool over them.

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

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

Explicit when-to-use guidance is provided: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also names an alternative for name inputs ('use resolve_entity first if you only have a name'), giving clear decision rules.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds context about the impact ('clear sensitive data') and the nature of the data ('previously stored memory'), which helps the agent assess consequences beyond the raw hint flags. This is a useful addition 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?

Two concise sentences: the first states the action, the second lists use cases and mentions complementary tools. No filler, front-loaded with the core verb, and every word 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 delete operation with one parameter and no output schema, the description covers the purpose, usage triggers, and relationship to sibling tools. Annotations cover safety traits. Nothing essential is missing for an agent to select and 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 schema covers the single parameter 'key' with a clear description 'Memory key to delete' (100% coverage). The description's phrase 'by key' simply echoes the schema, adding no new semantic detail. Baseline 3 is appropriate when the schema already documents the parameter fully.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes from sibling tools by explicitly mentioning 'previously stored memory' and pairing with remember/recall, which are clearly complementary memory operations.

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references sibling tools ('Pair with remember and recall'), giving context on how it fits into the workflow. This goes beyond vague hints to actionable conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds process details ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and output specifics ('single text blob ready to drop at site-root/llms.txt'). This is valuable beyond the safety hints, though it does not cover edge cases or rate limits.

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

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

The description is two sentences plus a compact 'Useful for' list. It front-loads the core action, then explains the process and output, and ends with use cases. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple read-only tool with two parameters and no output schema, the description covers input (URL), behavior (fetch/extract/emit), output format, and use cases. It is slightly light on potential failure modes or handling of dynamic content, but 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 description coverage is 100% and both parameters are well-documented in the schema. The description adds minimal parameter-specific detail beyond 'any URL', so the schema carries the parameter semantics burden. Baseline 3 is appropriate.

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

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

The description opens with 'Generate a production-ready llms.txt file for any URL', which is a specific verb and resource, and explicitly names the output format and target placement. It clearly distinguishes this tool from sibling tools like 'ai_visibility_check' by focusing on llms.txt generation.

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

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

The 'Useful for' section lists concrete scenarios: getting a client's site indexed, drafting for your own project, or auditing competitor visibility. This provides clear usage context, though it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds behavioral context by listing what data is returned (characteristics, temperament, origin, size, health data), which is useful and not redundant 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?

One clear, front-loaded sentence that communicates purpose and return fields without unnecessary detail. Every word 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?

The tool is simple with one parameter and an output schema. The description states the key returned categories, and with the output schema present, no further explanation of return structure is needed. The context is fully 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% for the single 'id' parameter. The description adds value by explaining the parameter's provenance ('obtained from list_breeds'), which aids correct usage beyond the schema's bare description.

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

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

The description clearly states 'Get detailed info about a dog breed by ID', identifying the specific action and resource. It distinguishes itself from the sibling 'list_breeds' by indicating this retrieves a single breed's details rather than a list.

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 context by specifying 'by ID' and the parameter schema adds 'obtained from list_breeds', which tells the agent the prerequisite step. However, it does not explicitly state alternatives or when not to use it, but the guidance is sufficient for a simple lookup.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return content (group names and descriptions) but this is likely already captured by the output schema. No additional behavioral traits like rate limits or auth needs are mentioned.

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, highly concise, and front-loaded with the core purpose. The example groups add clarity without unnecessary length. Every word 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?

The tool is simple—no parameters, an output schema exists, and annotations cover safety. The description is complete for the task: it states what the tool retrieves, gives examples, and mentions the returned fields. No additional context is needed.

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 tool has 0 parameters, and the baseline for 0 params is 4. The description does not need to explain parameter semantics. It adds context about the return value (group names and descriptions) which is helpful for understanding the tool's output.

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 specific action ('Get all AKC dog breed groups'), identifies the resource (AKC dog breed groups), and provides examples (Sporting, Herding, Terrier). It is distinct from sibling tools like get_breed and list_breeds by explicitly focusing on groups rather than breeds.

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 the tool is for retrieving breed groups and gives examples of what to expect. It does not explicitly mention alternatives or when not to use, but the context is clear enough to avoid confusion with related breed tools. No explicit exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by disclosing what the tool returns (breed names, IDs, weight ranges, life spans, hypoallergenic status) and that results are paginated. However, the use of the verb 'Search' is slightly misleading since the schema only includes a page parameter and no search query, which introduces minor ambiguity.

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 concise sentences: the first states the core action, the second lists return fields, and the third directs to an alternative tool. There is no redundant wording, and each sentence contributes essential information, making it well-structured and efficient.

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

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

With one parameter, a schema that covers it fully, and annotations that establish safety, the description covers the tool's purpose, output, pagination, and alternative. There is no missing critical context for the 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 input schema has 100% coverage: it fully documents the single 'page' parameter with description 'Page number for pagination (default: 1).' The description merely echoes 'with pagination' without adding additional semantic detail about the parameter's behavior, so it provides no value beyond the schema. Baseline 3 is appropriate given complete schema coverage.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Search dog breeds with pagination.' It also lists the returned data fields (breed names, IDs, weight ranges, life spans, hypoallergenic status) and explicitly distinguishes it from get_breed, making the purpose unambiguous.

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

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

The description provides explicit guidance by stating 'Use get_breed for detailed info on a specific breed,' which serves as an alternative tool for a different use case. This clearly indicates when to use list_breeds (browsing/searching multiple breeds) versus get_breed (deep dive on one breed).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and side-effect behavior. The description adds 'random' as a behavioral trait and mentions the content type, but does not disclose additional details like rate limits or pagination. This is acceptable given annotation coverage, so a baseline 3 applies.

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

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

Two concise, front-loaded sentences. The first sentence states the core action, and the second adds relevant detail about the content. No wasted words 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?

The tool is simple with one optional parameter, a complete schema, rich annotations, and an output schema. The description fully conveys what the tool does without needing to explain return formats, which are already covered by the 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%: the only parameter, limit, has a clear description including default and max values. The description adds no extra parameter information, but it doesn't need to since the schema fully documents it. 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 with a specific verb and resource: 'Get random dog facts.' It further specifies the content domains (behavior, history, abilities), which distinguishes it from sibling tools like list_breeds or get_breed. This is a clear, specific 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 implies usage context: use when you want random dog facts. No alternatives are mentioned because no sibling tool offers the same randomized fact-fetching capability, so exclusions are unnecessary. The clear context earns a 4.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds useful behavioral details: it returns specific fields, focuses on active subscriptions, and serves as a prerequisite for canceling. This complements the annotations rather than repeating them, though it doesn't disclose pagination or ordering.

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 what it does and what it returns, the second gives usage guidance. It is front-loaded and concise with no unnecessary words. Every sentence adds value.

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

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

For a simple one-parameter read-only tool without an output schema, the description covers purpose, return format, and usage context. The optional parameter is fully documented in the schema, and the return field list in the description fulfills the need for output expectations. No critical gaps remain.

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

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

The schema has 100% coverage for the only parameter (include_inactive) with its own description. The tool description doesn't add any additional meaning about this parameter, so the baseline of 3 is appropriate since the schema carries the semantics.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' It enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count) and positions the tool in the workflow of reviewing monitoring before adding or canceling, distinguishing it from siblings like subscribe/unsubscribe.

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

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

The description gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use it relative to subscribe/unsubscribe, though it doesn't name those sibling tools directly, so it's clear but not as explicit as naming alternatives.

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

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

Annotations provide the low-level readOnly/destructive hints, and the description adds substantial behavioral context on top: the claim_token mechanism for anonymous filing and later result retrieval, the 'pass it back later' usage pattern, the 5-per-identifier-per-day rate limit, and the note that it's free and doesn't count against quota. It also says the team reads digests daily, which sets expectations for response time. 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: purpose, use cases, exclusion rule, identification heuristic, content guidelines, token flow, roadmap impact, rate limit, and quota note. It is front-loaded with the core purpose and uses compact, scannable sentences. No redundant filler.

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

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

Given the tool has no output schema, the description sufficiently covers return behavior: filing returns a claim_token, and passing that token later returns status and what changed. It also covers edge cases (anonymous filing, different-server exclusions) and operational constraints (rate limits, quota). For a feedback-submission tool with well-documented parameters, 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?

Even though schema coverage is 100%, the description enriches parameter meaning substantially. It maps 'bug' to wrong/stale data, explains that claim_token should be passed 'with no other arguments' to read a previous report, and tells users to describe issues in terms of Pipeworx tools/packs, which directly informs the context and message fields. This goes beyond the schema's bare field descriptions.

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

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

The description opens with a specific verb phrase: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying both the action and target. It also enumerates the exact feedback categories (bug, feature/data_gap, praise), which cleanly distinguishes this tool from sibling Q&A or research tools like ask_pipeworx and 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?

This is exemplary: it says exactly when to use the tool ('when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well') and explicitly states when NOT to use it ('if the tool came from a different MCP server... file it with that server instead'). It also provides practical guidance about not pasting end-user prompts and how to identify Pipeworx 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, idempotentHint, and destructiveHint false. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, just (pack, tool, count), and caching in the 5min-1h range. This goes beyond the annotations and helps the agent understand data freshness and privacy implications.

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

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

The description is well-structured and front-loaded. It starts with the core purpose, then describes the output, enumerates use cases, and finishes with data source/caching details. Every sentence contributes actionable information without redundancy.

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

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

For a simple read-only tool with one optional parameter, the description fully covers behavior: what it returns (top tools/packs, volume), the aggregation nature, privacy (no PII), caching, and parameter semantics. No output schema exists, but the description explicitly states the data shape (pack, tool, count), making it sufficiently complete.

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

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

Schema coverage is 100% with a simple enum parameter. The description adds interpretive guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the bare enum with practical meaning, so it earns above the baseline 3.

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

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

The description opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This identifies the resource (Pipeworx call trends) and the specific action (returns top tools/packs/volume), distinguishing it from siblings like discover_tools or ask_pipeworx.

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

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

The description provides three explicit 'Useful for' scenarios (discovering hot data sources, confirming canonical tools, aligning use cases) and explains that shorter windows surface hot trends while longer windows show steady-state demand. It gives clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description goes far beyond that, disclosing specific behavioral details: the ~200 market scan limit, the Jaccard similarity threshold (≥0.30), placeholder filtering rules and the >20% null condition, the fill-check pricing against live CLOB depth, and the meaning of realizable_edge_pp ≤ 0. These details are not in the annotations or schema and provide crucial execution-time context.

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

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

Though the description is long, it is broken into clearly labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every sentence conveys a distinct, non-redundant fact. The opening sentence is dense and informative, and the structure mirrors the tool's execution pipeline. This is an appropriate length for a tool with two distinct modes plus a fill-check subbehavior.

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 the absence of an output schema, the description fully specifies the response shape: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge cases like low similarity and placeholder-heavy partitions. Combined with strong annotations and schema, this description is complete enough for an agent to select and invoke the tool correctly without additional context.

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

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

Schema coverage is 100%, with both parameters already described in the schema. The description adds substantial semantic depth beyond the schema: it explains what 'event' slugs look like with concrete examples ('fed-decision-may-2026'), what 'topic' queries should be, and how each parameter alters the scan behavior. It also introduces derived concepts like 'semantic anchor' and 'partition filter' that give operational meaning to the parameters.

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 first sentence clearly states the tool's core function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names both the specific resource (Polymarket) and the method, distinguishing it from siblings like polymarket_edges and polymarket_fill_risk. The description also breaks down the two main modes (event and topic), leaving no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'pass topic for a themed cross-event scan'. It also clarifies when to avoid this tool, instructing users to use 'polymarket_fill_risk' for custom sizing and warning 'do not trade it' when realizable_edge_pp ≤ 0. This is excellent differentiation 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 read-only/idempotent, and the description adds extensive behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, _diagnostics), filter logic (placeholder-slug filter, loyalty to 24h-move warnings), and the reason Fed bets are excluded. No contradiction with annotations exists.

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

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

The description is long but well-structured with uppercase section headers and information-dense sentences that serve a purpose. It front-loads the core purpose, then groups models, knobs, and response details. Slightly verbose compared to ideal conciseness, but the density is justified by the tool's complexity.

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

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

Despite having no output schema, the description fully documents the response structure (by_segment, fed_candidates, _diagnostics) and explains the filters and gates that affect results. It even explains why segments may be empty, giving agents the diagnostic context needed to interpret unexpected results. This is highly 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% with each parameter described, but the description adds cross-parameter semantics not present in the schema, such as the relationship between min_kelly and min_partition_leg_kelly (the latter applies to per-leg Kelly, not parent-level) and the recommendation to bump slippage for thin books. This goes beyond the baseline expected when schema descriptions are thorough.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately distinguishes itself as a discovery tool for 'what should I bet on today' and outlines the three output segments, clearly differentiating from sibling tools like arb scanners or trackers.

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 explains the intended use case ('agents discover opportunities without paging hundreds of markets') and provides detailed knob guidance for filtering tradeable edges. It does not explicitly name alternative tools to use instead, but the inclusion of structural arbitrage alongside model-driven and longshot signals implies a broad coverage that other sibling tools do not offer.

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 a safe, read-only, idempotent operation. The description goes well beyond this by detailing the response structure (tracked[], expired[], snapshot_dates[]), explaining edge_pp_net sign convention, describing gaps in snapshot dates due to cache-miss behavior, and disclosing limitations such as the 60-day TTL and daily-close basis. This provides comprehensive behavioral context without contradicting 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 every sentence carries essential information. It is logically structured: opening purpose, argument details, response format, and limitations. There is no filler or redundancy; the detailed format is justified by the tool's complexity.

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

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

For a read-only telemetry tool with two optional parameters and no output schema, the description fully compensates by explaining the response in detail, including the meaning of each field, trends, and edge cases like missing snapshot dates. Limits and data provenance are also covered, making the tool's behavior predictable.

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

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

The input schema already describes both parameters (days and window) with format and defaults, achieving 100% coverage. The description adds a marginal 'snapshot family' context for window and restates defaults, but does not significantly enrich parameter meaning beyond the schema. Therefore, 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 identifies the tool as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, with a specific question it answers: 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (which likely provides current edge data) by focusing on time-series analysis and trend classification.

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 when to use the tool—for analyzing the persistence and decay of edges over time—by contrasting fresh vs. old wide edges. It does not explicitly name alternative tools or state 'use polymarket_edges for current edges', but the context and reference to snapshots make the intended usage clear. The response format further clarifies what the tool provides, reinforcing its specific use case.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description adds rich behavioral context: it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and highlights risks like thin_legs[] and forced_directional_risk. This goes well beyond the annotations and fully discloses the tool's behavior.

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

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

The description is a dense, information-rich block. It front-loads the core purpose, then details modes, parameters, return values, and usage context. Every sentence earns its place, though the lack of paragraph breaks makes it a bit heavy. Slightly bulky but not wasteful.

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 must explain return values, which it does comprehensively: per-mode outputs, verdict values, capture_ratio, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also covers parameter semantics and use cases, making it fully self-contained for a complex two-mode tool.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds significant meaning beyond the schema by explaining mode-specific interpretations: market vs event, side defaults (including 'default auto' in basket mode), and size_usd semantics ('max spend on buys, target proceeds on sells' vs 'settlement notional... shares per leg'). This is more than marginal compensation.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) that this tool complements, making it unmistakable what this tool does and how it differs.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why—partial fills convert arb into unhedged directional risk—which gives the agent a clear decision rule for when to invoke this tool.

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

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

The description goes far beyond the readOnly/idempotent/non-destructive annotations: it discloses compatibility_codes, when pairs are skipped, that unknown legs are NEVER paired, how top_spreads_pp carries flags, and the meaning of skipped_cross_type/subtype counters. This gives an agent a precise model of the tool's behavior and output without 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 long but tightly organized: purpose first, then modes, response shape, safety fields, code meanings, pairing rules, counters, and a final caveat. Each sentence carries distinct operational information and the most critical warnings are front-loaded in the SAFETY FIELDS section.

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

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

For a tool with no output schema and three optional parameters, this description is remarkably complete: it covers both invocation modes, response contents, safety fields and their codes, skipped-pair behavior, temporal alignment, and the reliability caveat. An agent has enough context to call it correctly and interpret the result without additional discovery.

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

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

The schema already describes each parameter, but the description adds important interaction semantics: topic selects a pre-mapped pair, while kalshi_event_ticker and polymarket_event_slug override the mapped side for custom pairings. It also enumerates the 10 topic values, reinforcing and extending the schema's coverage.

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

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

The opening sentence defines a specific resource and action: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from Polymarket-only siblings by naming both venues and the same-question constraint, so an agent can tell it apart from polymarket_arbitrage or polymarket_edges.

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 explains the two modes (topic shortcuts vs explicit ticker+slug), when to use each, and warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return compatibility_warning today. It does not explicitly name sibling tools as alternatives or state when not to use this tool, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar for additional behavioral disclosure is lower. The description adds valuable context beyond these: omitting the key lists all saved keys, and data is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID). This enriches understanding of the tool's runtime behavior.

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

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

The description is three sentences, each with a distinct purpose: core action, use-case context, and scoping/related tools. It is front-loaded with the primary function and contains no redundant or filler words.

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

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

Given the tool's simplicity (one optional parameter) and strong annotation coverage, the description is complete. It covers the main functionality, common use cases, scoping behavior, and related tools, so the agent has all necessary context for effective invocation.

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

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

Schema description coverage is 100% for the single key parameter, establishing a baseline of 3. The description adds meaning by explaining the semantic distinction of omitting the key (list all keys) and providing example key types (ticker, address, research notes), which helps the agent understand what kinds of values are retrievable.

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 'Retrieve a value previously saved via remember, or list all saved keys' – a specific verb and resource that clearly states the tool's function. It distinguishes itself from sibling tools by explicitly mentioning remember and forget, making its role unambiguous within the toolset.

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

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

The description provides explicit guidance on when to use the tool: 'Use to look up context the agent stored earlier' with concrete examples like the user's target ticker, address, and research notes. It also names alternatives: 'Pair with remember to save, forget to delete,' which clarifies the relationship with sibling tools.

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

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

Description states that setting mark_read:true flags returned events as read so the next call shows only newer ones, which is a state-mutating side effect. This directly contradicts the readOnlyHint:true annotation. The description also adds other useful context, but the contradiction forces a score of 1 per 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 about four sentences, front-loaded with the core action. Each sentence carries useful information: return fields, filtering options, mutation flag, polling, and an alternative endpoint. It is dense but not bloated, and the structure flows logically from purpose to details to alternatives.

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 shape (source, citation_uri, raw payload). It also covers all five parameters, side effects, polling behavior, and an external access route. Minor deduction for the contradiction with readOnlyHint, which introduces ambiguity about whether the tool is always side-effect free.

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, so baseline is 3. The description adds value by giving a concrete type example ('sec_8k'), explaining that since is an ISO timestamp, and clarifying mark_read semantics (flagging events read so the next call only shows newer ones). These go beyond the schema's minimal 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 opens with the specific verb 'Pull fired events from your subscription feed' and names the resource (alerts feed). It clearly distinguishes itself from sibling tools like list_subscriptions by focusing on fired events and alert payloads, not subscription management. The return fields and filtering options further reinforce its 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?

Provides clear usage context: filter by type and/or since, mark_read behavior, polling is fine, and an alternative HTTP endpoint for scripts/dashboards. It does not explicitly name a when-not-to-use case or sibling alternative, but the guidance is sufficient for an agent to decide when to use this tool.

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

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

Annotations already set readOnlyHint=true and idempotentHint=true, but the description adds crucial behavioral depth: multi-source fan-out with fallback logic, USPTO soft-fail due to PatentsView API sunset, and response structure. These go well beyond the annotations, painting a full picture of side effects (or lack thereof) and failure modes.

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 carries information: user-question framing, source-specific behavior, parameter syntax, and a direct pointer to the alternative tool. It is front-loaded and structured like a well-organized specification, not wasted words.

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

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

Despite no output schema, the description clearly states return values (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It covers source behavior, fallback, rate limits, and parameter flexibility. For a tool with this complexity, the description is unusually complete.

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

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

Schema coverage is 100%, but the description adds substantial meaning: `since` accepts ISO date or relative shorthand (with examples), `value` can be ticker or CIK, and it even advises '30d' or '1m' for typical monitoring. This is more than the schema provides.

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 change feed for a company over a time window, using specific verbs like 'change feed' and 'Fans out to SEC EDGAR, GDELT→GNews fallback, USPTO'. It is explicitly distinguished from the sibling entity_profile via the closing sentence, so an agent can tell what this tool uniquely does.

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

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

Provides explicit usage context: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains the parallel fan-out, fallback behavior (GDELT preferred, GNews when rate-limited or 5xx), and `since` formats, giving clear when-to-use guidance versus alternatives.

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

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

The description discloses key behavioral traits beyond annotations: scoped by identifier, persistent for authenticated users vs 24-hour retention for anonymous sessions. It also clarifies the key-value storage model. While it doesn't explicitly mention overwriting on duplicate keys, the added context about persistence and scope is valuable.

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, front-loading the core purpose in the first sentence. Every sentence earns its place: purpose, usage trigger, and storage details/pairings. No redundancy or filler.

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

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

For a simple two-parameter tool with no output schema, the description covers everything needed: what to store, when to use it, persistence behavior, and companion tools. It is fully self-contained and leaves no major gaps.

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

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

The schema already describes both parameters (key and value) with examples, giving 100% coverage. The description reinforces this by providing realistic examples of keys and values (e.g., 'subject_property', 'target_ticker') and framing them as key-value pairs. This adds practical meaning beyond the schema.

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

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

The description clearly states the tool's function: saving data for later reuse across conversations or sessions. It specifies the resource (data) and the verb (save), and distinguishes from siblings like recall and forget by mentioning these counterparts. Examples of use cases (ticker, address, preference) further clarify the 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 explicitly states when to use the tool ('Use when you discover something worth carrying forward') and provides concrete examples. It also mentions pairing with recall and forget, which implicitly contrasts with alternative tools. This gives clear guidance on appropriate usage.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail: identifiers are labelled with their source, unresolved identifiers are explicitly listed under 'unresolved', LEI/FIGI enrichment degrades gracefully (fallback to EDGAR), and internal cascading replaces multiple manual lookups. No contradictions with annotations.

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

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

The description is front-loaded with relatable query examples and a clear directive. It is longer than average but every sentence adds necessary detail about supported types, input variations, and fallback behavior. Slight verbosity in the nested explanations could be compressed, but overall the structure helps comprehension without being wasteful.

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 two parameters and no output schema, the description sufficiently describes what the tool returns (canonical identifiers with source labels, unresolved list, RxCUI for drugs) and handles edge cases (ISIN resolution, graceful degradation). For its complexity, it is complete and leaves little ambiguity about operation.

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 adds value by clarifying that 'value' accepts ticker, CIK, ISIN, or company name for 'company', and brand/generic name for 'drug'. It also explains that an ISIN resolves to the legal entity via GLEIF, providing context beyond the schema's basic listing.

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

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

The description explicitly states the tool resolves names to canonical/official identifiers for other tools. It starts with concrete query examples like 'What's the ticker for…' and 'find the CIK for…', then defines the verb 'resolve' and the resource (entity). It distinguishes from siblings by specifying it is for name-to-ID lookup, contrasting with tools like compare_entities or entity_profile.

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

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

The description gives clear guidance: 'Use FIRST whenever you have a name but need an ID.' It provides a list of example queries that trigger this tool and explains the supported types (company, drug) with specific input expectations. Although it does not explicitly list when not to use, the positive direction is strong and leaves no ambiguity about its primary purpose.

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 safety. The description adds valuable behavioral detail: it probes each entity via ai_visibility_check, ranks by score, and returns per-entity score, confidence, and signal density—information not available in annotations.

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

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

The description is efficiently structured: first sentence states the primary purpose, second explains method and output, third gives a use case, and fourth lists return fields. Every sentence earns its place without redundancy.

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

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

For a tool with 4 parameters, 1 required, and no output schema, the description is sufficiently complete. It covers purpose, method, output format, and use case. The absence of rate-limit or auth details is mitigated by annotations indicating read-only, idempotent behavior.

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

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

Schema coverage is 100%, with each parameter having a thorough description. The tool description adds little semantic value beyond reinforcing that entities are compared (e.g., 'your brand + N competitors'), which is already in the schema. Baseline 3 applies.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' The verb 'Compare' and resource 'AI visibility' are specific, and it distinguishes itself from the sibling ai_visibility_check by emphasizing multi-entity comparison and ranking.

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 an explicit use case ('competitive AI-marketing audits') and an example query, giving clear context. However, it does not explicitly state when not to use this tool or mention alternatives like ai_visibility_check for single-entity checks, though it implies this by describing probing each entity individually.

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 behavioral traits beyond annotations: the fan-out across two external services, the summary/return block structure, per-advisory detail, links, alternative versions, and graceful degradation with 5-30s timeout on first bundlephobia measurement. This adds significant context on top of the readOnly/idempotent hints.

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

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

The description is dense but well-organized: it opens with the composite purpose, then gives trigger use cases, return content, ecosystem scope, and failure behavior. Each sentence carries relevant information, though the first sentence is long and could be split for readability.

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 external services, multiple data points) and the absence of an output schema, the description compensates fully by enumerating exactly what fields are returned, noting alternative versions, and covering partial failure behavior. The ecosystem limit and timing caveats make the tool predictable to invoke.

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

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

Schema coverage is 100% for both parameters, so the description does not need to add syntax. It reinforces that scoped packages are accepted and that version defaults to latest, but these are already in the schema. The description adds contextual use-case info but no new parameter-level semantics, warranting the baseline 3.

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

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

The description names a specific composite check ('should I add this npm package to my project') and specifies the sources (deps.dev, bundlephobia) and data types (license, advisories, bundle size, dependencies, tree-shaking). It clearly distinguishes itself from sibling tools by its npm-only scope and composite nature.

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 the tool ('Use whenever an agent asks...') and gives concrete example queries. It also provides an important exclusion ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), which steers agents 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?

Beyond the readOnly/idempotent annotations, the description discloses the embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), output includes character offsets and scores, and the 200K-char cap with truncation flagging—rich behavioral context.

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

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

The description is front-loaded with the core purpose, and each subsequent sentence adds value (usage guidance, pairing, technical details). It is slightly verbose at five sentences but contains no filler; a 4 is earned for efficient but thorough structure.

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

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

With no output schema, the description clearly states the return shape (top-N passages with character offsets and similarity scores), the truncation behavior, and the companion tool. Together with strong schema and annotations, this makes 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% and each parameter already has explicit descriptions (e.g., query examples, limit range, text cap). The description adds little beyond the schema; it mentions the cap and top-N concept, but these are already present in parameter docs. Baseline 3 applies.

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

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

The description opens with 'Semantic search INSIDE a fetched record', clearly naming the verb, resource, and scope. It differentiates from siblings by explicitly contrasting with ask_pipeworx_grounded and stating it operates on already-fetched text, not the whole document.

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

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

The description gives explicit when-to-use: 'Use when the record is too big to cram into the prompt'. It also names the paired tool ask_pipeworx_grounded and describes the fetch-then-ground workflow, effectively telling the agent when to prefer this over alternatives.

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

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

Rich behavioral detail beyond annotations: describes feed always-on behavior, SMS verification requirements, email templating, webhook HMAC signing secret returned once, and auto-disable after 10 consecutive failing runs. This goes far beyond the basic readOnly/idempotent hints and provides actionable operational knowledge.

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

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

The description is long but well-organized, leading with the core action then layering in type and delivery details. Every sentence contributes information, though the single-paragraph format could benefit from shorter subsections for scanability. Minor verbosity is justified given 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 subscription-creation tool with nested objects and no output schema, the description covers return values, all subscription types, parameter shapes, delivery channels, prerequisites, and failure behaviors. It is self-sufficient and leaves no critical operational gap for an agent to proceed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical examples for each subscription type (e.g., items:['5.02'] for officer change) and delivery channel specifics (e.g., localhost/private hosts rejected for webhooks). This enhances the parameter schema's semantics without overstuffing.

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: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value ('Returns the new subscription id'). It names concrete subscription types and delivery channels, making it distinct from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context on when to use the tool, including prerequisites ('Requires a Pipeworx OAuth account') and exclusions ('anonymous + BYO cannot persist subscriptions'). It also gives guidance on alternative feed retrieval (via recent_alerts) and specific constraints like SMS verification and 10/day cap. However, it doesn't explicitly contrast with sibling tools like unsubscribe or list_subscriptions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns category-bucketed example questions from the live catalog, supports an optional topic focus, and requires no arguments for the full spread. It could mention response format, but the description is still transparent.

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

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

The description is efficient and well-structured, starting with example user queries, then explaining the return value, usage, and focus options. It is a bit long, but every part serves a purpose in orienting a new agent. It earns its length with concrete examples and specific guidance.

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

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

Given the simple schema (one optional param) and annotations covering safety, the description is complete: it states what is returned (category-bucketed example questions), lists the categories, describes the optional parameter, and gives clear when-to-use guidance. No output schema exists, but the description adequately conveys the return type by describing the content.

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 the parameter 'topic' is well-defined with a list of possible values. The tool description reinforces this with examples like 'finance', 'pharma', 'betting' and explains that omitting it provides a cross-category spread, but it doesn't add meaning beyond what the schema already provides.

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

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

The description clearly states that this tool returns category-bucketed example questions with exact tool and argument shapes, serving as the onboarding entry point. It distinguishes itself by emphasizing 'get ideas / show me examples' and 'learn how to call the meta-tools', which is different from sibling tools like discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. Also provides usage alternatives (call with no arguments vs. passing a topic) and specifies categories for the topic parameter.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds critical behavior: ownership enforcement and soft-delete semantics with historical events preserved. This directly informs the agent of side effects and access restrictions, aligning with and enriching 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?

Two sentences, action-first, and every sentence adds value: the first states the core action and parameter, the second explains ownership and non-destructive behavior. 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, single-parameter mutation tool, the description covers the essential behavioral aspects: what is canceled, who can do it, and the effect on historical data. Annotations fill in the write/idempotent/non-destructive profile, and no output schema exists, so no return-value explanation is needed.

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 fully documents the single parameter with 100% coverage and a clear description ('Subscription id (uuid) returned by subscribe'). The description merely restates 'by id' without adding further semantic detail, so the baseline of 3 applies.

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

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

The description uses a specific verb-resource pair ('Cancel a subscription by id') and clearly differentiates from sibling tools like subscribe and list_subscriptions. It also clarifies the object as a subscription to alerts, aligning with the title.

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) and adds important constraints (ownership enforced). It does not explicitly name alternatives or when-not scenarios, but the context is sufficiently clear given sibling tool names.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial context: the structured XBRL fast path vs grounded fallback, the full verdict set, the meaning of 'could_not_verify' (not evidence, carries verification_error), and the distinction from 'unsupported'. It also notes that evidence includes verbatim source with citation, all beyond what annotations state.

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 phrasings and a clear one-sentence definition. Each subsequent sentence earns its place: routing logic, verdict list, the critical could_not_verify caveat, and the efficiency benefit over sequential calls. It is dense but well-organized, with 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?

Even without an output schema, the description explains return values (verdict enum, actual value with citation, reasoning) and error semantics (could_not_verify vs unsupported). It also conveys the tool's scope and limitations (authoritative sources, coverage for unsupported claims), making it fully self-contained for 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?

Schema coverage is 100%, but the description adds tactical semantics for tolerance_pct: it overrides the implied wording tolerance, is capped at 5 by default, and the agent is advised to set 1–2 for hallucination detection. The claim parameter is also exemplified with realistic inputs, enriching the schema's short description.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with a specific verb ('verify') and resource ('claim'). It distinguishes itself from siblings by positioning as a single composite call that replaces sequential NL parsing, entity resolution, data lookup, and comparison, and by giving illustrative user phrasings ('fact check', 'confirm or refute').

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', giving clear when-to-use context. It also explains the structured vs grounded pipeline routing based on claim type, but does not explicitly list exclusions or name alternative tools to prefer in other cases, so it lacks the 'when-not' part for a 5.

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