Jsdelivr

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond these: the default model is Workers AI Llama-3.3-70b (free), passing _apiKey incurs direct cost through Anthropic, and it discloses the return structure (per-model {score, confidence, signals, raw_response} + combined view). This supplements the annotations with cost and model-selection 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 four sentences, each earning its place: core action, default configuration, return format, and use cases. It is front-loaded with the verb 'Probe' and the resource 'LLMs', and contains no redundant phrases or filler. This is a model of conciseness and clear structure.

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

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

Despite having no output schema, the description adequately explains the return values (per-model score/confidence/signals/raw_response + combined view). It also covers purpose, usage context, and behavioral traits. It does not elaborate on how the score is computed or how to interpret 'signals', but given the rich annotations and detailed parameter schema, the description is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

All 4 parameters have descriptions in the schema, giving 100% coverage. The description adds semantics by clarifying the default value for 'models' (workers-ai is default and free) and the cost implication of '_apiKey' ('you pay Anthropic directly'). This goes beyond the schema, which only says the key is optional, without explaining the cost or default behavior.

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

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

The description uses a specific verb+resource pair: 'Probe one or more LLMs' and defines the output as a 0-100 visibility score per model. This clearly distinguishes it from sibling tools like ask_pipeworx (which answers questions) and scan_competitor_ai_presence (which may focus on competitive scanning), by focusing on quantifying AI knowledge about any entity.

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

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

It provides explicit use cases for when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also gives operational context by stating the default model and how to opt into Anthropic with a BYO key and direct cost implications. However, it does not explicitly mention alternative sibling tools or state when not to use it, leaving room for interpretation.

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 useful behavioral context beyond these: it routes to sub-tools, fills arguments, returns citation URIs, works on every tier, and is one fast call. It does not contradict annotations and provides meaningful additional transparency about the tool's operation.

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

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

The description is long and includes extensive examples and repeated guidance (e.g., 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it' are redundant). While the length might be justified for a default entry point, several sentences could be trimmed without losing value. It is front-loaded with the main purpose, but not optimally 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?

Given the tool's complexity (routing among thousands of tools) and the absence of an output schema, the description provides substantial context: what it does, when to use, alternatives, examples, and output type ('structured answer with stable pipeworx:// citation URIs'). It lacks details on error handling or specific return structure, but for a general-purpose query tool, it is fairly 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%: every parameter (aliases) is described as 'Alias for question' and the 'question' property explains natural language input and accepted aliases. The description adds no further parameter-level semantics; it only restates that the question will be routed, which is tool behavior, not parameter meaning. Baseline 3 applies because schema already covers all 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's specific verb and resource: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes itself from siblings by positioning as the default entry point and naming alternative tools (ask_pipeworx_grounded, deep_research). This is a specific, non-tautological purpose.

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

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

The description provides explicit when-to-use guidance: 'Use whenever the user asks "what is", "look up", "find", "get the latest", "how much", "current", or any factual question about real-world entities, events, or numbers.' It also gives when-not-to-use with alternatives: 'for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is detailed and distinguishes from web search.

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 valuable context: it is an experimental router with live candidate improvements when under test, and it currently matches the stable version exactly. It also clarifies it is a full working router, not a fallback, which is important behavioral transparency.

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

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

The description is three sentences, efficiently front-loaded with the primary purpose (beta router). It includes a specific date and status detail that is relevant for understanding current behavior, and while slightly verbose, every sentence earns its place.

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

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

For a single-parameter router with no output schema, the description is sufficiently complete: it explains the tool's identity, current state, relationship to the stable version, and confirms it returns the same response shape. No critical information is missing for an agent to decide to invoke it.

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

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

The schema description coverage is 100%: all six parameters are clearly documented as aliases for the 'question' field. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate given the schema already handles parameter meaning.

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 this is a beta version of ask_pipeworx, acting as an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing the experimental edge, making its purpose specific and differentiated.

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 like ask_pipeworx when wanting the newest routing, and notes that it currently matches ask_pipeworx exactly because no candidate is active. While it doesn't explicitly state when not to use it, the 'newest routing' context implies the stable version may be preferred otherwise, providing clear usage context.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals refusal reasons, the evidence quote, the extra LLM call cost, and that only tool result content is used. 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?

Every sentence earns its place: purpose, mechanism, return/refusal structure, use cases, and cost tradeoff. It is dense but not padded, and the information is front-loaded.

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

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

Despite lacking an output schema, the description fully specifies the success and refusal return shapes with field names and refusal reasons, making the tool's behavior clear. It also covers the tradeoff with the sibling tool.

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

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

Schema description coverage is 100% with all 6 parameters documented as aliases for 'question.' The description adds no new parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' immediately stating a specific purpose. It also distinguishes from sibling tool ask_pipeworx by explaining the extraction-only mechanism and refusal behavior.

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: 'whenever an answer will be quoted, cited, or acted on... must not invent facts.' Also provides an alternative and cost tradeoff: 'prefer ask_pipeworx for casual lookups' and 'Costs one extra LLM call'.

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 (readOnly, openWorld, idempotent) by detailing the resolver contract, safety short-circuiting, market statuses (low_confidence_match, market_closed_or_inactive), cancellation-rule risks, and fan-out behavior. This gives agents deep insight into what the tool does and potential pitfalls.

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 section headings (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and front-loaded with a concise purpose statement. While some redundancy exists, each section contributes specific operational knowledge.

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

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

With no output schema, the description thoroughly explains response shapes (result.market, result.analysis, result.evidence), edge-case statuses, and the resolver contract. It covers safety, closed markets, wide spreads, and resolution rules, making it highly complete for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds examples for market formats and fan-out mappings, but these are contextual illustrations rather than new parameter definitions. The schema already explains market, depth, and include_raw adequately.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' identifying the specific verb (research), resource (Polymarket bet), and mechanism (Pipedworx data). It also lists explicit use cases ('should I bet on X', 'what does the data say about Y') that distinguish it from sibling tools like polymarket_arbitrage.

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

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

Provides explicit usage scenarios ('Use for...') that define when to invoke the tool. It does not explicitly name alternatives or when-not-to-use, but the context is clear and sufficient for an agent to select it appropriately.

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

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

Annotations already set readOnly/idempotent, and the description adds what data is pulled (10-K metrics, FAERS counts), how fiscal year-ends are handled, and that results are sorted by primary metric. This significantly exceeds annotation coverage.

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 packs query examples, data sources, sorting behavior, and return format; however, it is a single long block that could be better structured with separators.

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 dual-purpose nature and no output schema, the description covers data sources, metrics, sorting, and return URIs, making it complete for an AI agent to select 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 covers type (enum) and values (array with min/max); description adds that type='company' pulls SEC EDGAR data and type='drug' pulls FAERS/FDA/trial counts, giving practical meaning to the enum values 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 opens with explicit user intents ('Compare X and Y' / 'X vs Y') and states a clear purpose: side-by-side comparison of 2–5 companies or drugs in one call. It distinguishes from sibling lookups by noting this 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?

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives example query patterns and clarifies that the tool is for comparisons, not deep dives.

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?

Discloses extensive behavioral traits beyond annotations: parallel routing across 5,529 tools, gap[] reporting with 'never invented', citation URI availability conditions, depth-specific hop/contradiction behavior, latency expectations, account/auth requirements, and semantic excerpting. No contradiction with the readOnly/openWorld/idempotent hints.

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

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

Every sentence contributes value, and the most critical caveat (account required) is front-loaded. The description is long but justified by the tool's complexity. However, it is a single dense paragraph without breaks, which slightly hurts scannability.

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

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

With no output schema, the description fully explains return structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], latency, and auth requirements. It leaves little ambiguity for a tool with this complexity and parameter count.

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 descriptions already document both params (100% coverage), but the description enriches them: depth is tied to facet counts and recovery hops (quick=3, standard=5 with gap recovery, thorough=8 with lead-chasing), and question guidance clarifies broad/multi-part decomposition. Adds meaningful context beyond the schema.

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

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

The description clearly states it performs grounded multi-source research across Pipeworx's structured data sources, returning a findings packet with citations. It explicitly differentiates from ask_pipeworx for single lookups and breaking news, making its purpose distinct among siblings.

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

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

Provides explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured-data questions, not for single lookups or current/breaking news. It names the alternative (ask_pipeworx) and even handles the signed-out case, covering exclusions and preconditions.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by detailing what the tool returns (top-N relevant tools with names, descriptions, and full input schemas with curated examples) and that results are immediately callable without further lookups, which goes beyond the annotations.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. It efficiently lists supported domains and clearly explains output and usage guidance, with no redundant or filler content.

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

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

The tool is simple (one required parameter with aliases, no output schema). The description covers input (natural language query), output (matching tools with schemas), and usage context (call first). It also enumerates supported data domains, making the tool's scope explicit and complete for an agent to decide when 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?

Schema description coverage is 100%, so all parameters (query and aliases) are already described. The description adds only a general statement about describing data/task, which largely mirrors the schema's 'Natural language description' explanation. No meaningful new parameter semantics are contributed.

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: 'Find tools by describing the data or task.' It specifies the resource (available tool set), the action (browse/search/discover), and lists covered domains. It also distinguishes itself by explaining it returns ready-to-call tool schemas, setting it apart from sibling tools that perform specific tasks.

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 you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear guidance and a strong recommendation for the tool's role as a discovery layer.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive, openWorld), the description discloses internal behavior: it fans out across multiple sources, returns up to 5 filings, sorts fundamentals, soft-fails for patents API sunset, and uses GDELT→GNews fallback. This is rich context not covered by annotations.

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

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

The description is long but every sentence earns its place given the tool's multi-source complexity. It front-loads with concrete example queries, then gives a clear directive, outlines the return fields, and ends with input format constraints. Well-structured and information-dense.

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

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

Without an output schema, the description fully specifies what is returned: CIK, recent filings with URIs, fundamentals details, patents status, news fallback, and LEI. It also covers edge cases (name unsupported, API sunset) and usage preferences, making the tool's behavior complete and predictable 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% for both parameters, and the schema descriptions already fully explain `type` and `value`, including the ticker/CIK format and the 'names not supported' limitation. The description repeats this information without adding new parameter-level detail, so it stays at the baseline for high 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 with a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from siblings by explicitly preferring it over chaining single-pack SEC/XBRL/news lookups and by noting the resolve_entity alternative for names.

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 with 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and gives an alternative (resolve_entity) for name-only inputs. The opening example queries also signal appropriate 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?

Annotations already disclose destructiveHint=true and idempotentHint=true, so the agent knows this is a destructive but idempotent operation. The description adds the 'clear sensitive data' context, but does not explain behavior for missing keys, return values, or other side effects. The added value 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 concise and well-structured: first sentence states the action, second gives usage scenarios, third mentions related tools. Each sentence earns its place with no filler or repetition. It is front-loaded with the most important information.

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

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

The tool is simple (one parameter, no output schema), so the description covers purpose and usage well. However, because there is no output schema, the description should mention what the tool returns or whether it confirms deletion. It also omits edge-case behavior (e.g., key not found). These gaps prevent higher completeness.

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

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

Schema coverage is 100% with a clear parameter description: 'Memory key to delete.' The tool description only repeats 'by key' and adds no extra meaning, examples, or format details beyond what the schema already provides. This matches the baseline of 3 for high 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 action: 'Delete a previously stored memory by key.' It names the specific resource (memory) and operation (delete by key), and easily distinguishes from sibling tools like 'remember' and 'recall' which store and retrieve memories. The purpose is unambiguous and specific.

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

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

Explicit when-to-use guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions related tools ('Pair with remember and recall') for context. However, it does not explicitly state when not to use the tool or name an alternative for deletion, which prevents a perfect score.

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

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

Annotations already cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the bar is lower. The description adds useful process context: it fetches the page, extracts metadata, and emits a text blob ready for site-root placement. This goes beyond the annotations by explaining how the operation is performed and what the output looks like.

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 plus a 'Useful for' list. The first sentence front-loads the action and object, the second explains the process and output, and the third lists use cases. No wasted words; every sentence earns its place.

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

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

With only two parameters, full schema coverage, and robust annotations, the description adequately covers the tool's behavior and return value (a text blob). It could mention edge cases like invalid URLs or rate limits, but for a read-only, idempotent, open-world tool, the current description is sufficiently complete 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?

The schema description coverage is 100% for both url and max_links (including default/max for max_links). The description itself adds minimal semantics beyond the schema—only reiterating that it works for 'any URL'. Per the rubric, a baseline of 3 is appropriate when the schema carries the 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 uses the specific verb 'Generate' with the resource 'llms.txt file', and details the process (fetches page, extracts title/description/key links, emits standard markdown). This clearly distinguishes it from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on the artifact it produces.

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

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

The 'Useful for' section gives three concrete scenarios: getting a client's site indexed, drafting llms.txt for a project, and auditing how an AI crawler sees a competitor. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat safety traits. It adds context about the exact metrics returned (request count and bandwidth) and acceptable period values, but does not disclose potential limitations like data granularity or default period behavior.

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

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

The description is a single, well-structured sentence that front-loads the core functionality. Every word adds value, with no redundancy or fluff.

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

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

Given the tool's simplicity, the read-only annotations, and the presence of an output schema, the description fully covers what the tool does. Minor gaps like default period or data freshness are not critical for a safe, read-only operation with clear input examples in the 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?

With 0% schema description coverage, the description must clarify parameter meaning. It does explain that owner/repo refer to a GitHub repository and enumerates valid period values, but it does not specify a default period or provide format constraints beyond that. This is a reasonable but partial compensation for the schema 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 clearly states the tool returns JSDelivr CDN request count and bandwidth for files served from a GitHub owner/repo. It includes the verb 'Return' and specifies the resource and metric, distinguishing it from sibling tools like npm_package_stats.

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

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

The description implies usage when the user needs CDN statistics for a GitHub repository and allows specifying a period. It does not explicitly mention alternatives or exclusions, but the unique focus on GitHub repos provides clear context for when to use it.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds valuable context about the data source (jsDelivr's index), scope (one specific version), and the nature of results (CDN-oriented file tree), which goes beyond the annotations without contradicting them.

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

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

The description is concise and front-loaded, leading with the core purpose and then detailing return fields and use case. It avoids redundancy and every sentence adds value.

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

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

With an output schema present and simple parameters, the description adequately covers the tool's operation, including the source and the type of data returned. It does not discuss edge cases or prerequisites, but these are not critical for a straightforward read-only tool.

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

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

Schema coverage for parameters is 50% (only version has a description). The description indirectly clarifies that package_name is the npm package name and mentions 'latest by default', which addresses version semantics. However, it does not fully describe parameter formats or provide examples, leaving some burden on the schema.

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

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

The description clearly states the tool lists the file tree of an npm package version via the jsDelivr Data API, emphasizing the specific data returned (path, size, hash, type). It distinguishes from siblings like list_npm_versions by focusing on file structure rather than version listings.

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

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

The description provides clear context for when to use the tool (to determine what files, entry points, and build outputs a package actually ships), though it does not explicitly name alternative tools or exclusion criteria. This is a minor gap, but the implied use case 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 adds the 'all published versions' scope, which is a behavioral trait beyond the read-only and idempotent annotations. However, it does not disclose any additional behavior such as pagination, sorting, or registry specifics. Annotations already 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 a single, concise sentence that is easy to parse and front-loads the core function without any 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?

Given the simplicity of the tool, the existing annotations, and the presence of an output schema, the description provides sufficient context for basic use. It lacks usage guidance, but the core behavior and parameter are covered.

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?

With 0% schema description coverage, the description only implicitly identifies the parameter as the npm package name via the sentence context. It adds minimal meaning beyond the bare schema, but the single parameter's purpose is inferable.

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 indicates the tool returns all published versions for an npm package, avoiding tautology. It is distinct from sibling tools like list_npm_files or npm_package_stats, but it does not explicitly differentiate itself.

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

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

No guidance is provided on when to use this tool versus alternatives. It simply states the function without any use cases, prerequisites, or 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=true and destructiveHint=false, so the safety profile is known. The description adds value by detailing the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only active subscriptions are listed by default, which complements the schema's include_inactive 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?

The description is two sentences, front-loaded with the core function and return fields, followed by concrete use cases. Every sentence adds value and there is 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 tool with one optional parameter and no output schema, the description is complete: it states the operation, the default scope, the return fields, and when to use it. Nothing essential is missing.

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

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

The schema already covers the single parameter include_inactive with a clear description (default false). The tool description does not add further parameter meaning beyond mentioning 'active' subscriptions, which is implicit. Thus 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: 'List the caller's active subscriptions.' It clearly distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on listing existing subscriptions. The inclusion of return fields further reinforces the purpose.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use context. It does not explicitly name alternatives (subscribe/unsubscribe) but implies their role, so it stops short of a perfect 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=false, so the safety profile is clear. The description adds the JSDelivr context but does not disclose any additional behavioral traits such as rate limits, response aggregation, or data freshness. It provides minimal behavioral insight beyond the resource scope.

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 with no wasted words. It conveys the core purpose immediately and is appropriately sized for a simple 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 simple tool with full schema coverage, rich annotations, and an output schema, the description is mostly complete. However, it lacks any mention of usage context or alternatives, which slightly reduces completeness. Still, the core purpose is clear.

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 both parameters with descriptions covering 100% of the properties, including allowed period values and default. The tool description adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns request counts and bandwidth for an npm package via JSDelivr, using a specific verb ('Request counts') and resource. It distinguishes from sibling tools like list_npm_files or list_npm_versions by focusing on usage metrics.

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 no guidance on when to use this tool versus alternatives such as top_npm_packages or list_npm_versions. It simply states what it does without any explicit usage context or 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 provide no positive safety flags (all false), so the description carries the full burden. It discloses several behavioral traits beyond the schema: filing without an account returns a claim_token that can be used later to read status, the team reads digests daily, it's rate-limited to 5 per identifier per day, and it's free (no quota cost). These details meaningfully shape agent expectations and are not inferable from annotations.

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

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

The description is somewhat long but every sentence earns its place: purpose, use cases, ownership boundary, message guidance, token workflow, team process, rate limit, and quota note. It is front-loaded with the purpose and then provides actionable details in logical order. No redundant or filler content.

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

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

Given 4 parameters (0 required) and no output schema, the description covers all necessary operational context: when to use, what not to file, how to construct the message, how to read a prior report via claim_token, and operational constraints (rate limit, quota, team read cadence). The description even explains the return value concept (claim_token) despite lacking an output schema, making the tool 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 descriptions cover 100% of parameters, so baseline is 3. The description adds extra semantic value by explaining the claim_token workflow: 'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed.' It also reinforces how to construct effective context ('Describe the issue in terms of Pipeworx tools/packs'), which clarifies the intended use of the `context` object.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates exact use cases (bug, feature/data_gap, praise) and distinguishes itself from sibling tools by explicitly limiting scope to 'tools served by this Pipeworx connection,' unlike other MCP servers. This is a clear, differentiated purpose.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This tells agents exactly when to invoke this tool versus alternatives.

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

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

Beyond the annotations, the description discloses data provenance ('derived from CF analytics-engine'), privacy characteristics ('no PII'), output granularity ('pack, tool, count'), and caching behavior ('Cached 5min-1h depending on window'). This informs the user about important behavioral nuances not captured in annotations.

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

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

The description is compact and front-loaded, starting with the core value proposition and answer, followed by use cases and data details. Every sentence earns its place and avoids redundancy or fluff.

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

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

For a simple one-parameter read-only tool, the description covers the purpose, output contents, data source, caching, and use cases. No output schema exists, so the explicit explanation of returns ('top tools, top packs, total call volume') is valuable and sufficient.

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

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

The schema already describes the window parameter with enum values and semantic notes. The description adds the cache-time relationship tied to window selection and reinforces the trade-off between shorter and longer windows, which goes slightly beyond the schema text.

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

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

The description uses a specific verb+resource combination: 'Returns the top tools, top packs, and total call volume over a recent window.' It clearly identifies what the tool does and its output. It distinguishes itself from siblings like discover_tools or top_npm_packages by focusing on aggregate cross-agent usage on 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 explicitly lists three concrete use cases under 'Useful for:', such as discovering hot data sources and confirming canonical tool choices. It does not explicitly name alternatives or exclusions, but the context is clear enough to guide 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?

Although annotations already mark this as read-only, open-world, and idempotent, the description goes far beyond by disclosing internal logic: deviation >3pp triggers a signal, Jaccard similarity threshold of ≥0.30, placeholder fraction >20% returns null, and fill-check pricing against live CLOB depth. It also explains output fields and edge cases, adding substantial context not present in annotations. 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 long but every sentence carries specific, non-redundant information. It is effectively structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. The complexity of the tool justifies the length, and no wasteful prose is present.

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 and lack of an output schema, the description takes on the full burden of explaining response structures (opportunities[], partition_check{}), failure modes (null signal, thin_legs), and actionable advice (when not to trade). It also mentions internal safeguards like skipped_low_similarity and placeholders_filtered, making the tool's behavior fully comprehensible 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?

The schema already provides 100% coverage with brief descriptions, but the tool description enriches both parameters with mode-specific behavior, examples ('fed-decision-may-2026'), and consequences (event walks child markets; topic searches across events). It also explains how these modes differ and what outputs to expect, adding meaning beyond the bare parameter names.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' which clearly specifies the tool's verb, resource, and method. It distinguishes itself from sibling tools like polymarket_edges by its focus on arbitrage via monotonicity and partition-sum logic, and further clarifies three invocation modes (trending_scan, event, topic).

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 guidance is given for all scenarios: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends which mode to use for specific cases and directs users to an alternative tool: 'For custom sizing use polymarket_fill_risk.' It also provides a clear negative directive: 'realizable_edge_pp ≤ 0... do not trade it.'

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

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

Annotations cover read-only/idempotent/non-destructive behavior, but the description adds substantial extra behavioral detail: the 24h-move warning, the caching policy ('Cached 1h at the KV level keyed on all knobs'), why Fed bets are excluded, how tradeable-edge knobs drop opportunities, and the diagnostics structure explaining why segments may be empty. 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 long and dense but front-loaded with the core purpose. It uses clear section-like capitalization and structured lists. However, there is an inconsistency: it claims 'FIVE MODEL FAMILIES' but lists only four (crypto_price, news_momentum, partition_overround, concentrated_longshot). This confuses and the extreme length may hinder quick parsing, though it is organized.

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

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

With no output schema, the description fully carries the burden of explaining return values. It details the top-level response structure (by_segment, fed_candidates, _diagnostics), the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the funnel reasoning for empty segments. It also covers caveats like Fed data unreliability, making it highly complete for a complex tool.

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

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

All 9 parameters have schema descriptions (100% coverage), so the baseline is 3. The description goes beyond by grouping knobs as 'TRADEABLE-EDGE KNOBS', explaining the special interaction of min_partition_leg_kelly with partition arbs (parent-level kelly_fraction_half=0), and noting cache keys vary by knobs. This adds meaningful contextual semantics not present in the schema.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on cross-referencing Pipeworx data for daily bet discovery. The phrase 'Built for "what should I bet on today"' reinforces the purpose.

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

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

It explicitly states the intended use case ('Built for "what should I bet on today"') and value proposition ('discover opportunities without paging hundreds of markets'), providing clear context for when to use. It does not name alternative tools or state explicit exclusions, but the context is strong enough to differentiate from siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: history is bounded by a 60-day snapshot TTL, decay is computed from daily closes, snapshot gaps mean no scan that day, and response semantics include signed edge_pp_net values and trend classification. This goes well beyond annotations 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 long but dense with essential information, structured into clear sections: purpose, args, response format, and limits. Every sentence earns its place, though it could be trimmed slightly without losing meaning, e.g., some response details could be condensed.

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 absence of an output schema, the description fully specifies the return structure: tracked[] with full edge_pp_net time-series, trend/decay fields, expired[] with lifespan_days, and snapshot_dates[] with gap semantics. It also covers data limits (TTL, scan gaps) and computation basis (daily closes), making the tool's behavior complete for an agent.

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

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

Schema description coverage is 100%, so baseline 3 is appropriate. The description restates defaults for days and window and clarifies days as a lookback and window as a snapshot family, but does not add significant semantic meaning beyond the schema's own descriptions (e.g., 'clamp 2-30' is already in the schema).

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry built from daily polymarket_edges snapshots, answering 'how long has this edge existed and is it shrinking?'. This specific verb+resource+scope distinguishes it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description provides strong context on when to use the tool (assessing edge age/decay vs fresh edges) but does not explicitly name alternatives or exclusions. The sentence 'a fresh wide edge and a 3-week-old wide edge are different trades' implies usage, but no direct 'use instead of X' guidance is given.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds complementary detail: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), discloses forced_directional_risk on thin legs, and warns that partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is dense yet logically structured: it opens with purpose, then covers single-market and basket modes in separate sections, and closes with usage guidance. Every sentence carries technical value (e.g., size clamp, per-leg fill detail, thin_legs[]), with no filler words.

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

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

For a tool with no output schema, the description enumerates all key return fields (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd), explains parameter behaviors across modes, and covers practical failure modes. An agent can correctly invoke the tool with zero 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?

Although schema coverage is 100%, the description adds significant mode-dependent semantics: size_usd means 'max spend' in single-market but 'settlement notional' in basket mode; side has an auto default derived from partition sum; market/event are clarified as slug or URL. This goes well beyond the schema's field descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly delineates two modes (single-market and basket) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill feasibility and slippage rather than signal generation.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also names the exact sibling tools as alternatives and explains the rationale (theoretical overround on thin books is not capturable, partial basket fills become unhedged directional 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?

Goes far beyond the readOnlyHint/idempotentHint annotations, detailing response structure, compatibility_warning trigger conditions, temporal_alignment semantics, and skipped_cross_type counters. It also honestly warns that most pre-mapped topics return warnings today, adding significant 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 long but well-structured with clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Each sentence provides substantive detail, though the density might be slightly overwhelming. 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?

With no output schema, the description fully compensates by explaining the response format, leg-by-leg prices, top_spreads_pp, compatibility warning conditions, and temporal alignment. It is comprehensive for a read-only comparison tool.

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

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

Schema has 100% parameter coverage, so baseline is 3. The description adds meaningful interaction semantics: explains the two modes, lists the macro shortcuts, and clarifies that explicit parameters override the topic-mapped side. This raises the score to 4.

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

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

The description immediately states the tool's core function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This is specific and distinguishes it from sibling tools like polymarket_arbitrage by explicitly naming both venues and the spread 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?

Provides clear context including two modes (topic shortcuts vs explicit ticker/slug), and cautions that pre-mapped topics often produce compatibility warnings and are not necessarily tradeable. However, it does not explicitly name alternative tools or state when to use this tool instead of them, so it falls short of a 5.

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

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

The annotations already cover readOnlyHint and destructiveHint, so the bar is lower. The description adds useful behavioral context: the tool is scoped to the agent's identifier (anonymous IP, BYO key hash, or account ID), and it can either retrieve a specific key or list all keys when the key argument is omitted. This goes beyond what annotations provide.

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

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

The description is three sentences with no wasted words. The first sentence states the core action, the second gives a concrete use case, and the third covers scoping and related tools. Each sentence earns its place.

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

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

For a simple tool with one optional parameter and strong annotations, the description is complete. It covers functionality, use case, scoping, and relationships to sibling tools. No output schema is needed because the description and schema adequately convey the two return modes.

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

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

The schema has 100% coverage for the single 'key' parameter, so baseline is 3. The description adds meaning by explicitly explaining that omitting the key lists all saved keys, which the schema only hints at via the example. It also provides concrete examples of what keys might contain (target ticker, address, research notes), enhancing semantic 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 states the tool retrieves a previously saved value or lists all saved keys, using a specific verb ('Retrieve') and resource (values saved via remember). It distinguishes itself from the related remember and forget tools by explicitly pairing with them.

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

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

The description provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the alternatives (remember to save, forget to delete), giving clear context for 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?

The description transparently discloses that setting mark_read:true flags events as read and causes the next call to only show newer events, a side effect not visible in the annotations. It also mentions the persisted feed, providing behavioral context beyond the readOnlyHint, idempotentHint, and destructiveHint 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?

Three sentences, each earning its place: main action, return details, and filtering/alternative endpoint. The description is front-loaded with the tool's purpose and avoids any fluff or repetition.

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

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

With no output schema, the description compensates by listing the fields in each event (source, citation_uri, raw payload). It covers filtering, the optional mark_read behavior, and the direct endpoint alternative, making the tool fully invocable without additional context.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaningful param semantics: an example type ('sec_8k'), clarifies 'since' as an ISO timestamp, and explains the effect of mark_read on future calls. 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 'Pull fired events from your subscription feed' with a specific verb and resource. It distinguishes from sibling tools like recent_changes by focusing on subscription alerts, and details what the returned events contain (source, citation_uri, raw payload).

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

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

It provides clear usage context by noting 'Polls work fine' and offering an alternative endpoint for scripts/dashboards ('the same feed is also at GET registry.pipeworx.io/alerts.json'). This tells the user when to use the tool versus a raw HTTP request, though it doesn't explicitly exclude 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, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is clear. The description adds valuable behavioral context beyond the annotations: the parallel fan-out to SEC EDGAR, GDELT→GNews fallback with specific failure conditions, USPTO soft-fail due to PatentsView API sunset, and the structure of the returned changes[] grouped by source. This far exceeds the baseline set 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 long but well-structured: it opens with user-facing example queries, then states the core function, enumerates data sources and fallback behavior, describes the return format, and closes with the alternative tool. Every sentence adds necessary context for a multi-source tool, though it is denser than strictly necessary. It earns a 4 rather than a 5 due to slight redundancy in repeating example query patterns already implied elsewhere.

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

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

The tool has no output schema, so the description appropriately explains the return structure (structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs). It also covers time-window syntax, data-source details, fallback logic, failure modes (PatentsView sunset), and the alternative tool. This is a complete description for the tool's complexity.

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

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

The input schema already provides 100% coverage with detailed descriptions for all three parameters: type, since, and value. The description repeats the `since` examples ('7d', '30d', '3m', '1y') and value formats (ticker or CIK) but does not add meaning beyond what the schema already specifies. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool provides a change feed for a company within a time window, with concrete example queries ('What's new with X', 'latest on Y') that make the purpose instantly understandable. It also distinguishes itself from the sibling entity_profile by explicitly saying when to use that alternative instead.

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 usage guidance: it provides trigger phrases for when to use this tool, explains the fan-out across sources, and explicitly calls out entity_profile as the alternative for static profiles. This is exactly the kind of when-to-use/when-not-to-use guidance that helps an AI agent select the correct tool.

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

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

The description adds valuable behavioral context beyond the annotations: scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. This addresses lifetime and visibility, which are not inferred from the schema or annotations alone.

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

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

Four sentences, each serving a distinct purpose: purpose, usage trigger, storage mechanics, and pairing with related tools. It is front-loaded and no sentence is wasted.

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

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

The description fully covers the tool's purpose, when to use it, how it stores data, and its relationship to recall/forget. With a simple two-parameter schema and no output schema, this is complete guidance 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?

The input schema already defines both key and value with descriptions, so baseline is 3. The description's mention of 'key-value pair' and examples of values add minimal extra 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 uses a specific verb ('Save') and resource ('data the agent will need to reuse later'), clearly distinguishing it from siblings by mentioning it pairs with recall (retrieve) and forget (delete). Examples like 'resolved ticker' and 'user preference' make the purpose tangible.

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: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names the complementary tools (recall and forget) with their roles, effectively covering when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it cascades through multiple lookup endpoints, labels identifiers with their source, explicitly reports unresolved identifiers under 'unresolved', and degrades gracefully if GLEIF/OpenFIGI are unavailable. This goes well beyond the basic 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 long but not redundant. It includes natural language examples, a clear directive, detailed type-specific explanations, and a note about internal cascading. It is somewhat lengthy but front-loaded with the core purpose and usage guidance. Every sentence adds context, though some examples could be trimmed.

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

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

With no output schema, the description carries the burden of explaining return values. It does so comprehensively for both types: company returns CIK, ticker, company_name, LEI, FIGI, with source labels and unresolved identifiers; drug returns RxCUI, ingredient, brand, and citation. It also covers fallback behavior and the tool's role in replacing multiple manual lookups.

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 elaborates on what each type returns (e.g., CIK, ticker, LEI for company; RxCUI, ingredient, brand for drug) but the input schema already explains accepted value formats and examples. The description adds minimal additional meaning regarding the parameters themselves.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides multiple natural language examples (e.g., 'What's the ticker for…') and distinguishes from siblings like compare_entities and entity_profile by focusing on name-to-ID resolution.

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 guidance is given: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to use, but the description does not mention when not to use or explicitly name alternative tools, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds no additional behavioral details beyond the core operation, but does not contradict annotations. With annotations handling the safety burden, a score of 3 is appropriate.

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 and directly communicates the purpose. Every word contributes value, 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 has an output schema (not shown) that likely explains return values, and annotations cover safety traits. The description is sufficient for a simple resolution task, though it omits edge cases like error conditions. It is complete enough for the tool's apparent complexity.

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

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

Schema coverage is 50%: 'range' has a description but 'package_name' does not. The description adds meaning by explicitly mentioning 'semver range or tag', indicating that the range parameter also accepts tags (e.g., 'latest', 'next'), which is not stated in the schema's 'Semver range' description. This enriches the parameter 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 'Resolve' with a clear resource ('semver range or tag') and outcome ('concrete published version'). It distinguishes itself from sibling tools like list_npm_versions or resolve_entity by focusing on version resolution.

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

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

The description implies when to use the tool (when you need a concrete version from a semver range or tag) but does not explicitly mention alternatives or exclusions. Context is clear, but there is no explicit 'use this instead of X' guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, lowering the disclosure burden. The description adds useful behavior beyond that: it explains the internal mechanism (probing each entity with ai_visibility_check), the ranking step, and the return details (score, confidence, signal density). This gives the agent a clear picture of how the tool executes and 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?

The description is three sentences with clear roles: primary action, mechanism + output, and use case example. It is front-loaded and every sentence earns its place with no redundant or vague phrasing.

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

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

With no output schema, the description compensates by specifying the return format (ranked list with score, confidence, signal density) and the ranking behavior. It also notes the dependency on ai_visibility_check. Combined with the comprehensive schema and safety annotations, this is sufficiently complete for a multi-entity comparison tool.

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

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

Schema description coverage is 100% (all 4 parameters have meaningful descriptions), so the baseline is 3. The description adds only marginal semantics beyond the schema—it restates the concept of 'your brand + N competitors' and mentions the output, but doesn't elaborate on parameter syntax or domain constraints beyond what the schema already covers.

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 'Compare AI visibility across multiple entities side-by-side' – a specific action (compare) on a defined resource (AI visibility) with explicit scope (multiple entities). It further states it probes with ai_visibility_check, ranks by score, and surfaces most/least recognized, which clearly distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 offers a clear use case: 'competitive AI-marketing audits' with an illustrative example question. However, it does not explicitly mention when to avoid this tool (e.g., for a single entity use ai_visibility_check) or name alternatives. The comparative nature is implied, so clear context but no 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses composite multi-source behavior, graceful degradation on partial failures, the potential 5-30s delay for bundlephobia's first measurement, and the sources_failed field. It also details the return structure (summary block, advisories, links, alternative versions), which is not covered by annotations or an output schema.

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

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

The description is dense yet every sentence earns its place: it front-loads the core purpose, then covers use cases, return values, ecosystem limitations, and timeout behavior. No filler words or redundant restatements; it is appropriately sized for the tool's composite complexity.

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

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

Despite having no output schema, the description lists all key return fields (is_latest, license, bundle_kb_gz, dependency_count, etc.) and covers operational nuances (timeout, degradations, ecosystem scope). Given the tool's complexity and the annotations present, the description is fully self-sufficient 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?

Schema coverage is 100% with both parameters described, so the baseline is 3. The description reinforces that 'package' is an npm package and 'version' defaults to latest when omitted, but adds no genuinely new parameter-level semantics 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 opens with 'Composite should I add this npm package to my project' check in ONE call', giving a specific verb (check) and resource (npm package). It clearly distinguishes itself from siblings like npm_package_stats by detailing that it fans out across deps.dev and bundlephobia to produce a holistic assessment.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an explicit alternative for non-NPM ecosystems: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing users to the right tool/approach.

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/trivial annotations, the description discloses key behaviors: returns top-N passages with offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and has a 200K char cap with truncation flagging. This sets clear expectations for output and limitations.

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 with no fluff. It front-loads the core purpose, then details usage, technical mechanics, and a pairing with another tool—all in four sentences. Every sentence contributes distinct 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?

Given the tool has no output schema, the description compensates by stating return values (top-N passages with character offsets and similarity scores). It also covers input constraints (200K cap, truncation) and suggests a workflow with ask_pipeworx_grounded, making it complete for practical 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%, so the baseline is 3. The description adds minor context (e.g., 'text you already pulled', query examples) but does not materially enhance understanding beyond the schema, as the 200K cap and query examples are already in the schema 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: 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K body, article). It distinguishes itself from sibling tools by focusing on searching within user-supplied text, and it explicitly mentions pairing with ask_pipeworx_grounded, showing awareness of its niche.

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: 'Use when the record is too big to cram into the prompt'. It also suggests a complementary workflow with ask_pipeworx_grounded, indicating when this tool is appropriate versus alternatives.

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

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

The description goes far beyond the annotations, disclosing auth requirements, the returned subscription ID, phone verification needs, SMS rate caps, webhook auto-disable after failures, and the one-time signing secret. It does not contradict the annotations (readOnlyHint=false, idempotentHint=true) and adds substantial operational context that an agent needs to invoke the tool correctly.

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, but it is well-structured with a colon-separated list of types and delivery details. Every sentence adds value, though some content overlaps with the schema. It is appropriately sized given the tool's complexity, though a bit long and slightly 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?

The description covers purpose, auth requirements, supported types, delivery channels, return value, webhook mechanics, and rate limits. With no output schema, it still tells the agent what to expect (subscription ID). It is complete enough for an agent to select and invoke this tool correctly, given the complexity of nested parameters and delivery options.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents each parameter with examples and constraints. The description repeats these examples (e.g., items:['5.02'] = officer change) and adds a small clarification for item codes, but adds little beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and lists supported subscription types, leaving no doubt about its function.

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

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

The description provides clear usage context: it states a prerequisite ('Requires a Pipeworx OAuth account'), explains how to consume the feed via recent_alerts or the alerts.json endpoint, and details delivery channel options. It does not explicitly name alternative tools for management, but the context is sufficient for an agent to know when to subscribe versus when to list or unsubscribe.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that results are drawn from a live catalog of thousands of tools, and that omitting topic yields a full spread while passing topic focuses results. This adds useful behavioral context without contradicting annotations.

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

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

The description is longer than average but front-loads example queries and then states the core function, parameter usage, and when to use. Every clause adds value, though a few of the initial examples could be trimmed without losing clarity.

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 one optional parameter and no output schema, the description fully explains return behavior (category-bucketed examples with tool/argument shapes), parameter behavior, and usage context. It is complete enough 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 already fully describes the 'topic' parameter with its enum list. The description adds examples ('finance', 'pharma', 'betting') and clarifies that omitting the parameter gives a cross-category spread, reinforcing schema meaning rather than just repeating it.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. It uses specific verbs like 'returns' and 'Call', and distinguishes itself from sibling meta-tools like ask_pipeworx by being the initial discovery tool.

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 this FIRST when the agent does not know what Pipeworx can do, and mentions it is for learning how to call meta-tools. It does not explicitly state when not to use it, but the FIRST directive and reference to meta-tools 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds little behavioral context beyond identifying JSDelivr as the source; it does not mention data freshness, rate limits, or response structure, but this is acceptable given the annotation coverage.

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, focused sentence with no fluff. It clearly front-loads the core function without any unnecessary words.

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

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

The tool is simple, with all three parameters optional and well-documented in the schema, plus an output schema is present. The description provides essential context (JSDelivr leaderboard) and is complete enough for straightforward use, though it could benefit from an explicit verb or a hint about ordering.

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

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

The schema provides descriptions for 'by' and 'limit' (67% coverage), including allowed values and defaults. The description does not add any parameter details beyond what the schema already offers, so 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 clearly identifies the tool as returning a JSDelivr leaderboard of top-served npm packages. It specifies the resource (npm packages) and the source (JSDelivr), distinguishing it from sibling tools like npm_package_stats or list_npm_versions.

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

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

The description implies usage for retrieving a leaderboard of top npm packages, but it provides no explicit guidance on when to use it versus alternatives. No alternative tools or exclusions are mentioned, so usage context is only implied.

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

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

Beyond annotations, the description discloses that ownership is enforced, the row is deactivated (not deleted), and historical events remain available via recent_alerts. This adds meaningful behavioral context that annotations alone 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?

Three sentences, each contributing distinct information: the action, ownership enforcement, and the deactivation effect. It is front-loaded with the core purpose and contains no filler.

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

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

For a simple one-parameter mutation tool, the description covers the purpose, ownership, soft-delete behavior, and the preservation of historical events. It lacks explicit error handling or return value details, but these are not critical given the low complexity and absence of an output schema.

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

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

Schema description coverage for the single parameter is 100%, and the schema already explains 'id' as the subscription uuid returned by subscribe. The description adds no further semantic detail, 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: 'Cancel a subscription by id.' This clearly distinguishes it from sibling tools like subscribe and list_subscriptions, making the tool's 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 use case is implied by the purpose ('Cancel a subscription'), but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions. The ownership constraint is behavioral rather than usage direction.

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/openWorld, but the description adds crucial semantics beyond that: it explains the difference between could_not_verify (check did not happen, with verification_error{stage,detail}) and unsupported (no source covers it), warns not to present could_not_verify as evidence, and states answers come with verbatim evidence and citations. This is exactly the kind of context agents need.

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: usage triggers, scope, routing, return values, and critical warnings are all present, and no sentence is wasted. For a tool with this complexity, the length is justified and front-loaded with actionable examples.

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

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

With no output schema, the description must explain return values, and it does: verdicts, actual value with citation, reasoning, and the error structure for verification_error. It also covers edge-case semantics that would otherwise be opaque, making the tool safe and self-contained for an agent to call.

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?

Both parameters are fully documented in the schema (100% coverage), so baseline is 3. The description adds extra meaning for tolerance_pct by explaining it overrides the wording-implied tolerance, recommending 1-2 for hallucination detection, and noting the default cap of 5. This guidance goes beyond schema, so a 4 is warranted.

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

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

The description opens with natural-language triggers ('Is it true that…' / 'fact check' / 'verify the claim that…') and states a specific verb+resource: natural-language claim verification against authoritative sources. It also distinguishes the company-financial path from the grounded fallback, making its scope unmistakable and distinct from sibling Q&A 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?

It explicitly states when to use ('Use whenever the agent needs to check whether something a user said is factually correct') and describes internal routing for financial vs. other claims. However, it doesn't list when-not-to-use or name alternative tools, so it stops short of full exclusion guidance.

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