crypto

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

Annotations already cover read-only, open-world, and idempotent behaviors. The description adds valuable context: it discloses that probing Anthropic requires a BYO key with direct cost to the user, and it reveals the return structure (per-model fields + combined view). It stops short of discussing potential failures or rate limits, but given the annotation coverage, this is solid.

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 deliver purpose, default behavior, cost model, return format, and use cases—zero wasted words. The main action is front-loaded, and every sentence carries information.

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

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

With no output schema, the description compensates by listing the exact return fields. It covers the default model, optional Anthropic probing, and practical use cases. While it doesn't explicitly mention the `context` parameter or error conditions, the schema covers those, and the overall picture is sufficient for an agent to select and invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the free default (Workers AI Llama) and the cost implication of `_apiKey` ('you pay Anthropic directly'), which helps agents decide whether to pass that parameter. It also ties the `entity` parameter to a broad concept ('business / brand / product / topic').

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 ('Probe') and a resource ('one or more LLMs') plus the core output ('score visibility (0-100) per model'). It clearly differentiates from sibling tools by focusing on LLM knowledge visibility for brands/topics, not asking questions or scanning competitors, and names concrete use cases.

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

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

The description gives clear contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also notes the default model and the option to add Anthropic via `_apiKey`. However, it does not explicitly state when not to use this tool or mention alternatives among siblings (e.g., scan_competitor_ai_presence), so it misses the 'when-not/alternatives' level.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond annotations: it mentions that the tool routes to thousands of tools, returns structured answers with pipeworx:// citation URIs, works on every tier, and is a single fast call. This adds useful behavioral context without contradicting annotations.

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

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

The description is long but well-structured: it opens with a strong preference statement, explains what the tool does, then provides usage triggers, examples, and escalation paths. Every part adds value, though it could be slightly condensed without losing meaning. Front-loaded with the most critical information.

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

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

Given no output schema, the description does well to explain return format (structured answer with citation URIs) and scope (source count, tool count). It also covers when to use and when not to use, making it sufficiently complete for an AI agent to 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%, with the question parameter and its aliases fully documented in the JSON schema. The description text does not add additional parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: it routes questions to one of 5,529 tools across 1,455 sources and returns structured answers with citations. It uses specific verbs like 'routes' and 'returns', and distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and gives concrete examples. It also specifies when to step up to alternatives ('Step up only when needed...') and mentions limitations of alternatives, such as grounded being hallucination-resistant and deep_research being for broad/multi-part questions.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses the experimental nature, live candidate routing improvements, and the fact that it is a full working router with no fallback. This adds valuable behavioral context about potential variability and current state, exceeding what annotations alone 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 four sentences and conveys significant context: beta status, current state, usage instruction, and fallback clarification. It is slightly verbose but each sentence adds necessary information, so it's concise without losing substance.

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

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

The description covers purpose, current state, usage, and experimental behavior, and references the same response shape as ask_pipeworx. Given that annotations and schema handle safety and parameters, this is sufficient for a beta router tool, though it doesn't detail the response format explicitly.

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

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

The input schema already covers all six parameters (question plus five aliases) with 100% coverage. The description only says 'same arguments' as ask_pipeworx, adding no extra semantic detail. Thus it stays at the baseline of 3, 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 identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx by its experimental routing improvements, making the purpose and differentiation explicit.

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

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

Provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' Also clarifies that it currently matches ask_pipeworx since no candidate is active, and states that results are compared against the stable router. This tells the agent when to choose this tool over alternatives.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses critical behavioral traits: the grounding mechanism (uses ONLY tool results), the exact return structure with evidence and confidence, the explicit refusal reasons (not_in_source, no_tool_match, etc.), and the extra LLM call overhead. This goes well beyond what annotations provide and helps the agent predict 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 new information: purpose, routing mechanism, return format, refusal behavior, use cases, and cost tradeoff. The structure front-loads the main purpose and then flows logically into details. No wasted words; the length is appropriate for the tool's complexity.

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

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

For a complex tool with no output schema, the description manages to cover the return format (success and refusal), error handling, use cases, and performance characteristics. It also provides enough context about the routing through 5,529 tools to set expectations. The description is fully self-contained and leaves little ambiguity for an agent.

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

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

Schema description coverage is 100%: all 6 parameters are aliases for 'question' and are described in the schema. The tool description adds no parameter-level detail, but per the rubric a 3 is baseline when schema covers everything. The description does not compensate with usage nuances, but the schema is self-explanatory.

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

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

The description explicitly states this is a 'hallucination-resistant answer mode for high-stakes reads,' and distinguishes it from the sibling 'ask_pipeworx' by explaining it extracts answers only from tool results and returns evidence. It clearly covers verb (extract/answer), resource (Pipeworx tools), and scope (grounded, evidence-based), differentiating it from other tools.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also provides an exclusion: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost. This is textbook usage guidance with alternative named.

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 strong annotations (readOnly, openWorld, idempotent, non-destructive), the description goes far beyond them by disclosing critical safety behaviors: low-confidence matches short-circuit with status:'low_confidence_match' and suppress analysis; closed/inactive markets return status:'market_closed_or_inactive'; wide-spread markets carry tradeability:'illiquid_wide_spread'; resolution-rule risk parses cancellation rules and quantifies ev_impact. It even explains GDELT 429 fallback behavior. 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, but its structure is well-organized with uppercase section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Each section delivers actionable information without fluff, and the length is justified by the tool's complexity. Minor redundancy exists between SAFETY and RESOLVER CONTRACT regarding low-confidence matches, preventing a perfect score.

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

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

With no output schema, the description fully carries the burden of explaining return values. It does so thoroughly: result.market fields, result.analysis with model probabilities and edge, result.evidence keyed by source, resolver contract fields, parent_event structure, and status codes. It also covers classifiers, fan-out examples, safety mechanisms, and resolution-rule risk—covering every aspect a user agent needs to invoke the tool and interpret results correctly.

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

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

Although schema coverage is 100% (baseline 3), the description adds meaningful value beyond the schema: market input formats are expanded with examples and question-text clarification, include_raw gains 'when you need to recompute deltas, cite specific observations, or post-process', and depth's quick vs thorough fan-out is illustrated via concrete examples (BTC, Fed, Hormuz). The description also enriches understanding of what the parameters ultimately affect in the output structure.

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 pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states inputs (slug, URL, question text), the resolution/classification/fan-out workflow, and the output (evidence packet + market-vs-model comparison). The scope is unambiguous and easily distinguishes it from sibling tools like deep_research or get_crypto_price.

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

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

The description explicitly says to use it for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z', which is a clear usage context. It also explains when to set include_raw=true (needing to recompute deltas, cite observations, post-process). However, it does not explicitly state exclusions or when-not-to-use compared to alternatives like get_crypto_price or ask_pipeworx, so it falls short of a 5.

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

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

While annotations already declare readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral context: data source (SEC EDGAR/XBRL for companies, FAERS for drugs), specific financial fields pulled, handling of off-calendar fiscal years, result sorting by primary metric, and return format (paired data + citation URIs). This goes well beyond the annotations and no contradiction exists.

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

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

The description is dense but every sentence carries important information. It starts with trigger phrases, then explains functionality, data sources, edge cases, and output. It is slightly longer than strictly necessary but remains well-structured and front-loaded with the most critical usage context. Could be trimmed slightly, but 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?

Without an output schema, the description fully explains return values (paired data + citation URIs) and behavior. It covers edge cases (off-calendar fiscal years), sorting, and data sources. Given 2 parameters and no output schema, this description is complete for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning. It explains what 'type=company' returns (latest 10-K revenue, net income, cash, long-term debt) and what 'type=drug' returns (FAERS counts, FDA approval counts, trial counts). It also gives concrete value examples (AAPL, MSFT; ozempic, mounjaro) and notes sorting behavior, adding value beyond the schema.

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

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

Purpose is crystal clear: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It specifies the resource (companies/drugs), the action (compare), and the scope (2–5 entities). It also distinguishes itself from sequential single-pack lookups, which is a primary alternative.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides trigger phrases ('compare X and Y', 'X vs Y', 'which is bigger'), which tells the agent exactly when to invoke this tool. It also clarifies data sources for each type, giving clear usage context.

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

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

The description goes far beyond the annotations, disclosing expected latency (15-60s, thorough up to ~90s), the structure of findings (verbatim evidence + confidence + source + fetched_at + citation_uri), behavior on unanswered facets (gaps[]), the 'never invented' guarantee, and the semantic excerpting of large records. No contradiction with annotations; all are additive and contextual.

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 crucial operational or safety information: account requirements, tool differentiation, processing model, output format, latency, and limitations. It is front-loaded with the most critical user-gating info and flows logically. Minor redundancy exists (e.g., 'never invented' appears twice near the end) but overall it remains appropriately dense, not bloated.

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 (2-param, no output schema, heavy annotations), the description covers all necessary context: return format, gaps/contradictions, citation resolvability, timing, pricing, and explicit alternatives. It even explains edge cases like 'returns mostly empty gaps[] when the topic isn't in the structured catalog'. This is complete for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters, establishing a baseline of 3. The description adds meaningful depth-mode semantics beyond the schema, such as 'depth:"standard" re-angles unanswered gaps' and 'thorough additionally chases the best leads', which clarifies the enum's operational impact. Question parameter is naturally explained via 'Broad/multi-part is fine' and the decomposition point.

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, multi-clause definition: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explains the decomposition/routing process. It also clearly distinguishes this from sibling ask_pipeworx ('For a single lookup use ask_pipeworx'), satisfying the sibling-differentiation criterion.

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 and when-not-to-use guidance is abundant: 'Best for broad/multi-part questions...', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides alternative conditions based on account tier (if not signed in, use ask_pipeworx). This is a model of usage clarity.

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, but the description adds valuable behavioral context: it returns top-N tools with full input schemas and curated examples, ready to call directly without a second lookup. It also advises calling this tool first, which goes beyond the annotations.

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

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

The description is well-structured and front-loaded with the purpose. It includes a helpful but somewhat lengthy list of domains and then explains output and usage priority. Each sentence contributes, but the domain list could be trimmed without losing much value, so a 4 is warranted.

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 (6 parameters, no output schema), the description is remarkably complete. It explains the return format (names, descriptions, full input schemas, curated examples), the use case, and the recommended placement in the tool selection flow. The absence of an output schema is compensated by the explicit description of the result.

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

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

Schema description coverage is 100%, with clear descriptions for query, q, task, limit, search, and description. The tool description adds some context about 'top-N' and natural language queries, but it does not significantly extend the parameter meanings. With full schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: 'Find tools by describing the data or task.' It uses a specific verb and resource, and the enumerated domains (SEC filings, FDA drugs, etc.) distinguish it from sibling domain-specific tools. This is a meta-tool for discovery, which is immediately evident.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use it ('not just one answer') but does not explicitly name alternatives or provide a when-not list, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behaviors: parallel fan-out across sources, patent API sunset with soft-fail, GDELT→GNews fallback, and the exact return fields including URIs and sorting. 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 densely packed with valuable information. It is front-loaded with user-intent examples and quickly establishes the tool's role. Each sentence adds meaningful context—preference, sources, return fields, input format—so every part 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?

Given the tool's complexity (multiple sources, no output schema), the description is exceptionally complete. It enumerates all returned fields, explains fallbacks and limitations, and provides usage context. Nothing needed for invocation or understanding return values is missing.

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

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

Schema description coverage is 100% for both parameters. The description repeats the same parameter constraints (ticker or CIK, names not supported) but adds no new semantic detail beyond the schema. Baseline 3 is appropriate since schema carries the full burden.

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: "full cross-source profile of a US public company in ONE parallel call." It uses specific verbs (profile, research, brief) and distinguishes itself from sibling tools by explicitly preferring it over chaining single-pack lookups and by directing users to resolve_entity for name-only queries.

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

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

It provides explicit when-to-use guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also states exclusions: names are not supported, use resolve_entity first. The examples of user queries make it clear when this tool should be selected.

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 baseline is lower. The description adds context beyond annotations by explaining the purpose ('clear sensitive data the agent saved earlier') and the deletion semantics ('previously stored memory'). It also notes the pairing with remember/recall, which is useful behavioral context. No contradiction found.

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

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

The description is two sentences, front-loaded with the action. Every sentence provides value: what it does, when to use it, and its relationship to sibling tools. No redundant or filler content.

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

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

The tool is simple with one parameter, no output schema, and annotations covering destructive/idempotent behavior. The description covers purpose, usage conditions, and pairing with related tools. There are no critical gaps for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% for the single 'key' parameter, with description 'Memory key to delete'. The tool description only repeats 'by key' without adding format, examples, or further semantics. Baseline 3 applies since the schema fully documents the parameter.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific, and the phrase 'previously stored' distinguishes it from remembering or recalling. It also names the sibling tools 'remember' and 'recall', making the deletion 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?

Explicit conditions are provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This tells the agent exactly when to invoke the tool. It also says 'Pair with remember and recall,' giving clear alternatives and integration context.

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

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

The description discloses the tool's behavior: it fetches the page, extracts title/description/key links, and emits a single text blob in standard llms.txt markdown. This adds process context beyond the readOnlyHint and idempotentHint annotations, confirming it performs a live read operation without mutation.

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

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

The description is compact and front-loaded, stating the core purpose in the first sentence. The 'Useful for' list adds value without redundancy, making every sentence earn 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 only two parameters, both well-documented in the schema. Annotations cover safety and idempotence. The description specifies the output format ('single text blob') and use cases, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the schema already fully documents them. The description doesn't add any additional parameter-specific details, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It explains the process (fetches, extracts, emits) and distinguishes itself from sibling tools by focusing on file generation rather than visibility analysis.

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 provides concrete scenarios such as getting a client's site indexed, drafting llms.txt for one's own project, or auditing a competitor's AI visibility. It doesn't explicitly name alternative tools or when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing a safe read-only behavior. The description adds valuable context by listing the exact return fields and, through the parameter description, notes the keyless free endpoint and option for a dedicated quota, which informs expectations about data source and 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 with no filler. The first sentence states the purpose, and the second delivers usage preference and output details. It is front-loaded with the tool essence, making it highly 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?

Despite lacking an output schema, the description enumerates the return fields, which gives the agent a clear idea of the response shape. The tool is simple with one optional parameter and strong annotations, and the description covers the primary use case; however, it omits any potential limitations like data freshness or throttling for the keyless endpoint.

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 provides 100% coverage for the single optional _apiKey parameter, including detailed behavior about the api-pro endpoint and failover for get_crypto_price. The description itself adds no parameter-specific meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool returns a 'Global cryptocurrency market overview' and enumerates specific metrics like total market cap, 24h volume, and Bitcoin dominance. It identifies the resource and scope well, but it does not explicitly differentiate from sibling crypto tools such as get_crypto_market, leaving some ambiguity.

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 OVER WEB SEARCH' for queries about total crypto market cap, bitcoin dominance, and state of the crypto market, which provides clear when-to-use guidance. It does not, however, mention when to use alternative crypto-specific tools, so it lacks 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it names the data source (coinpaprika), discloses the free-tier limitation (~last year), and specifies the exact return fields (date, price USD, 24h volume, market cap). This is substantial behavioral disclosure.

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

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

The description is a single, front-loaded paragraph. Each sentence adds distinct value: scope, usage examples, return format, accepted identifiers, and data source limitation. It is longer than a two-sentence ideal but not verbose or redundant.

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

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

With no output schema, the description compensates by explicitly listing the daily time-series fields and coverage limits. It handles the 5-parameter complexity reasonably well, though it could have added an explicit 'for current price use get_crypto_price' contrast. Overall, it is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining that coin_id accepts common names, tickers, or coinpaprika IDs, and by clarifying that the time series starts from the start date. The schema's _apiKey note about failover also adds context, raising the score above baseline.

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

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

The description opens with 'HISTORICAL price history for a cryptocurrency', a specific verb+resource combination, and immediately signals scope. The examples ('bitcoin price last 30 days', 'ETH price history') make the purpose unmistakable and implicitly distinguish it from current-price tools like get_crypto_price.

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 'PREFER OVER WEB SEARCH' with concrete query examples, which is strong usage guidance. It also notes the keyless free tier covers roughly the last year, setting expectations. However, it does not directly contrast with sibling tools like get_crypto_price or get_crypto_market, so the when/when-not guidance is not fully explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return-field list but does not reveal additional behavioral traits like rate limits, endpoint selection, or keyless vs. API-key behavior; those details appear only in the parameter schema, not the description.

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

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

The description is a single, efficient sentence that front-loads the core action and result fields. It contains no filler or redundant information, every phrase earning 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?

Given the low complexity, rich annotations, 100% schema coverage, and the presence of an output schema, the description is complete. It conveys the purpose, sorting basis, and returned fields, leaving no significant gaps for an agent to 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%: both 'limit' and '_apiKey' have meaningful descriptions, including default values and optionality. The main description adds no parameter-level meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states the exact operation: 'Get top cryptocurrencies ranked by market cap' and enumerates the returned fields. This clearly distinguishes it from sibling tools like get_crypto_price, get_crypto_history, and get_crypto_global by specifying the ranking scope and data fields.

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 a use case—retrieving a market-wide ranked list—but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or exclusions, so the agent must infer appropriate usage from the tool's purpose.

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

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

Beyond the readOnlyHint and other annotations, the description discloses that data refreshes every few seconds and includes automatic failover to Coinbase/CryptoCompare if coinpaprika is rate-limited, ensuring a real price is always returned. This is valuable behavioral context not present in annotations.

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

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

The description is one well-organized paragraph, front-loaded with the core purpose and followed by specific usage examples and technical details. Every sentence contributes unique information; there is 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?

The description covers the tool's purpose, input flexibility, API key option, fallback behavior, and return fields. Combined with the rich annotations and output schema, it provides a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra semantics by explicitly listing accepted input forms (common names, tickers, coinpaprika IDs) and explaining the optional _apiKey behavior, which goes beyond the basic schema and justifies a score above the baseline.

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

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

The description opens with 'REAL-TIME spot price for any cryptocurrency', which is a specific verb + resource that clearly states the tool's function. It also differentiates from web search and implies distinction from sibling crypto tools like get_crypto_history by focusing on spot price.

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 advises 'PREFER OVER WEB SEARCH for...' and lists concrete query examples, giving strong when-to-use guidance. It doesn't explicitly mention sibling tools like get_crypto_market or get_crypto_history as alternatives for related but different needs, so it stops short of full when-not-to-use coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds a small detail about returning conversion rate and timestamp, but no deeper behavioral context (e.g., live vs. snapshot rates, data source, limits) is provided.

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

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

The description is a single, front-loaded pair of sentences with no redundant words. It communicates purpose and core output clearly, earning maximum points for conciseness.

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

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

For a simple read-only tool, the annotations and schema cover safety and parameter semantics well, and the output schema presumably documents return values. However, the description does not clarify whether passing 'amount' alters the return (e.g., converted amount vs. just rate), which introduces slight ambiguity.

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

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

The input schema has 100% description coverage for all three parameters, so the description does not need to add parameter meaning. It does not; it stays silent on parameter semantics, which is acceptable given the schema's completeness.

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

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

The description opens with a specific verb ('Convert') and identifies the resource ('between fiat currencies') with a concrete example ('USD to EUR'). This clearly differentiates it from the many crypto-focused sibling tools like get_crypto_price.

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 for fiat currency conversion but does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions. The example clarifies fiat scope, but no alternative tools are referenced.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations, such as caller scoping, active-only filtering, and the exact response fields, giving the agent a fuller picture of 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 two sentences, front-loaded with the core action, and contains no unnecessary words. Every element—purpose, returned fields, and usage guidance—is packed efficiently.

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 low complexity (one optional parameter, no output schema) and comprehensive annotations, the description is fully complete. It covers return values, caller scoping, and usage guidance, leaving no significant gaps for an agent to 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% for the single optional parameter include_inactive, so the schema already documents it well. The description does not add extra parameter semantics, but the baseline of 3 is appropriate since the schema handles the burden.

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

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

The description uses the specific verb 'List' with the resource 'active subscriptions', clearly distinguishing it from sibling tools like subscribe/unsubscribe. It also enumerates the returned fields (id, type, params, etc.), making the tool's purpose precise and unambiguous.

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

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

The description explicitly states two use cases: reviewing what you're monitoring before adding more subscriptions and finding an id to cancel. This implies alternatives (subscribe/unsubscribe) without naming them directly, providing clear context for 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?

All annotation hints are false, so the description carries the full burden of behavior. It discloses several non-obvious behaviors: filing without an account returns a claim_token for later status reads, rate limiting to 5 per identifier per day, and that it's free with no impact on tool-call quota. No contradiction with annotations.

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

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

The description is front-loaded with the primary purpose and maintains a logical flow from usage to exclusions to token mechanics. However, it includes a few non-essential details such as 'The team reads digests daily and signal directly affects roadmap' that do not affect how an agent should invoke the tool, making it slightly longer than strictly necessary.

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 explains the return flow (claim_token for anonymous filing and later status reads), rate limits, scope limitations, and cost, which fully covers the key operational aspects. The rich schema covers parameter details, and the description adds all contextual behavior needed for correct invocation.

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

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

The schema provides 100% coverage with rich descriptions for all four parameters, so the baseline is 3. The description adds extra meaning by warning not to paste the end-user's prompt (message parameter) and providing a concrete invocation example for the claim_token parameter (`pipeworx_feedback({claim_token:"pwfb_…"})`), which goes beyond the schema's text.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools by scoping to 'tools served by this Pipeworx connection' and explicitly excluding feedback for other MCP servers, making it unambiguous.

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

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

Explicitly lists triggers for each feedback type ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)') and gives a clear exclusion for tools from other MCP servers with the alternative instruction to 'file it with that server instead.' It also advises how to phrase the message in terms of Pipeworx tools/packs.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral context: it is 'self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This discloses data provenance, privacy, and freshness characteristics that the annotations do not cover.

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

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

The description is front-loaded with the core return value, then organizes use cases in a numbered list, and finishes with essential data-quality notes. Every sentence carries useful information and there is no redundant filler. The em-dash aside about source and PII is compact but substantive.

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

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

For a simple tool with one optional parameter and no output schema, the description covers return contents, caching behavior, data privacy, and use cases. It is fully self-contained and gives an agent enough context to decide when and how to invoke it, even without additional structured information.

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 the `window` parameter with valid enum values and a description. The tool description adds further nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which enriches the meaning beyond the schema. Given 100% schema coverage, the baseline is 3, but the added semantic context justifies a 4.

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

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

The description opens with a clear, specific purpose: 'What other AI agents are calling on Pipeworx right now' and explicitly states the returns: 'top tools, top packs, and total call volume.' This distinguishes it from sibling tools like `discover_tools` by focusing on aggregated usage trends rather than individual discovery or searches.

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

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

The description provides three explicit use cases ('Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns...'). This gives clear context for when to use the tool, though it does not explicitly list alternatives or when-not-to-use scenarios.

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 rich behavioral details: SEMANTIC ANCHOR (Jaccard similarity ≥0.30), PARTITION FILTER (placeholder fraction >20% returns null), response structure, and FILL CHECK logic (theoretical vs realizable edge, 'do not trade it' if ≤0). These caveats help the agent understand not only what is computed but also the limitations and edge cases.

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 deliberately structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and paragraph breaks for modes. It front-loads the core purpose and each subsequent sentence adds necessary operational detail for a complex tool. No sentence feels wasted; the length is appropriate for the tool's complexity.

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

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

Without an output schema, the description compensates by detailing the response fields: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and the partition_check object in event mode. It also covers filtering rules, fill checking, and points to an alternative tool, making the behavior fully comprehensible to 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?

Although the input schema already describes both parameters, the description adds deep behavioral context: event 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check', while topic 'searches related events across the platform, flattens markets, runs the comparator on the union'. It also explains the no-args case, which is not in the schema, and provides concrete slug/seed examples.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes the tool from siblings like polymarket_edges or polymarket_fill_risk, and explains its unique methodology. The three modes (no-args, event, topic) further clarify the scope.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It names an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'), and includes a caution about not trading when the fill check shows no realizable edge. This provides clear decision 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses extensive behavioral details: three segments and their model families, response top-level structure, edge metrics including Kelly caps and slippage subtraction, filtering knobs' effects, diagnostics for empty segments, and 1h KV-level caching. It also explains design quirks like partition arbs returning zero parent-level Kelly.

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 unique information: model formulas, segment groupings, edge fields, knobs, response schema, diagnostics, and caching. It is front-loaded with the core purpose and then logically organized into segments, response details, and operational notes. 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 fully specifies the response top-level structure (by_segment, fed_candidates, _diagnostics) and explains the meaning of each segment and diagnostics. Combined with high schema coverage and rich annotations, the tool is completely specified despite its complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics: it explains how min_liquidity/max_spread_pp drop non-tradeable edges, that min_kelly never filters partitions because parent-level Kelly is always 0, and that min_partition_leg_kelly instead applies to per-leg Kelly. This goes beyond the raw schema descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is explicitly built for 'what should I bet on today' and distinguishes itself from plain market listings by focusing on data/market disagreement and opportunity discovery, which clearly separates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description gives clear context for when to use the tool ('what should I bet on today', discover opportunities without paging hundreds of markets) and mentions limitations (Fed bets unreliable). However, it does not explicitly name alternative sibling tools or state when NOT to use this tool in favor of another, so it stops short of a full 5.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important operational behaviors: snapshots are written only on cache-miss (so gaps mean no scan), history is bounded by a 60-day TTL, and decay is computed from daily closes of edge_pp_net (not intraday). These details give the agent critical expectations about data completeness and computation methodology.

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 with labeled sections (Args, RESPONSE, LIMITS) and front-loads the primary purpose. It is long, but each sentence delivers essential context — response shape, edge cases for expired opportunities, and data availability caveats — which is justified given the absence of an output schema. Not perfectly concise, but efficient for the complexity.

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

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

With no output schema, the description compensates by fully enumerating the response fields (tracked, expired, snapshot_dates) and explaining their semantics. It also covers operational limitations (TTL, cache-miss gaps, daily close computation), making the tool's behavior fully predictable for an agent. No significant information is left unstated.

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

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

The input schema already provides 100% coverage with clear descriptions for both parameters (days lookback with clamp, window family with enum). The description's Args section adds only a narrative rehash of the same defaults and no new semantic meaning. Since schema coverage is total, a baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('Edge persistence and decay telemetry built from daily polymarket_edges snapshots') and immediately distinguishes its historical focus from the current-edge data provided by sibling tools like polymarket_edges. The phrase 'how long has this edge existed and is it shrinking?' crisply captures the tool's unique value.

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

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

The description clearly states the use case ('a fresh wide edge and a 3-week-old wide edge are different trades') and makes the context obvious. However, it does not explicitly name alternative tools or provide explicit when-not-to-use guidance, so it falls just short of a 5.

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

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

Annotations already mark this read-only, open-world, idempotent, non-destructive, and the description adds critical behavioral context beyond those flags: it walks the order-book ladder, returns a verdict, and warns that partial basket fills create unhedged directional risk. It also explains that theoretical overround on thin books is not capturable. This exceeds the annotation baseline and contradicts nothing.

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

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

The description is long but front-loaded with a one-sentence summary and then organized by SINGLE-MARKET/BASKET sections. Every sentence adds substantive detail like output fields and failure modes. It could be more readable, but the density is necessary given 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?

With no output schema, the description enumerates all return fields and provides both mechanical outputs and risk-related outputs (thin_legs, forced_directional_risk). It covers the real-world failure mode of partial fills, which is essential for using this tool responsibly. The use-case guidance completes the picture.

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

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

Schema coverage is 100%, but the description adds value by requiring exactly one of market or event, which the schema does not encode as a constraint. It clarifies mode-specific meaning of size_usd (spend vs proceeds vs settlement notional) and default side selection for baskets, going beyond the schema's individual 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource that identifies the tool's function. It clearly distinguishes from siblings like polymarket_arbitrage by positioning this as the pre-trade risk check and specifying modes. This is a clear, purposeful statement.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' making the preferred invocation context unambiguous. It also differentiates single-market vs basket modes, implying when each is appropriate. No misleading exclusions are present.

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

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

The description extensively discloses behavior beyond the read-only annotation, including compatibility_warning cases, temporal_alignment, skipped_cross_type counters, and the reality that most macro topics are not tradeable. This is exactly the kind of non-obvious behavioral context an agent needs.

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, but the structure is organized around MODES, RESPONSE, and SAFETY FIELDS. It front-loads the core purpose and every section earns its place given there is no output schema.

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

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

With no output schema, the description covers the return context: leg-by-leg prices, top_spreads_pp, compatibility warning conditions, temporal alignment, and skip counters. It also covers failure modes and operational context for a complex cross-venue 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?

The input schema already documents all three parameters with descriptions and examples. The description adds the mode semantics: topic auto-fetches the matching event, while explicit ticker/slug overrides the mapped side, which genuinely supplements 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 defines a specific cross-venue spread tool between Kalshi and Polymarket and details its two modes with concrete examples. It clearly identifies the resource and distinguishes from sibling tools like polymarket_arbitrage by emphasizing the same resolving question across venues.

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

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

The description explains when to use the topic shortcuts vs explicit tickers and warns that most pre-mapped topics currently return compatibility_warning, so pre-mapped is not tradeable. It does not name explicit alternatives, but the context and caveats provide clear use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description does not contradict them. It adds additional behavioral context about scoping to an identifier and the ability to list all keys when the argument is omitted, which is beyond what annotations convey.

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

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

Four sentences, each adding distinct value: core action, usage scenario, scoping detail, and relation to siblings. No fluff or redundancy. The description is front-loaded with the primary action.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, usage, scoping, and related tools adequately. It does not describe the return format or error behavior, but for a straightforward lookup tool with strong annotations, this is sufficient.

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

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

The schema already fully describes the key parameter (100% coverage), so the description's mention of omitting the key to list all keys adds no new structural information. It does provide examples of values (ticker, address, research notes), which adds some semantic context but not enough to exceed the baseline.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs (retrieve/list) and identifies the resource (saved memory values/keys), and distinguishes itself from sibling tools like remember and forget.

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

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

It explicitly explains when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also references the complementary tools (remember/forget), providing contextual guidance on how this tool fits into a workflow.

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, idempotentHint), the description discloses the important side effect of mark_read:true, which flags events as read and affects subsequent calls. It also reveals the return payload content (source, citation_uri, raw event payload) and the existence of an external feed endpoint. No contradiction with annotations is present.

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-loaded with the primary purpose, and every sentence contributes new information: the resource, return fields, filter options, mark_read effect, and an alternative HTTP endpoint. There is 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?

With no output schema, the description compensates by specifying the return shape (source, citation_uri, raw payload). It also addresses polling behavior and provides a script-friendly alternative. Given the tool's moderate complexity (5 optional params, no required fields, read-only default with optional side-effect), the description is complete enough for an agent to select and invoke correctly.

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

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

The schema covers all 5 parameters with descriptions, giving a baseline of 3. The tool description adds meaningful semantic context, such as 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)' and the effect of mark_read on future calls. It does not elaborate on limit or unread_only, but the schema already does so, keeping the description's added value at a solid level.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It further clarifies the resource as 'the most recent alerts the evaluator has written to your persisted feed,' distinguishing it from generic list tools. Although there is no sibling with an identical name, the description clearly scopes the tool to alert retrieval, which differentiates it from subscription management tools like list_subscriptions.

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

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

The description provides clear context on when to use the tool (to fetch recent alerts, filter by type/since) and states that polling is acceptable. It also gives an explicit alternative for scripts/dashboards via the registry.pipeworx.io URL. However, it does not explicitly mention when to prefer this tool over siblings like recent_changes or when not to use it, so some exclusion guidance is missing.

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

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

Beyond annotations (readOnly, idempotent), it discloses the fan-out architecture, GDELT→GNews fallback for rate limits/5xx, and USPTO soft-fail due to PatentsView sunset. This gives the agent realistic expectations about source reliability 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?

A single dense paragraph that front-loads the purpose with natural-language examples before diving into sources and output. Every clause provides useful data, though the sentence about PatentsView sunset adds complexity for a soft-fail edge case.

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 multi-source complexity and no output schema, the description covers source list, fallbacks, time-window formats, and return shape (changes[], total_changes, citation URIs). Minor gaps remain around edge cases like empty results or ambiguous entity resolution, but it is sufficient for selection and invocation.

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

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

The schema already documents all three parameters thoroughly: type enum, value ticker/CIK, and since with examples and relative format. The description adds only minor usage guidance ('Use 30d or 1m for typical monitoring') without materially expanding on schema 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 opens with natural-language triggers ('What's new with X') and clearly states the tool returns a change feed for a company, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It explicitly distinguishes itself from sibling entity_profile by naming when to use that alternative.

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 with example queries and states 'Use entity_profile instead' for static profiles regardless of window. It also notes the company-only scope and recommends typical monitoring windows ('30d' or '1m').

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 idempotent and non-destructive behavior, and the description adds valuable context beyond those: key-value scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. It does not contradict annotations and gives the agent useful expectations about memory lifetime.

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

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

The description is well-structured: it opens with the main action, then gives usage guidance, then explains storage semantics, and ends with companion-tool references. Every sentence earns its place, though it is slightly longer than strictly necessary, so it earns a 4 rather than a 5.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, usage, persistence rules, and related tools. The only missing piece is an explicit statement about what the tool returns (e.g., a confirmation), but this is not critical for a storage operation and the description is otherwise complete.

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

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

The input schema already provides full coverage with descriptions for both parameters (key and value), including examples in the key description. The tool description itself does not add new parameter details beyond stating that it is a key-value pair, so it adds no extra meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, using a specific verb ('Save') and resource ('key-value pair'). It also distinguishes itself from the sibling tools by explicitly naming 'recall' and 'forget' as companions, making its role in the memory workflow 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?

It provides concrete use cases ('a resolved ticker, a target address, a user preference, a research subject') and explicitly mentions the companion tools 'recall' and 'forget'. However, it does not clearly state when NOT to use it, such as for transient data or when a different tool would be more appropriate, so it falls short of a 5.

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

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

The description goes well beyond the readOnlyHint/idempotentHint annotations by describing graceful degradation (EDGAR still returns if GLEIF/OpenFIGI unavailable), explicit `unresolved` handling, source-labeling of each identifier, and internal cascade through multiple endpoints. These are valuable behavioral insights not inferable from 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 and well-structured, starting with example queries then core purpose and type-specific details. It is somewhat long but every sentence carries information; the length is justified by the tool's complexity. The structure uses clear labels (SUPPORTED TYPES) to aid skimming.

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 and only two simple parameters, the description fully compensates by explaining return-content per type, degradation behavior, and the `unresolved` field. An agent has enough information to decide when to invoke the tool and what to expect from the response.

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 the parameters, but the description significantly enriches the value parameter by explaining what each type returns (CIK/ticker/LEI/FIGI for company, RxCUI/ingredient/brand for drug) and which input variants are accepted. This provides meaningful semantics beyond the schema's brief field comments.

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

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

The description clearly states the tool resolves a user-spoken name into canonical/official identifiers, with a specific verb (resolve) and resource (identifiers). It distinguishes itself from siblings by positioning as the name-to-ID lookup tool, while e.g., entity_profile is not for ID resolution. The many example queries make the purpose immediately obvious.

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 FIRST whenever you have a name but need an ID' and gives concrete input formats for each supported type (company, drug). It does not name sibling alternatives or specify when-not to use, but the guidance is clear and applied. Mentions it 'replaces 2-3 manual lookups' as a practical tip.

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 the safety profile. The description adds useful behavioral context: it probes each entity, ranks by score, and returns a ranked list with specific metrics. This exceeds the annotation baseline without contradiction.

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

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

The description is three sentences, front-loaded with the main purpose, includes a practical example, and no filler. Every sentence contributes meaning, and the return-value summary is succinct.

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?

Since there is no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also frames the use case and the entity semantics. For a tool with four parameters and no output schema, this is complete and self-contained.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description restates that the first entity is the subject but doesn't add new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from the sibling tool ai_visibility_check by explicitly stating it probes each entity with that tool and ranks them, making the multi-entity comparison purpose unmistakable.

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

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

It provides a concrete use case ('competitive AI-marketing audits') and an example query. While it doesn't explicitly say when not to use it or name alternative tools, the mention of ai_visibility_check as the underlying probe implies the single-entity alternative. Clear context but no explicit exclusions.

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, idempotent, open-world behavior. The description adds meaningful behavioral detail beyond annotations: composite fan-out nature, partial failure handling, the 5-30s first-measurement latency for bundlephobia, and the sources_failed field. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and then efficiently covers use cases, return fields, limitations, and failure behavior. Every sentence adds distinct value; no fluff or repetition of schema/annotations.

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

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

Given no output schema, the description compensates by enumerating the summary block fields, per-advisory details, links, and alternative versions. It also covers ecosystem scope, latency, and graceful degradation, making the tool's behavior fully predictable for the agent. The tool's complexity is high, but the description leaves no significant gaps.

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

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

Schema coverage is 100%, with both 'package' and 'version' already described clearly, so the baseline is 3. The description adds context that the package is npm and that version defaults to latest, but the schema already handles that. It does not add new parameter-level details 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 a specific composite check for npm packages, using a concrete question ('should I add this npm package') and explicitly naming the data sources (deps.dev, bundlephobia). It distinguishes itself from siblings by focusing on dependency/packaging risk and cost, not entity profiles or competitors.

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

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

Provides explicit trigger phrasing ('Use whenever an agent asks "is X safe / popular / small"...') and exclusion guidance for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This gives the agent both when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnly=true and destructive=false, but the description adds non-obvious behavior: BGE-base-en embeddings, 500-char overlapping windows, 200K cap with truncation flagging, and that every passage carries character offsets for quote verification. This goes well beyond the structured 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?

Four sentences, each serving a distinct purpose: definition, use case, pairing with sibling, and technical constraints. No filler; the information is front-loaded and efficiently packed.

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 3-param tool with no output schema, the description covers input expectations, output shape (top-N passages with offsets and similarity scores), limits (200K chars, truncation), and its relationship to ask_pipeworx_grounded. With annotations covering safety, this is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for all 3 parameters, so baseline is 3. The description adds examples for the text parameter (SEC 10-K body, article, tool result) and clarifies that the text is already fetched and not to be retrieved, plus the truncation flag behavior for long inputs. These enrich the bare schema but aren't critical due to already-solid schema descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record' – a specific verb (search), resource (fetched record), and scope (inside). It clearly distinguishes from siblings by explaining it operates on already-fetched text and pairs with ask_pipeworx_grounded, so it's not a fetch or grounding tool itself.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and highlights the benefit of saving context. It also names the alternative ask_pipeworx_grounded for grounding over relevant passages, giving clear when-to-use and with-what-to-pair 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?

Beyond annotations, the description discloses important behavioral constraints: OAuth account requirement, phone verification, 10/day SMS cap, always-on feed behavior, and the fact that webhook signing secret is returned once. These details help the agent anticipate failure modes and side effects, adding significant value beyond 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 and front-loaded with the core purpose, followed by prerequisites, types, and delivery details. Every sentence carries useful information, but the length is substantial and could benefit from light formatting (e.g., bulleted types). It is not wasteful, but not as crisp as minimal high-quality examples.

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—multiple subscription types, nested params, and optional delivery channels—the description covers requirements, supported types with examples, delivery behavior, and return value. The schema fills in remaining nested-object structure, so the combined definition is complete even without an output schema.

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

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

Although schema coverage is 100%, the description substantially expands each parameter's meaning: sec_8k item codes (e.g., items:["5.02"] = officer change), polymarket_edge topic, fred_series series_id, and delivery channel semantics including webhook HMAC signing. This is far beyond baseline and helps the agent set correct values.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts, and states the key output.

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

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

The description gives clear context for appropriate use: requires a Pipeworx OAuth account, notes that anonymous/BYO cannot persist subscriptions, and lists supported types with examples. It also mentions that the feed is always on and can be pulled via recent_alerts or the registry URL, hinting at alternatives for reading alerts. It stops short of explicitly naming alternative tools for every scenario, so 4 rather than 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds useful context like drawing from a live catalog and the format of returned examples. No negative behaviors or side effects need 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 but each sentence adds value: entry-point definition, return format, call patterns, and usage directive. The opening list of example queries is slightly redundant but serves as useful matching snippets for an agent.

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

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

Given one optional parameter, complete annotations, and clear description of return value (categories + exact tool/arg shape), the description fully covers what an agent needs to invoke this tool correctly. No output schema is needed because return behavior is explicitly described.

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

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

Schema covers the topic parameter with enum-like options, and the description adds extra examples ('finance', 'pharma', 'betting') and clarifies behavior when omitted vs provided (full spread vs focus). This adds meaning beyond the schema's list.

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: returning category-bucketed example questions with exact tool/argument assistance. It positions itself as the onboarding entry point and distinguishes from siblings by recommending use before other meta-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?

Provides explicit 'Use this FIRST' guidance and context for when the agent doesn't know what Pipeworx can do. It mentions learning to call meta-tools as an alternative, but does not give when-not-to-use or compare directly with discover_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?

Adds significant behavioral detail beyond annotations: ownership enforcement, deactivation instead of deletion, and retention of historical events. These details are not present in annotations and help the agent understand side effects.

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

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

Three concise sentences, each adding essential information. The main action is front-loaded, and the additional context (ownership, deactivation, retention) is efficiently stated.

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

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

For a simple one-parameter mutation tool with annotations, the description covers the key aspects: ownership, deactivation, and historical value. It does not mention return values, but given no output schema, this is a minor gap.

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

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

The schema fully describes the single parameter (id as subscription uuid returned by subscribe) with 100% coverage. The description adds no new parameter information, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific resource and verb. It distinguishes from siblings like subscribe and list_subscriptions by focusing on cancellation and adding ownership constraints.

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: only cancel your own subscriptions, and the row is deactivated not deleted. It implicitly guides usage vs. alternatives (e.g., not a hard delete, historical events remain). However, it does not explicitly name alternative tools for other scenarios.

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?

It discloses two distinct execution paths, return verdicts, and the crucial semantic distinction between could_not_verify (check did not happen, not evidence) and unsupported (no source found). This adds rich behavioral context far beyond the readOnlyHint, idempotentHint, and openWorldHint annotations.

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

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

The description is long but well-organized with an 'IMPORTANT for callers' section. The opening list of example phrasing is somewhat redundant, but every other sentence earns its place, so it is not the ideal 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?

With no output schema, the description fully explains return values (verdict, value, citation, reasoning), special error semantics, and the unsupported case. It also clarifies routing and the composite nature of the tool, making it complete for callers.

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 for both parameters, so the description need not add much. It mentions the company-financial path's exact percent-delta math but does not elaborate on tolerance_pct beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a natural-language claim verifier against authoritative sources, with specific triggers like 'fact check' and 'verify the claim that…'. It distinguishes between company-financial claims (SEC EDGAR/XBRL path) and other claims (grounded pipeline), and differentiates itself from sequential calls by noting it replaces 4–6 steps.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and details routing logic. However, it does not name alternative sibling tools or provide explicit when-not-to-use guidance, so it falls short of a 5.

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