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 show readOnly, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavior: it routes to internal tools, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. This gives the agent useful expectations 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 front-loaded with the key directive 'PREFER OVER WEB SEARCH' and followed by a concrete list of domains and examples. While long, most sentences earn their place by expanding when and how to use the tool. The trailing breaking-news sentence feels slightly appended rather than integrated, keeping it from a 5.

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

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

For a simple single-required-parameter tool with no output schema, the description is unusually complete: it explains the tool's role, gives inclusion criteria, provides examples, notes that it beats web search for this class of question, and describes the citation-bearing return format. An agent has enough information to decide when to invoke ask_pipeworx and what to pass.

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%: every parameter is documented as an alias for question, and the question parameter description is clear. The tool description provides context about what kinds of questions to ask but does not add parameter-level meaning beyond the schema. Baseline 3 is appropriate because the schema already 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 a specific role: ask_pipeworx routes questions to one of 5,798 tools and returns structured answers with stable citation URIs. It also distinguishes from an implicit alternative, web search, by prefacing 'PREFER OVER WEB SEARCH'. However, it does not distinguish this tool from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, so it misses the sibling-differentiation part of a 5.

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

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

Gives explicit when-to-use guidance: 'Use whenever the user asks "what is", "look up", "find", "get the latest"...' and includes concrete examples like unemployment rate and Apple's 10-K. It also states it should be preferred even when web search could answer. It does not discuss when not to use it or name specific sibling tools as alternatives, so it stops short of a 5.

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

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

Beyond the readOnly, idempotent, openWorld, and non-destructive annotations, the description discloses important behavioral details: candidate routing improvements may be live, none are currently active, the tool currently matches ask_pipeworx exactly, and it has no fallback because it is a full working router. This gives the agent a realistic model of experimental variability.

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 reasonably concise and front-loaded with the essential identity ('Beta version of ask_pipeworx'). It covers state, usage, and fallback behavior compactly. Minor redundancy exists ('same arguments' appears twice, and 'currently matches' is restated), but it remains efficient and scannable.

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 explicitly a beta duplicate of ask_pipeworx, the description provides the key facts: identical tool set, identical argument and response shape, experimental edge, current no-op candidate state, and comparison against the stable router. It relies on the sibling ask_pipeworx for the exact response shape, but that is acceptable given the explicit equivalence and no output schema.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters and their aliases. The description adds only that arguments are identical to ask_pipeworx and does not provide additional meaning beyond the schema. Baseline 3 is appropriate because the schema carries the semantic 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 ask_pipeworx_beta as a beta version of ask_pipeworx: a universal router with the same 5,798 tools, arguments, and response shape. It explicitly contrasts it with the stable ask_pipeworx and notes its experimental routing improvements, making its role and distinction from siblings 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 gives explicit guidance: use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It also clarifies the current state ('No candidate is active right now') and that it is a full working router. It names the stable alternative but does not fully enumerate exclusions or cases where another sibling should be chosen.

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

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

The description richly discloses behavior beyond the annotations: it explains the internal routing, that the answer is extracted only from tool results, the exact success return shape, and the full refusal_reason enumeration. It also discloses the extra LLM call cost. No contradiction with the readOnly/openWorld/idempotent 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: core purpose, routing behavior, success/refusal formats, usage guidance, and cost trade-off. It is front-loaded with the most important differentiator and structured so an agent can quickly extract decisions.

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 contract, including evidence, confidence, source, fetched_at, and all refusal reasons. It also addresses operational context (extra LLM call) and routing context, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already explains the natural-language 'question' parameter and its aliases. The tool description adds no parameter-specific meaning beyond restating that arguments are filled during routing, so the baseline of 3 is appropriate.

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

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

The description opens with a specific, meaningful distinction: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly names the resource (ask_pipeworx), the mechanism (extracts the answer using ONLY what the tool result contains), and differentiates this grounded variant from the sibling ask_pipeworx.

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

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

Explicit when-to-use guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples like financial verdicts and legal claims. It also names the alternative ask_pipeworx and explains when to prefer it: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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

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

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?

Beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true), the description adds significant behavioral context: it never invents answers, returns explicit gaps[], includes confidence/source/fetched_at/citation per finding, performs semantic excerpting rather than head-truncation, and discloses latency (15-60s, up to ~90s for thorough). It also reveals contradictions[] behavior for standard/thorough. This is strong disclosure beyond what annotations provide.

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

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

The description is dense and information-rich, front-loading the critical account requirement. However, it's quite long and contains some redundant phrasing that could be tightened. The parenthetical parenthetical 'as ai_visibility_check' at the end is garbled, indicating some editing issues. It earns its length mostly, but could be more structured.

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

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

For a tool with no output schema, the description does an excellent job explaining what the findings packet contains: verbatim evidence, confidence, source, fetched_at, stable citation URI, gaps[] and contradictions[]. It also covers important operational details like latency, account requirements, and how large records are handled. An agent has enough to decide when to invoke it and what to expect back.

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

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

The schema already covers both parameters at 100%, but the description enriches the depth parameter by explaining the behavioral difference between quick/standard/thorough (single hop, gap-recovery, contradictions scan, paid tier). The question parameter is adequately described in the schema, and the description adds context about broad/multi-part questions being 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 purpose: grounded multi-source research across 1517 structured data sources in one call, decomposing questions into facets and routing them in parallel. It explicitly distinguishes itself from open-web search and names the specific alternative (ask_pipeworx) for users not signed in.

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 and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead'. It also mentions the account requirement and tier restrictions ('thorough' needs paid plan), which helps an agent route appropriately.

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

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

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

Annotations already mark this as read-only, open-world, and idempotent, and the description adds substantial non-obvious behavior: parallel fan-out across many sources, expected-empty sections for FDA products for non-biologic companies, USPTO sunset soft-failure, sources_used/sources_failed semantics, and resolved:false with notes for private companies. This is exactly the kind of behavioral context annotations do not provide.

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

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

The description is long, but the tool is genuinely complex with many sources and edge cases, and nearly every clause carries useful operational guidance. It front-loads the purpose and preferred usage before diving into return sections. Slightly better formatting (bullets) would improve scannability, but it is not padded with fluff.

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

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

Despite no output schema, the description enumerates the main return sections, explains what empty sections mean, covers accepted input shapes, and handles failure/edge cases like private companies, USPTO sunset, and FDA-licensed biologics. An agent has enough context to invoke the tool correctly and interpret its results in diverse scenarios.

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

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

The schema already fully documents both parameters, so the baseline is 3. The description adds meaningful extras: accepted examples for ticker/CIK/name, zero-padding for CIKs, name resolution via SEC EDGAR, and confirmation that type='company' and type='ticker' behave identically. This goes beyond the schema without being redundant.

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

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

The description states a precise purpose: producing a full cross-source profile of a US public company in one call. It includes concrete user phrasings ('Tell me about X', 'brief me on Tesla') and explicitly differentiates itself from chaining single-pack SEC/XBRL/news lookups. This makes the tool's role unambiguous even among siblings like compare_entities and resolve_entity.

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 prefer this tool over chaining individual lookups when the user wants a holistic company view, which is strong when-to-use guidance. It does not enumerate when to choose siblings like deep_research or compare_entities instead, so there is a small gap in exclusion guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, 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?

Despite readOnlyHint and idempotentHint already signaling safety, the description adds rich behavioral disclosure: compatibility codes, null temporal_alignment semantics, unknown legs never being paired, skipped comparison counters, and the gross-vs-net fee caveat. None of this contradicts 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 information-dense, and it front-loads the core purpose before safety fields and output semantics. Some redundancy appears in repeated temporal-alignment and either-mode caveats, but each section earns its place given the absence of an output schema.

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

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

For a read-only comparison tool with no output schema and complex safety semantics, the description is unusually complete: it explains response fields, compatibility codes, per-spread flags, skipped legs, low-confidence pairs, and fee treatment. An agent has enough detail to invoke either mode and interpret results reliably.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real value by explaining mode interactions, the full topic shortcut list, and the override precedence between topic and explicit parameters. The schema already documents parameter strings, so this is strong but not maximal.

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

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

The description opens with a specific verb-resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool from sibling Polymarket tools by naming both venues, and it defines the two operational modes.

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

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

It provides clear when-to-use context by describing topic shortcuts versus explicit ticker/slug pairing, and it warns that pre-mapped topics often return compatibility warnings. It does not explicitly name sibling alternatives, but the usage conditions and cautions are strong enough to guide selection.

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

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

Annotations already 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 signal read-only, non-destructive, idempotent behavior. The description goes well beyond this by disclosing important behavioral traits: ambiguity handling via figi_candidates, explicit unresolved identifiers, graceful degradation when GLEIF/OpenFIGI are unavailable, and the ISIN-to-legal-entity mapping. 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 and dense, with many parentheticals and asides, but nearly every clause adds operational value. It is front-loaded with examples and the core usage rule, and the verbose type-specific sections are justified by the tool's multi-source behavior.

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 carries the burden of explaining return contents, and it does: CIK/ticker/company_name, LEI and ownership, FIGI, RxCUI/ingredient/brand, plus failure behaviors like unresolved and figi_candidates. It also covers input edge cases and external-source degradation, making the tool safe and predictable for an agent 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%, so the baseline is 3, but the description adds substantial meaning beyond the schema: concrete examples (AAPL, CH0038863350, ozempic), the accepted input forms for company, and a critical caveat about passing the entity name only rather than the full noun phrase. This materially improves correct invocation.

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

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

The description clearly states a specific verb and resource: it resolves user-spoken names to canonical/official identifiers that other tools consume. It enumerates supported types (company, drug) and distinguishes itself from siblings by emphasizing it is the first stop when you have a name but need an ID.

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

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

The description gives explicit context for when to use it ('Use FIRST whenever you have a name but need an ID') and provides numerous query examples. However, it does not explicitly name alternative sibling tools or state when NOT to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing 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.