Kraken

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond these by disclosing that the default model is free, that passing `_apiKey` incurs direct Anthropic charges, and that returns include per-model and combined views. It doesn't detail rate limits or failure modes, but the added context is meaningful.

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, with the core action front-loaded in the first sentence, followed by configuration details, return format, and use cases. Every sentence contributes new information without redundancy, making it appropriately concise for a tool with this 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 rightly explains the return values: "Returns per-model {score, confidence, signals, raw_response} + a combined view." It covers the main configuration options and use cases. It doesn't address potential error scenarios or explicitly distinguish itself from the similar sibling `scan_competitor_ai_presence`, but it is sufficient for an agent to 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%, so the baseline is 3. The description goes beyond the schema by specifying the default model ("Workers AI Llama-3.3-70b (free)") and clarifying the dependency between `models` and `_apiKey` (BYO key, direct payment). This adds context not present in the parameter descriptions.

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

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

The description clearly states the tool's function: "Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model." This uses a specific verb (probe, score) and resource (LLMs, visibility), making its purpose unmistakable. It also outlines the output format, distinguishing it from generic search 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 provides explicit use cases: "Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring." It also gives conditional guidance on when to pass `_apiKey` (to also probe Anthropic) and notes that Workers AI is the free default. However, it does not mention alternatives or explicit 'when not to use' scenarios, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it routes over 5,708 tools, fills arguments, returns structured output with stable citation URIs, and works on every tier. It does not add trivial details like latency or rate limits, but the existing disclosure is strong.

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

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

The description is longer than minimal, but it is well-structured and front-loaded with the most important instruction: prefer over web search. Every section serves a purpose: domain list, trigger phrases, examples, default-entry-point guidance, and escalation paths. Slight redundancy and many examples keep it from a perfect 5, but it is not padded or wasteful.

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

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

Given the tool's complexity, the description is remarkably complete: it states the tool's scope, supported domains, trigger phrases, output characteristics, default status, tier availability, and when to choose sibling tools. There is no output schema, but the description sufficiently explains that the result is a structured answer with pipeworx:// citation URIs.

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 every parameter documented as an alias for the natural-language question. The description reinforces this with examples but does not add new parameter-level meaning beyond what the schema already provides. Baseline 3 applies because the schema fully carries parameter documentation.

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

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

The description clearly states a specific verb and resource: it routes natural-language questions to the appropriate one of 5,708 tools across verified sources and returns a structured answer with pipeworx:// citation URIs. It also differentiates itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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: prefer over web search for factual questions, use as the default entry point, and 'step up only when needed' to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad/multi-part questions. It even lists trigger phrases and concrete example questions, leaving little ambiguity about when to invoke this tool.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: that it is fully functional ('Falls back to nothing — this IS a full working router'), that no candidate is currently active, and that results are compared against the stable router.

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 and information-dense, covering purpose, current status, usage, and fallback in compact form. No wasted words, though it is 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?

For a natural-language router with a single required string parameter, the description covers purpose, status, and usage. It references 'same response shape' as ask_pipeworx, making it complete for an agent familiar with that 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 schema already documents the question parameter and all five aliases at 100% coverage. The description adds no specific parameter semantics beyond noting that arguments match ask_pipeworx, which is marginal 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?

States clearly that this is the beta version of ask_pipeworx, a universal router over 5,708 tools. It distinguishes itself from the stable ask_pipeworx by describing its experimental role and current inactive candidate state.

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

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

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing,' naming the stable sibling as the alternative. The experimental context implicitly indicates when not to use it for stable, non-experimental routing.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail beyond that: the exact success return shape, the explicit refusal format with an enumerated refusal_reason list, the guarantee to use only tool-result content, and the one-extra-LLM-call cost. No contradictions with annotations.

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

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

The description is dense but every clause earns its place: it front-loads the core differentiator, specifies the routing, details both success and refusal returns, gives concrete use cases, and closes with a cost tradeoff. The refusal_reason enumeration is useful because 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?

Given there is no output schema, the description fully documents return values, failure modes, and usage context. It also handles the ambiguity between ask_pipeworx and this sibling by explicitly naming both. An agent has everything needed to invoke it correctly and interpret its 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?

The schema covers all parameters at 100%, documenting six aliases of the same `question` parameter. The description adds no parameter-specific semantics beyond 'natural language,' but the schema fully carries that burden, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it is a 'hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It explicitly contrasts with the sibling ask_pipeworx by noting 'Same routing' but grounded extraction, so an agent can distinguish the two without opening the schema.

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 the agent must not invent facts.' It also names the alternative and the condition for preferring it: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost. This fully routes the agent.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds the context that this is a directory/reference tool and enumerates the data returned, but it does not disclose additional behavioral traits such as default behavior when 'pair' is omitted or any rate limits/pagination. That extra context beyond annotations is minimal.

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 tool's purpose and data contents, followed by immediate usage guidance. Every word earns its place with no redundancy or filler.

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

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

The tool is simple with two optional parameters and has an output schema, so return values are covered by structured data. However, the description does not specify how the 'pair' parameter affects results (all pairs vs one), nor does it explain the 'info' parameter values. The schema examples partially fill this, but the description alone is incomplete for a fully informed invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It fails to explain the 'info' and 'pair' parameters explicitly. The only hints come from the schema examples (e.g., info: 'leverage'), which are not part of the description. The description lists output fields but not input parameter meaning, leaving a significant gap.

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 it provides Kraken tradable pair info and lists specific data fields (base/quote, lot decimals, fee schedule, leverage limits, ordermin). It also distinguishes itself from sibling market data tools by positioning it as a directory to use before depth/ticker/ohlc calls.

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 directly instructs to 'Use as a directory before depth/ticker/ohlc calls', offering clear context for when to call it and naming the alternate tools for subsequent data. However, it does not explicitly cover when not to use it or other exclusions, so it falls just short of a 5.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about the data content but does not disclose additional behavioral traits such as rate limits or return behavior. It does not contradict annotations.

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

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

The description is a single, front-loaded sentence that immediately establishes the tool's domain. It is concise with no redundant information.

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

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

With a simple 2-parameter schema and an existing output schema, the description covers the core purpose and content. It lacks usage guidance, but the tool itself is straightforward. The annotations and output schema cover the remaining context.

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

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

Schema description coverage is 0%, so the description must compensate. It provides examples of asset values (BTC, ETH, USDT) and mentions fiat, but does not explain the 'aclass' parameter at all. The schema examples partially fill this gap, but the prose is insufficient for full parameter understanding.

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

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

The description clearly identifies the tool as providing Kraken exchange asset information, listing specific data types (precision, status, alt-name, conversion factor) and asset types (crypto and fiat). This distinguishes it from siblings like asset_pairs, which focus on trading pairs.

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 use when asset metadata is needed, but does not explicitly mention alternatives or when not to use. There is no mention of asset_pairs for trading pair information, leaving the agent to infer context.

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

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

Beyond the readOnly/idempotent hints, the description discloses extensive behavioral traits: parallel fan-out to category-specific data packs, resolver contract with match confidence and alternatives, safety short-circuit when match is low-confidence, handling of closed/dead markets, wide-spread illiquidity warnings, and cancellation-rule parsing with EV impact. These are not predictable from annotations alone and are clearly valuable for safe invocation.

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 (roughly 650 words) but organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). The opening sentence front-loads the core purpose. Every section offers operational detail not available elsewhere, so the length is justified, though tighter editing could have made it more concise.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly specifies the shape of result.market, result.analysis, result.evidence, parent_event fields, news fallback markers, status values for low-confidence/closed markets, and cancellation-rule risk. Edge cases and blocking behavior are clearly documented, making the tool safe to invoke without additional context.

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

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

Schema description coverage is 100% and each parameter already has a detailed explanation (market formats, depth enum, include_raw behavior). The tool description adds contextual examples of fan-out but does not introduce new parameter-level semantics beyond what the schema provides. Hence the 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on single-market deep research rather than cross-market scanning. The addition of classifiers and fan-out examples reinforces the distinct 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?

Explicit when-to guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also describes block conditions such as low-confidence matches and closed markets, which serve as implicit when-not. However, no alternative sibling tool is named for exclusions, so it stops short of a 5.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail beyond annotations: parallel execution, type-specific data sources (10-K financials, FAERS counts), off-calendar fiscal year handling, sorting by primary metric, and citation URIs in results.

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 trigger phrases and the key preference directive. Each sentence provides useful information, though it is longer than strictly necessary; all content earns its place for a tool of this complexity.

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

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

For a tool with no output schema, the description is very complete: it covers entity types, data sources, fiscal-year handling, result ordering, return format, and citation URIs. It gives enough context to invoke the tool correctly and understand what will come back.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaningful semantic depth by explaining what each 'type' value retrieves ('company' pulls latest 10-K revenue/net income/cash/debt; 'drug' pulls FAERS and trial counts), and notes that results are sorted by primary metric, which helps the agent choose values and interpret results.

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

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

The description states a specific verb and resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from siblings by explicitly preferring this tool over sequential single-pack lookups when comparing entities, and notes it replaces 8–15 sequential lookups.

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

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

Usage context is clear with trigger examples ('Compare X and Y', 'head to head') and an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It does not name a specific alternative tool but clearly implies when not to use it (single-entity lookups).

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: it discloses account/auth requirements, latency expectations, parallel decomposition behavior, gaps[] for unanswered facets, contradictions[] on deeper depths, semantic excerpting, and fetchable citation URIs. The annotations (readOnlyHint, idempotentHint, destructiveHint) are fully consistent with this read-only research tool.

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

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

The description is long but densely informative, with the account prerequisite front-loaded. Every sentence contributes actionable detail about behavior, alternatives, or expectations, and the structure flows from access requirements to use cases to depth semantics to return characteristics.

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 covers return packet contents (verbatim evidence, confidence, source, fetched_at, citation_uri), gap behavior, contradiction behavior, timing, and account tiers. An agent has enough context to select the tool, set expectations, 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?

Schema coverage is 100% and both parameters are already described in the schema, so the baseline is 3. The description adds meaningful extra semantics: it explains that depth:'quick' uses a single hop, depth:'standard' adds gap recovery and contradictions, and depth:'thorough' is paid with a lead-chasing hop, plus it clarifies that broad/multi-part questions are acceptable.

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

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

The description states a specific verb and resource: it performs grounded multi-source research across Pipeworx's 1494 structured data sources in one call, decomposing questions into facets and routing them in parallel. It also clearly distinguishes itself from ask_pipeworx and from open-web search, which lets an agent differentiate it from sibling tools without 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 gives when-to-use guidance: best for broad/multi-part structured-data questions; use ask_pipeworx for single lookups, breaking current-news, colloquial topics, or when not signed in. It also explains when to prefer different depth settings, so usage context is thoroughly covered.

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

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

Annotations already declare this a safe, idempotent read operation. The description adds behavioral context about the output structure (bids and asks, per level, live data) that goes beyond the annotations and helps the agent understand what to expect.

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

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

Two sentences with no filler. The description is front-loaded with the key identity ('Kraken crypto exchange order book') and each sentence adds meaningful information about purpose and usage.

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, the rich annotations, and the existence of an output schema, the description covers purpose and usage adequately. The only notable omission is parameter semantics, but that is already penalized separately and does not prevent the agent from understanding the tool's role.

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 0%, and the description does not explain the 'pair' or 'count' parameters. It only mentions 'crypto pair' in passing, leaving the meaning of 'count' (number of levels) undefined. This is a significant gap since the agent must rely solely on the schema's 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 clearly states the tool returns the Kraken order book with bids and asks for a crypto pair, and specifies the data fields (price/volume/timestamp per level). This distinguishes it from sibling tools like ticker, trades, and ohlc, making the purpose unambiguous.

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

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

The phrase 'Use for live depth-of-book on Kraken-listed pairs' provides clear intended usage. It doesn't explicitly exclude alternatives, but the context of sibling tools and the specific focus on order book data implies when this tool is appropriate.

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 useful behavioral context beyond that: it returns 'top-N most relevant tools' with full schemas, and 'each result is ready to call directly, no second schema lookup needed.' It also advises to call it first, which is behavioral guidance. This is more than baseline, though it doesn't discuss latency or rate limits.

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

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

The description is three sentences, each packed with value: a clear purpose statement, a usage/scope sentence with a broad domain list, and a sentence about return format and when to call it first. There is no fluff or repetition. It is front-loaded with the core purpose, making it easy to scan.

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

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

Given there is no output schema, the description explains the return value ('top-N most relevant tools with names, descriptions, and full input schemas'), which is essential. It also covers when to use it. The only minor gap is a lack of detail about the exact structure of each result (e.g., whether it includes an ID or a tool endpoint), but this is not critical for a discovery tool. Overall, it's nearly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'describing the data or task' which aligns with the query parameter, and 'top-N' gives a hint about the limit parameter. However, it doesn't add much beyond what the schema already documents, which includes aliases and example values. The schema does the heavy lifting, so a 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 ('Find tools by describing the data or task') and immediately clarifies its meta-purpose. It lists many domains (SEC filings, FDA drugs, etc.), which both explains its scope and distinguishes it from domain-specific sibling tools. This is not a tautology because it elaborates on the 'discover' concept.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies when not to use it by saying 'not just one answer,' indicating it's for option exploration rather than direct answers. This is clear, actionable guidance with an implicit alternative.

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

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

The description adds rich behavioral context beyond the annotations: it fans out across multiple sources in a parallel call, includes a soft-fail mechanism for the USPTO PatentsView API sunset, and describes a GDELT→GNews fallback for news. It also notes the return fields (up to 5 filings with URIs, latest 10-K fundamentals). This goes well beyond the readOnly/idempotent hints.

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

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

The description is dense but well-organized, starting with user-phrased examples, then core functionality, then output details, and ending with input constraints. Every sentence provides value, though the length is substantial for the complexity. It could be slightly more scannable but earns a 4.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: lists CIK, company_name, filings (with URI count), fundamentals (specific fields), patents, news, and LEI. It also clarifies input requirements and fallback behaviors, making it complete for an agent to decide and invoke.

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

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

Schema description coverage is 100% and already documents the 'type' and 'value' parameters with examples and the name restriction. The description repeats this information without adding new parameter-level details, so it stays at the baseline for full schema coverage.

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

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

The description clearly states the tool's purpose: to provide a full cross-source profile of a US public company in one parallel call. It uses specific verbs ('profile', 'research', 'brief me') and lists concrete outputs (CIK, filings, fundamentals, patents, news, LEI), distinguishing it from sibling tools by explicitly advising to prefer it over chaining single-pack lookups for holistic views.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use it: names are not supported, and points to the alternative (resolve_entity) for names. This clearly delineates usage from sibling tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent. The description adds context about memory and use cases (clearing sensitive data) but does not disclose additional behaviors such as error handling for missing keys or any side effects beyond deletion.

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

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

The description is three concise sentences, front-loaded with the action verb. Each sentence earns its place: the first states the operation, the second gives usage context, and the third points to related tools. No wasted words.

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

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

For a simple single-parameter destructive tool with annotations and no output schema, the description plus schema cover the essentials: what it does, when to use it, and what the parameter means. It omits minor details like behavior for non-existent keys, but this does not hinder invocation for typical use.

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 'key' parameter, which already explains 'Memory key to delete.' The description's 'by key' adds no new semantic detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with 'Delete a previously stored memory by key,' which is a specific verb+resource combination that clearly distinguishes this tool from siblings like remember (store) and recall (retrieve). It leaves no ambiguity about the tool's function.

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

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

The description explicitly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and references pairing with remember and recall. It lacks an explicit 'when not to use' clause, but the positive usage cases and sibling mentions provide clear 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=true and destructiveHint=false, so the safety profile is established. The description adds valuable process context—fetches the page, extracts title/description/key links, emits markdown—and clarifies the output is a single text blob. This goes beyond annotations without contradicting them.

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

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

Four sentences, each earning its place: purpose, process, output format, and use cases. Front-loaded with the primary action, no filler or redundancy.

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

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

Given the simple parameter set and rich annotations, the description covers all essential context: what it does, how it works, what it returns, and when to use it. The output format is clearly stated, and no additional edge-case documentation seems necessary for this tool's complexity.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the baseline is 3. The description does not add additional parameter-specific context beyond what the schema already provides, such as examples or constraints.

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

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

The description opens with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL', clearly distinguishing this tool from siblings. It also names the output format and its placement, leaving no ambiguity about what the tool does.

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

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

The description provides clear usage contexts via 'Useful for:' listing three concrete scenarios (client indexing, personal drafting, competitor auditing). It does not explicitly list exclusions or alternatives, so it misses the full 5 but provides clear contextual guidance.

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

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

Annotations already indicate the operation is read-only, idempotent, and non-destructive. The description adds meaningful context by specifying the caller's scope and listing the exact fields returned, 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?

Two sentences with no redundancy: the first states the action and return fields, the second provides practical usage context. Information is front-loaded and every clause contributes value.

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

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

For a simple read-only list tool with one optional parameter, the description is complete. It provides the return shape, caller scope, and concrete use cases, and the annotations cover safety semantics. No output schema is needed since fields are listed.

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 fully describes the only optional parameter, include_inactive, so the schema carries the semantic weight. The description does not add parameter-specific detail but does clarify the default behavior by referring to 'active' subscriptions.

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

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

The description clearly states the tool lists the caller's active subscriptions, using a specific verb and resource. It also enumerates the returned fields, which distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly says to use it to review current monitoring before adding more subscriptions or to find an id to cancel. This directly maps to the subscribe and unsubscribe sibling tools, providing clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds the list of valid intervals and the exchange context, but does not disclose default behavior (e.g., default interval, number of candles returned, pagination). This is acceptable but not exhaustive given the annotations.

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

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

The description is two short sentences, front-loaded with the main purpose. The interval list is compact and useful, and the use-case sentence is clear. No wasted words.

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

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

The tool has an output schema, so return values need not be described. However, the description lacks parameter semantics for 'pair' and 'since', and does not contrast with sibling market data tools. It covers the core purpose and interval options, but not enough for fully confident invocation without external knowledge.

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 0%, so the description must compensate. It does list all valid intervals, which is helpful, but does not explain the 'pair' format (e.g., XBTUSDT vs BTC/USD) or the 'since' parameter (timestamp semantics, optionality, default). The examples in the schema hint at these, but the description adds no meaning for two of three parameters.

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

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

The description clearly states the tool provides OHLC candles for Kraken crypto exchange pairs. It specifies the resource (Kraken pairs) and the data type (OHLC candles), and distinguishes itself from siblings like ticker, trades, and depth by focusing on charting data.

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 a clear use case: 'Use for charting Kraken pairs.' This implies when to choose this tool, but it does not explicitly mention alternatives or exclusions. A stronger statement like 'for current prices use ticker' would push it to 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?

Goes well beyond the annotations by disclosing the claim_token retrieval mechanism, daily rate limit ('5 per identifier per day'), cost implications ('Free; doesn't count against your tool-call quota'), and the team's reading schedule. No contradiction with annotations exists.

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

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

The description is longer than average but every sentence carries distinct information: purpose, usage triggers, exclusions, naming guidance, token mechanics, rate limits, and cost. It is well-structured and front-loaded with the core purpose, but some redundancy exists between the type enum description and the opening sentence.

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

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

Given the tool has no output schema, the description compensates by explaining the return behavior (claim_token and later read-back) and constraining message length. It covers all parameter semantics, usage boundaries, and operational details, making it fully self-contained for an agent.

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

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

Schema coverage is 100%, but the description adds semantic value beyond the schema: advises describing issues in terms of Pipeworx tools/packs rather than pasting the end-user's prompt, and clarifies the claim_token's purpose and invocation pattern. This meaningfully supplements the parameter definitions.

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 immediately states 'Tell the Pipeworx team something is broken, missing, or needs to exist' and then enumerates specific feedback types (bug, feature, data_gap, praise). This clearly differentiates it from sibling tools like ask_pipeworx or system_status, which serve different purposes.

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

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

Provides explicit 'Use when' scenarios for each feedback type, and an explicit 'ONLY for tools served by this Pipeworx connection' exclusion that redirects users of other MCP servers to file elsewhere. It even offers a heuristic for disambiguation ('Pipeworx tool names are the ones this connection lists').

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds meaningful details: data is self-aggregated from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on the window. These traits are not inferable from the annotations and substantially help the agent understand 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 front-loaded with the core purpose, then gives a structured 'Useful for' list that earns its place by clarifying context, and closes with a concise transparency note. Every sentence adds value; it's appropriately sized for a tool with one optional parameter.

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 is complete: it specifies the return contents (top tools, top packs, total call volume, and the (pack, tool, count) data shape), mentions the caching behavior, and provides enough context for an agent to decide when and how to invoke it.

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

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

The single parameter 'window' has 100% schema description coverage, including its enum values and semantics. The tool description merely repeats the options without adding new meaning, so the baseline of 3 is appropriate.

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

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

The description opens with a specific question ('What other AI agents are calling on Pipeworx right now?') and a clear verb ('Returns') with concrete outputs: top tools, top packs, and total call volume. This clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx.

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

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

The description provides three explicit use cases, which is excellent guidance for when to use this tool. However, it doesn't explicitly state when not to use it or name alternatives, so it falls short of full 'when-not' 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds substantial behavioral specifics: scan modes, semantic anchor with Jaccard similarity threshold, partition placeholder filtering, return shape, and a fill-check against live CLOB depth with a clear discard condition. 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 efficiently organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Opening sentences state purpose and argument modes, and every subsequent sentence adds operational or safety-relevant detail. No filler or redundancy.

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

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

No output schema exists, so the description must explain return values. It does: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers default behavior, conditional null results, and fill-check pricing, making the tool fully usable from the description alone.

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

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

Although the schema already documents both `event` and `topic`, the description adds significant meaning: event mode 'walks child markets, checks date-axis / threshold-axis ordering AND computes the partition_check', while topic mode 'searches related events across the platform, flattens markets, runs the comparator on the union.' It also clarifies that no args triggers trending_scan, enriching the schema beyond its basic descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_edges (edge monitoring) and polymarket_fill_risk (sizing) by naming the exact detection method and output focus.

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 invocation modes: 'Call with NO args for a trending_scan... pass event for... pass topic for...' It recommends event mode for a specific market, contrasts event vs topic with an example pattern, and states when NOT to trade: 'do not trade it' if realizable_edge_pp <= 0. It also points to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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, so the safety profile is known. The description goes far beyond by disclosing internal model families, response structure, diagnostics, slippage assumptions, Kelly capping, caching behavior, and edge-case warnings (e.g., the 24h-move warning). This provides substantial behavioral context beyond annotations.

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

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

The description is a long, dense wall of text with extensive technical detail (Greek letters, percentages, model names, formulas, diagnostics). It is not appropriately sized for a typical tool description and lacks clear segmentation or front-loading beyond the first sentence. While detailed, it would benefit from restructuring and trimming.

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

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

There is no output schema, so the description must explain return values. It does so comprehensively: top-level response structure (by_segment, fed_candidates), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity), and diagnostics (_diagnostics with funnel counters). It also covers caching and knob behavior, making it complete for a high-complexity tool with no output schema.

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

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

Schema coverage is 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds valuable inter-parameter semantics, such as how min_kelly does not apply to partition opportunities while min_partition_leg_kelly does, and explains tradeable-edge knobs (min_liquidity/max_spread_pp). This goes beyond the schema's isolated parameter explanations.

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

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

The description clearly states a specific verb-resource-result: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also explains the built-in intent ('what should I bet on today'). However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it misses the full 5.

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

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

The description provides clear context on when to use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also gives a specific exclusion note (Fed bets excluded from ranking). However, it does not explicitly mention alternatives or when NOT to use the tool, so it lacks the explicit exclusions needed for a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by explaining the detailed response structure (tracked, expired, snapshot_dates), how snapshots are written on cache misses, that gaps mean no scan occurred, and that decay is computed from daily closes not intraday. This is rich additional behavioral context with no contradiction.

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

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

The description is well-structured with clear labeled sections (Args, RESPONSE, LIMITS) and front-loads the main purpose. It is dense and lengthy, but every sentence provides essential information given the tool's complexity and lack of an output schema. It could be slightly more concise but is not wasteful.

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

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

With no output schema and a complex telemetry tool, the description comprehensively covers what the tool does, how to use it, what the response contains (with field-by-field explanation), and important limitations (TTL, snapshot gaps, calculation basis). It even provides an interpretative insight ('the median lifespan is your competition clock'), making the response self-sufficient.

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

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

The input schema already provides 100% coverage for both parameters (days, window) with descriptions including defaults and constraints. The description merely restates these defaults and does not add new semantic meaning beyond calling window a 'snapshot family.' Since schema coverage is high, the baseline is 3 and the description adds little extra.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It specifically answers 'how long has this edge existed and is it shrinking?' which distinguishes it from the sibling polymarket_edges tool that likely provides current edge data, by focusing on historical time-series and decay.

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 strong context on when to use the tool: comparing a fresh wide edge to a 3-week-old one, implying the need for persistence/decay understanding. It also notes limitations (history depth bounded by TTL, snapshot gaps), but does not explicitly name alternative tools or say when NOT to use it, which would make it a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral context beyond these, such as 'walks the ladder', returning specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), interpreting size_usd differently for single-market vs basket, and warning about forced_directional_risk and thin_legs. 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 well-structured with clear SINGLE-MARKET and BASKET sections. Every sentence carries necessary information for a complex two-mode tool, and it is front-loaded with the core purpose. It is slightly dense, but this complexity justifies the length; it could be improved with bullet points but remains appropriately concise.

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

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

There is no output schema, so the description fully enumerates return values (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers all modes, parameter interpretations, and risk warnings, making the tool fully operable without further context.

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

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

Although the schema provides 100% description coverage for parameters, the tool description adds crucial semantic nuances: the distinction between market and event modes, the default side logic for baskets (auto from partition sum), and the meaning of size_usd as 'settlement notional' in basket mode vs 'spend/proceeds' in single-market mode. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from siblings by focusing on fill risk and order-book depth, with explicit single-market and basket modes. This is a specific verb+resource that is not tautological.

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 this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged directional position), giving clear context for alternative usage.

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

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

Annotations already mark this as read-only and non-destructive, and the description goes far beyond them by specifying response fields, compatibility codes, skip behavior for unknown legs, temporal alignment, and count semantics for dropped comparisons. There is no contradiction with the annotations, and the added behavioral detail is substantial.

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

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

Although long, the description is structured into recognizable sections (modes, response, safety fields, codes, counters) and front-loads the core purpose. Nearly every sentence carries distinct information needed to invoke the tool correctly, so the length is justified by the tool's complexity.

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

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

For a tool with no output schema, this description is unusually complete: it explains raw probability returns, matched spread entries, compatibility warnings and codes, unclassified/skipped pairs, temporal alignment, and pre-mapped topic caveats. An agent has enough context to call the tool in either mode and interpret the results safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds mode-level context such as 'auto-fetch' and 'custom pairings', but the schema already names the topic values and states that explicit tickers/slugs override the mapped side, so the description does not add significant parameter-level meaning beyond the schema.

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

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

The opening sentence names the exact operation and resource: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It further distinguishes the tool by explaining the economic signal (participant-pool deltas) and by framing what the tool will and won't do when bet shapes are not equivalent.

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 separates two modes ('topic' shortcuts vs explicit ticker/slug pairings) and says when each applies. It also gives practical caution that pre-mapped topics frequently return compatibility warnings and are not automatically tradeable, although it does not explicitly compare this tool to sibling tools like 'spread' or 'polymarket_arbitrage'.

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 establish read-only, idempotent, and non-destructive behavior. The description adds useful context about scoping (anonymous IP, BYO key hash, or account ID) and the difference between retrieving a single value versus listing all keys, going beyond the structured annotations without contradicting them.

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

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

Three sentences, front-loaded with the core purpose, followed by usage context and relationship to siblings. Every sentence earns its place with no filler or redundancy.

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

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

Given the tool's simplicity—one optional parameter, rich annotations, and no output schema—the description fully covers what an agent needs: behavior, scoping, listing mode, and pairing with remember/forget. No critical gaps.

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

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

Schema coverage is 100% and the key parameter is well-described in the schema ('Memory key to retrieve (omit to list all keys)'). The description reiterates this and adds examples (ticker, address, research notes) but does not add new semantic meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and also covers the list-all-keys variant. It distinguishes itself from sibling tools by explicitly naming remember and forget as its counterparts.

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

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

Clearly states when to use the tool: to look up previously saved context 'without re-deriving it from scratch,' and how to invoke the list mode (omit key). It does not provide explicit when-not or compare against a direct alternative, but the intended context is unambiguous.

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 explicitly describes a state-changing side effect ('Set mark_read:true to flag returned events read so the next call only shows newer ones') and non-idempotent behavior, while annotations declare readOnlyHint true and idempotentHint true. This is a clear contradiction, making the description conflict with the structured metadata.

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, front-loaded with the main purpose, and every sentence adds value (return format, filtering, mark_read behavior, polling guidance). It is slightly longer than necessary but remains concise and readable.

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 explaining the return payload structure ('source, citation_uri, raw event payload'). It also covers filtering, mark_read effects, and polling. It lacks explicit error handling or auth details, but overall is complete for a read-oriented tool of this complexity.

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

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

Schema description coverage is 100% with clear descriptions for all five parameters. The description adds a minor example type ('sec_8k') and reinforces the mark_read behavior, but does not significantly go beyond the schema's 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 what the tool does: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts...'. It specifies the resource (subscription feed alerts) and the action (pull/recent alerts), distinguishing it from siblings like 'recent_changes' by focusing on evaluator-written alerts.

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

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

The description gives clear context for when to use the tool ('Polls work fine') and provides an alternative for scripts/dashboards via the HTTP endpoint, implicitly guiding usage away from this tool for those cases. However, it does not explicitly name other tool alternatives or state when not to use it.

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

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

Beyond the read-only/idempotent annotations, the description discloses multi-source fan-out behavior (SEC EDGAR, GDELT, GNews, USPTO), fallback logic (GDELT→GNews on rate-limit/5xx), and the PatentsView API sunset soft-fail. This is rich, non-obvious behavioral context.

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

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

Five dense, purposeful sentences each add distinct value: usage examples, data sources and fallbacks, since syntax, return structure, and alternative tool. The description is front-loaded with user intent and avoids redundancy.

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

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

Despite lacking an output schema, the description fully covers return structure (changes[], total_changes, citation URIs), source-specific behavior, failure modes, and parameter formats. For a tool with complex orchestration, this is complete and actionable.

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

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

The input schema already fully documents all three parameters with types, examples, and recommended values, so the description adds marginal value. It reinforces the ISO/relative since formats and ticker/CIK value forms, but does not introduce substantially new semantic meaning beyond the schema.

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

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

The description clearly identifies the tool as a 'change feed for a company' over a time window, with explicit examples of natural-language queries. It distinguishes itself from the sibling entity_profile by noting the difference between dynamic changes and static profiles.

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

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

It provides explicit when-to-use guidance with example queries, defines the time-window scope, and names an alternative tool (entity_profile) for static profile needs. This gives the agent clear direction on tool selection.

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

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

The description adds meaningful behavioral context beyond the annotations: data is stored as a key-value pair scoped by identifier, and retention differs for authenticated (persistent) vs anonymous (24 hours). It does not contradict the idempotent or non-destructive hints, and while it doesn't discuss key overwrites, the provided context is sufficient.

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 primary action, and each sentence adds distinct value: what it does, when to use it, and companion tools. No filler or redundancy.

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

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

For a simple two-parameter key-value store with annotations and a fully described schema, the description covers usage context, persistence semantics, and companion tools. Since there is no output schema, no return-value documentation is needed, and the description is complete enough for an agent to 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% with descriptions for both key and value, including example formats. The description reinforces the key-value pair concept and gives content examples, but this does not significantly add beyond what the schema already provides.

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

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

The description states 'Save data the agent will need to reuse later' with a specific verb and resource, clearly distinguishing it from sibling tools recall and forget by framing the action as saving (vs retrieving/deleting). It also gives concrete examples of what to store (ticker, address, preference).

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 'Use when you discover something worth carrying forward' and then explains the persistence behavior (authenticated vs anonymous). It directly names companion tools: 'Pair with recall to retrieve later, forget to delete,' providing clear alternatives and when-to-use guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral detail: the tool cascades through multiple lookups (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), degrades gracefully when external sources are unavailable, and explicitly reports unresolved identifiers under an 'unresolved' field instead of omitting them. No contradictions with annotations.

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

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

The description is relatively long but front-loaded with a concise purpose statement and examples. The structure moves from general usage to type-specific details, making it easy to scan. Every sentence adds value, though some agents might find the detail on graceful degradation and identifier sourcing slightly verbose. Overall well-organized for a complex tool.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, cascading behavior, graceful degradation), the description covers most important aspects. It explains how unresolved identifiers are handled and the fallback behavior. However, it lacks an explicit description of the output schema (e.g., the fields returned for each type), which would improve completeness. Still, the rich detail compensates for the missing output schema.

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

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

Schema coverage is 100% and both parameter descriptions are clear. The description adds extra meaning by explaining that 'value' for company can accept ticker, CIK, ISIN, or name, and for drug accepts brand or generic name. It also reveals that an ISIN resolves to a legal entity via GLEIF, which is not in the schema. This additional context elevates the score above the baseline 3.

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

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

The description starts with concrete user-language examples ('What's the ticker for…') and states the primary action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes from siblings by positioning itself as the first step when you have a name but need an ID, and the detailed breakdown of 'company' and 'drug' types leaves no 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 'Use FIRST whenever you have a name but need an ID.' It provides example queries for both entity types and notes that a single call replaces 2-3 manual lookups, helping the agent understand when to invoke this tool. Although no explicit exclusions are given, the guidance is clear and actionable given the context of sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: it ranks by score, surfaces most/least recognized, and returns specific fields (score, confidence, signal density). It also reveals it internally calls ai_visibility_check, which informs the agent about underlying 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 appropriately concise and front-loaded. It starts with the core purpose in the first sentence, then expands on mechanics and use case without any filler. Each sentence adds distinct value: 'Compare...', 'Probes...', 'Useful for...', 'Returns...' – no redundancy.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description is quite complete. It covers what the tool does, what it returns (ranked list with score, confidence, signal density), and the intended use case. It does not specify error handling or rate limits, but those are not essential for basic invocation. With no output schema, the description serves the return-format explanation well.

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 meaningful semantic detail beyond the schema: it explains that the first entity in the 'entities' array is treated as the 'subject' for narrative while the rest are competitors. It also clarifies the purpose of 'context' (disambiguates common names) and the role of models, which the schema already partially covers, but the extra entity-ordering semantics push it 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 clearly states the tool's function with a specific verb ('Compare') and resource ('AI visibility') across multiple entities. It distinguishes itself from the sibling ai_visibility_check by explicitly mentioning it probes each entity and produces a ranked comparison, not a single-entity check.

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

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

The description gives clear context for use ('competitive AI-marketing audits') with an illustrative example query. It implicitly contrasts with single-entity probing by stating it probes 'your brand + N competitors', but does not explicitly name an alternative tool or state when not to use it. A 5 would require explicit when/when-not guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that it fans out to two services, degrades gracefully on partial failures, and may take 5-30s for first-time bundlephobia measurements. This is valuable behavioral context the annotations do not provide.

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

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

Five sentences, each earning its place. The description front-loads the purpose, then moves to usage, return fields, ecosystem scope, and failure behavior. It is dense but not bloated, with no fluff.

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

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

With no output schema, the description fully specifies the return payload (summary block fields, advisory details, links, alternative versions) and the sources_failed signal. It also covers ecosystem limitation and latency behavior, making the tool's behavior predictable in edge cases.

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 both parameters at 100% coverage. The description adds one meaningful extra: the 'version' parameter defaults to the latest published version when omitted. The scoped-package detail is redundant with the schema but still reinforces the syntax.

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?

Clearly identifies a composite 'should I add this npm package' check, naming both deps.dev and bundlephobia and listing the specific dimensions evaluated. Distinguishes from sibling tools by explicitly limiting to the NPM ecosystem.

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

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

Provides explicit when-to-use guidance by mapping to agent intents like 'is X safe / popular / small' or 'what does adding lodash cost me'. Also gives a clear when-not-to-use by directing non-NPM ecosystems to deps.dev:version directly.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds valuable behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and caps input at 200K chars with truncation flagging. These go well beyond annotations without contradiction.

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

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

The description is information-dense yet well-structured: it opens with the core function, provides use-case rationale, mentions workflow pairing, and ends with technical details. Every sentence earns its place with no fluff.

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

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

There is no output schema, so the description correctly explains return values (top-N passages, character offsets, similarity scores). It also covers input limits, truncation behavior, and embedding details, making it self-contained for an agent to use correctly.

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

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

Schema coverage is 100% and the schema descriptions are already detailed (e.g., text max ~200K chars, query examples). The description adds some context for 'text' (SEC 10-K body, article) but largely echoes the schema. Baseline 3 is appropriate since the schema carries the meaningful semantics.

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

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

The description uses a specific verb and resource ('Semantic search INSIDE a fetched record') and clearly distinguishes from siblings by explaining the workflow with ask_pipeworx_grounded and contrasting with fetching whole documents. Purpose is immediately obvious 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context by specifying the return formats, which helps the agent understand what to expect. It doesn't mention rate limits or authentication, but these are not critical for a simple server-time endpoint, and the annotations cover the safety profile.

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

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

The description is two sentences with no waste. It front-loads the core purpose and then adds the use case. Every word earns its place, and it is appropriately sized for the tool's simplicity.

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 (no parameters, no nested objects), an output schema is present to describe return values, and annotations cover behavioral traits, the description is complete. It provides the essential purpose and usage guidance without superfluous detail.

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

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

The tool has zero parameters, so there is nothing to document. The baseline for no parameters is 4, indicating that the description adequately handles the situation by not pretending to explain non-existent inputs. The schema coverage is 100% (trivially), so no compensation is needed.

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 the Kraken exchange server time in two specific formats (Unix timestamp and RFC 1123 string). It uses a specific verb ('Return') and a distinct resource, making it easy to differentiate from sibling tools like 'ticker' or 'trades'.

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 'Use to synchronize request timestamps,' providing a clear use case. While it doesn't mention alternatives, the tool is uniquely positioned for time synchronization, and the guidance is direct and actionable.

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 the operation safe and read-only. The description adds behavioral detail about the timestamped best-bid/best-ask output, which is useful, but it does not address ordering, limits, or the 'since' parameter.

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

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

Two sentences, no filler, front-loaded with the core purpose and use 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?

For a read-only tool with an output schema and two simple parameters, the description covers the essential purpose and use case. It could be more explicit about the 'since' parameter but is otherwise sufficient.

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

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

Schema properties have no descriptions (0% coverage). The description clarifies 'pair' by context but leaves 'since' entirely unaddressed, requiring inference by the agent.

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

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

The description states a specific verb ('recent bid/ask spread history'), resource ('Kraken crypto exchange pair'), and return value ('timestamped best-bid + best-ask'), clearly distinguishing it from sibling tools like 'depth' and 'ticker'.

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 clear usage context ('Use for liquidity studies'), which gives the agent a sense of when to apply this tool. However, it does not explicitly contrast with alternatives like 'depth' or 'ticker'.

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 (write operation, idempotent), the description discloses authentication requirements, phone verification for SMS, a 10/day SMS cap, and webhook auto-disable/one-time signing secret details. These are valuable behavioral traits not captured by the annotations.

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

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

The description is dense but well-structured: purpose, return value, requirements, supported types with examples, and delivery channels. Every sentence adds operational value without redundancy.

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

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

Given the tool's complexity (multiple subscription types, delivery options), the description covers prerequisites, type-specific params, optional channels with rate limits, and the always-on feed. The return value (subscription id) is stated, and the schema fills in webhook details, so the description is comprehensive.

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

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

The input schema already describes all parameters with 100% coverage, but the description adds concrete examples and semantic meaning (e.g., items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE'). This goes beyond the schema's simple descriptions.

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

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

The description opens with a specific verb+resource ('Create a proactive monitoring subscription to a live-data event stream') and clearly states the return value (new subscription id). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

It includes explicit prerequisites: requires a Pipeworx OAuth account, and anonymous/BYO cannot persist subscriptions. It also provides guidance on supported types and delivery channels, including consuming the feed via recent_alerts or the registry endpoint. It could name sibling tools directly, but the context is sufficient.

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 meaningful behavioral context beyond these: it returns category-bucketed examples, optionally filtered by topic, and explains that each example includes the exact tool plus argument shape from the live catalog. No contradiction with annotations.

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

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

The description is a single dense paragraph that immediately states purpose, enumerates categories, explains output content, and provides invocation guidance. The opening list of natural-language queries is slightly repetitive but serves as useful query patterns. Overall it is efficient and every sentence contributes to usability.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers what the tool returns, how it behaves with and without the topic parameter, and when it should be used. It even notes that results are drawn from a live catalog, giving the agent an accurate mental model.

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

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

The input schema already provides 100% coverage for the sole optional `topic` parameter, including a list of allowed values and the note to omit for a cross-category spread. The description reinforces this with examples like 'finance', 'pharma', and 'betting', but adds little beyond what the schema already states. Baseline score of 3 is appropriate given full schema coverage.

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

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

The description precisely states the tool's role: 'the onboarding entry point for an agent that just connected' and specifies exactly what it returns—'category-bucketed example questions' with 'the exact tool + argument shape' from a live catalog. It clearly distinguishes itself from sibling meta-tools by positioning this as the first tool to use when unfamiliar with Pipeworx.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also clarifies how to invoke with or without the `topic` parameter. However, it does not explicitly state when-not-to-use or name alternatives like discover_tools, so it lacks exhaustive exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond annotations by specifying the exact return contents (status values and timestamp), which is useful behavioral context.

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

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

The description is a single sentence that is front-loaded with the action and resource, and every word earns its place. No fluff or redundancy.

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

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

The tool is extremely simple with zero parameters, an output schema exists, and annotations cover safety. The description fully specifies what is returned (status and timestamp) and the enumerated statuses, making it complete for this simple 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 tool has zero parameters, so the baseline is 4. The description correctly implies no inputs are needed, and there is nothing more to explain about parameters.

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

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

The description clearly states the tool returns the current Kraken exchange operational status with a specific verb ('Return') and resource ('operational status'), and enumerates possible status values. This distinguishes it from sibling tools like server_time and ticker.

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 implicitly clarifies when to use this tool (when needing exchange operational status) but does not explicitly exclude alternatives or provide a when-not-to-use. The context is clear enough given the enumerated status values, so it earns a 4 rather than a 3.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds return field names and the 'live' nature, but doesn't disclose other traits like rate limits, authentication, or error behavior. That's a reasonable disclosure level given the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every clause adds value (usage preference, return fields). There is no redundant repetition of schema or annotation 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 one parameter, a simple output schema, and clear annotations, the description covers what the tool does, when to use it, and what it returns. The inclusion of both named and raw fields is a plus, and the example pair in the schema complements the description well.

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

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

The schema has 0% description coverage for the 'pair' parameter, so the description must compensate. It provides an example ('XBTUSD') and clarifies it's a trading pair, but doesn't fully explain the pair format or potential values. This gives some meaning but leaves room for ambiguity.

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 specifies the tool: a Kraken live ticker for a pair, and explicitly lists the return fields (bid, ask, spread, etc.). It distinguishes itself from sibling tools by indicating it should be preferred for current price and bid/ask queries, making its 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?

Usage context is provided via 'PREFER for current price, bid/ask, BTC spread', which tells the agent when to choose this tool. However, it doesn't explicitly state when not to use it or name alternative tools, so it falls short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the return fields and exchange context, but no deeper behavioral details like rate limits, ordering, or pagination. This adds minimal value beyond the annotations.

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

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

The description is two concise sentences, front-loaded with the core action and return data, followed by a targeted use case. Every word earns its place; no redundancy or fluff.

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

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

Despite having an output schema and annotations, the description fails to explain the parameters count and since, which are essential for correct invocation. The tool's purpose is clear, but operational completeness is lacking for an agent to use it correctly without additional inference.

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 0%, so the description carries the burden for explaining parameters. It only implicitly covers 'pair' via 'a pair' and completely omits 'count' and 'since'. Without these semantics, an agent cannot reliably construct requests with those optional parameters.

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

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

The description clearly states the tool returns 'Kraken crypto exchange recent trade tape for a pair' with specific fields (price, volume, timestamp, buy/sell, market/limit). This is a specific verb+resource combination that distinguishes it from sibling tools like ohlc, depth, and ticker.

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 for tick-level execution analysis,' providing clear context for when to choose this tool. It does not explicitly mention alternatives or exclusions, but the use case is specific and informative enough to guide selection.

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

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

Beyond the annotations, the description reveals important behavioral details: ownership enforcement, soft-delete (deactivation), and that historical events remain accessible via recent_alerts. This aligns with annotations (destructiveHint=false, idempotentHint=true) and adds valuable 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 two sentences, front-loaded with the primary action, and every sentence adds information. No wasted words or repetition of schema details.

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

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

For a simple single-parameter tool with helpful annotations and no output schema, the description fully covers the essentials: operation, prerequisite, side effects, and data retention. It is sufficiently complete.

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

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

Schema coverage is 100% for the single id parameter, and its description already explains it is the subscription uuid from subscribe. The tool description adds no extra parameter semantics (e.g., format or constraints), so the baseline of 3 applies.

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

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

The description starts with 'Cancel a subscription by id,' using a specific verb and resource that clearly distinguishes it from sibling tools like subscribe and list_subscriptions. It states exactly what the tool does without 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 gives clear context about when to use the tool (to cancel your own subscription) and mentions the ownership constraint. It also hints at an alternative (recent_alerts) for historical events, but does not explicitly list exclusions or alternative tools for other use cases.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations by defining the verdict enum, explaining that could_not_verify means the check did not happen and must not be shown as evidence, and distinguishing unsupported from could_not_verify. It also discloses the grounded live-source pipeline, verbatim evidence, and pipeworx:// citation 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 front-loaded with trigger phrases, then efficiently covers routing, output, error semantics, and efficiency gain. Every sentence adds distinct value and nothing feels extraneous 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?

Despite having no output schema, the description fully documents the verdict enum, citation, reasoning, and error cases. It explains routing and use cases, making it self-sufficient for a complex single-call fact-check 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 both claim and tolerance_pct with 100% coverage, including an example and tolerance override semantics. The description adds no parameter-specific meaning beyond what the schema provides, so the high-coverage baseline of 3 applies.

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

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

The description opens with concrete natural-language trigger phrases, then states 'natural-language claim verification against authoritative sources' — a specific verb+resource+scope. It further distinguishes from sibling tools by noting it replaces 4–6 sequential calls and internally routes company-financial vs other claims.

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 whenever the agent needs to check whether something a user said is factually correct,' giving clear when-to-use context. It does not explicitly list exclusions or alternative tools, so it misses the when-not dimension.

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