npm

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: the default model (Workers AI Llama-3.3-70b), the BYO Anthropic key with direct cost implication, and the per-model return structure. This is strong additional 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?

Three sentences, front-loaded with the core action, then optional key/cost, then return shape and use cases. No filler; 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?

Despite lacking an output schema, the description explicitly describes the return contract (per-model {score, confidence, signals, raw_response} + combined view), the default model behavior, optional key handling, and representative use cases. This is adequately complete for a 4-parameter tool with strong annotations.

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

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

Schema coverage is 100% and each parameter already has a thorough description. The description adds meaning by noting that the default model is free and that passing `_apiKey` means you pay Anthropic directly, which clarifies real-world implications not 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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly distinguishes this from sibling tools like ask_pipeworx by emphasizing scoring visibility per model rather than general question-answering.

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 supplies clear use contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternative tools or state when not to use it, but the context is specific enough to guide an agent.

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

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

Annotations already mark it readOnly, open-world, and idempotent; the description builds on this by adding routing behavior, argument filling, structured answers with pipeworx:// citation URIs, and speed/tier availability. It doesn't contradict the annotations and gives operational context beyond them.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and structured with examples and escalation guidance. It is somewhat repetitive—'Use whenever', 'START HERE', and 'prefer over web search' restate the same positioning—so it earns a 3 rather than higher.

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 broad routing tool with no output schema, the description supplies domains, trigger phrases, answer format, citations, and sibling escalation rules. The only minor gap is not detailing response fields, but 'structured answer with stable pipeworx:// citation URIs' is sufficient for invocation.

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

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

All six parameters are aliases for 'question' and the schema describes them 100%, so the description doesn't need to add parameter detail. The description reinforces the natural-language question format via examples, but adds no unique parameter semantics beyond 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 uses a concrete verb ('routes', 'returns'), identifies the resource (questions about current/historical data across 5,706 tools/1,493 sources), and explicitly differentiates itself from ask_pipeworx_grounded and deep_research. This tells the agent exactly what ask_pipeworx does and how it differs from 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?

Explicitly states when to prefer it over web search, lists trigger phrases and examples, and names the conditions for escalating to ask_pipeworx_grounded and deep_research. It even clarifies the breaking-news case, leaving little ambiguity about tool selection.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds important operational context: it is experimental, alternates between identical behavior and candidate routing, and currently behaves exactly like ask_pipeworx. This is far beyond what annotations convey and is transparent about the live testing nature.

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 typical but every sentence carries operational value: beta status, exact equivalence, current active-candidate state, usage instruction, and the reassurance that it is a full router. Minor redundancy exists in repeating 'same arguments, same response shape,' but it is not excessive.

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 no-output-schema tool, the description covers the core invocation requirement, current behavior, and relationship to the stable sibling. It does not spell out the response shape, but it explicitly says the shape is identical to ask_pipeworx, which is sufficient for routing purposes. The main gap is not describing the response format independently, but the reference to ask_pipeworx mitigates that.

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

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

Schema coverage is 100%, and the input schema fully documents the `question` parameter plus all aliases. The description does not need to repeat parameter details; it does mention the same arguments as ask_pipeworx, but the schema carries the load, so a baseline 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router over 5,706 tools, with identical arguments and response shape. It also distinguishes it from the stable ask_pipeworx by its experimental routing improvements, so an agent can tell what this tool is for.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and notes that no candidate is currently active so it matches ask_pipeworx exactly. It also clarifies that it is not a fallback stub but a fully working router, which prevents misuse.

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 mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: it returns {answer, evidence, confidence, source, fetched_at, refusal_reason} on success, specifies exact refusal_reason values, states the extraction is limited to the tool result, and notes the extra LLM call. 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?

Although fairly long, every sentence earns its place: purpose, routing behavior, return contract, refusal cases, usage boundaries, and cost tradeoff. The most important differentiator, hallucination resistance, is front-loaded, and the description stays structured without fluff.

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

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

There is no output schema, but the description fully specifies the return shape and refusal reason enums, making the response format predictable. It also covers usage context, limitations, and the relationship to ask_pipeworx. For a read-only, single-required-parameter tool, nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, and the description does not add parameter-specific details. The baseline of 3 is appropriate because the schema already fully documents the question parameter and its aliases; the description's mention of 'fills arguments' is contextually relevant but does not need to repeat schema detail.

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 a specific mode: a hallucination-resistant answer mode that routes through the same tool selection as ask_pipeworx, fetches data, and extracts an answer only from the tool result. It explicitly distinguishes itself from ask_pipeworx by emphasizing grounded evidence and explicit refusals, so an agent can differentiate it from 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?

It gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and names the alternative ask_pipeworx for casual lookups. It also discloses the cost tradeoff (one extra LLM call), which is exactly the kind of decision-relevant information an agent needs to choose between 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?

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It discloses the resolver contract (market_match_confidence, scores, alternatives), safety mechanisms (low-confidence short-circuit, blocking on closed/dead markets), wide-spread illiquidity warnings, news fallback behavior (429 handling), and resolution-rule risk (cancellation/void settlement). This is exemplary behavioral disclosure.

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

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

The description is long but well-structured with uppercase section labels, examples, and a logical flow from purpose to fan-out to response shapes to safety. It front-loads the core purpose and use cases, then adds necessary behavioral detail. While not terse, every section adds value and the structure makes it scannable.

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

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

Despite having no output schema, the description thoroughly explains all relevant response fields: result.market, result.analysis, result.evidence, result.parent_event, news fields, status values, and tradeability warnings. It also covers edge cases like low-confidence matches, closed markets, and cancellation rules. For a complex tool, the description is remarkably complete.

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

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

The input schema has 100% coverage for all three parameters, including descriptions for 'market', 'depth', and 'include_raw'. The description reinforces the market parameter with examples but adds no new semantic detail beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools by stating its use case ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and detailing the fan-out to category-specific data packs. The purpose is unmistakable and unique among the sibling list.

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

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

The description provides explicit when-to-use guidance via the 'Use for...' phrase and numerous examples. However, it does not name specific alternative tools or give when-not-to-use conditions, which prevents a 5. The guidance is still clear and actionable.

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

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

Annotations already declare read-only/idempotent behavior, but the description adds substantial context: it discloses data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years correctly, states results are sorted by primary metric, and mentions return of paired data with citation URIs. This goes well 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 dense and well-structured, front-loaded with trigger phrases and the key 'ALWAYS PREFER' guidance. While every sentence adds value, it is longer than strictly necessary, and the 'Replaces 8–15 sequential lookups' is a value prop rather than essential behavioral info.

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

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

Given no output schema, the description adequately explains the return structure ('paired data + pipeworx:// citation URIs'), sorting behavior, and the types of data retrieved for each entity type. It also covers quirks (off-calendar fiscal years) and performance benefits, making it complete for selection and invocation.

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

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

Even with 100% schema coverage, the description enriches both parameters: it explains what 'type=company' vs 'type=drug' means in terms of data fields, and gives concrete examples for the 'values' array (tickers/CIKs, drug names). This adds 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 opens with concrete user query patterns ("Compare X and Y", "X vs Y", "which is bigger") and clearly states the tool performs side-by-side comparison of 2–5 entities. It distinguishes itself from sibling tools by explicitly preferring it over 'sequential single-pack 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?

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear when-to-use directive and an alternative to avoid. It also details exactly what each entity type (company vs drug) pulls, guiding usage.

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

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

Despite readOnly/idempotent/non-destructive annotations, the description adds substantial behavioral context: output packet structure, explicit gaps[], never-invented behavior, semantically excerpted excerpts, latency expectations, citation_uri fetchability guarantees, hop fields, and depth-specific contradiction scans. This goes well beyond what the annotations convey.

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

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

The description is long but every sentence earns its place. It front-loads the account requirement, then moves through core behavior, alternatives, depth semantics, return-value guarantees, and latency, with no filler or redundancy.

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

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

There is no output schema, so the description carries the full burden of explaining the return value. It covers findings packet contents, gaps[], contradictions[], hop field, citation_uri resolvability, latency, and authentication/tier constraints, making it fully complete for a complex research tool.

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

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

Schema coverage is already 100%, but the description meaningfully enriches both parameters: it explains that 'question' can be broad/multi-part because decomposition is the point, and it details how each depth value changes the research hops, gap recovery, and contradiction scanning 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 states a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources in one call, with decomposition and parallel routing. It also explicitly distinguishes itself from open-web search and from ask_pipeworx, making its scope unmistakable.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and clearly says to use ask_pipeworx for single lookups and breaking/colloquial current-news topics. It also states the authentication prerequisite and tells signed-out users to use ask_pipeworx instead.

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, and non-destructive. The description adds valuable behavioral detail: it returns top-N tools with names, descriptions, and full schemas, and is ready to call directly without a second schema lookup. This describes output format and efficiency 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 well-structured and front-loaded with purpose. The list of data domains is long but informative, showing the scope of discoverable topics. Every sentence contributes; the trade-off between length and utility is acceptable.

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

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

With no output schema, the description compensates by explaining return contents and direct-callability. It covers what it returns (names, descriptions, schemas), the limit behavior, and mentions curated examples. Combined with annotations for safety, this is fairly complete for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'top-N' which hints at the limit parameter, but the query semantics are already fully described in the schema (natural language description, aliases). No additional parameter meaning is added 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 starts with a specific verb+resource pairing: 'Find tools by describing the data or task.' It clearly distinguishes itself from siblings by positioning as a meta-tool for discovery ('Call this FIRST when you have many tools available'), not as a direct data/research tool like deep_research or search_packages.

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 context is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST... not just one answer.' This gives clear when-to-use, though it does not explicitly name alternative tools or state when not to use it beyond the 'not just one answer' qualifier.

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

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

Beyond the readOnly/idempotent annotations, the description discloses valuable behavioral details: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specific return fields; the USPTO API sunset 'soft-fails until reactivated'; and the GDELT→GNews fallback. 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 information-dense, front-loaded with query examples, and every clause adds value. However, it is a long single paragraph with many nested clauses; while justified by the tool's complexity, it could benefit from structured bullets. Not maximal conciseness, but not wasteful.

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

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

With no output schema, the description carries full burden of explaining return values, and it does so thoroughly: cik/company_name, recent_filings (up to 5 with URIs), fundamentals (specific fields and sorting), patents, news fallback, LEI. It also covers limitations and input constraints, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% and the schema already documents the type enum and value format with examples and constraints. The description repeats the ticker/CIK requirement and name limitation but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company' with specific verb 'profile' and resource. It provides multiple example query forms and distinguishes itself from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' This is a specific, 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?

Explicitly states when to use: 'when the user asks for a holistic view' and directs preference over chaining single-pack lookups. It also gives an exclusion: 'names not supported (use resolve_entity first),' clearly guiding the agent to an alternative. Strong usage guidance.

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

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

Annotations already declare destructiveHint and idempotentHint; description adds context by identifying the resource ('previously stored memory') and use case ('clear sensitive data'). No contradictory or missing critical behavioral info beyond annotations.

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

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

Two sentences, action first, then usage guidance and sibling references. 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?

Tool has only one parameter, no output schema, and annotations cover destructive/idempotent behavior. Description gives purpose, when-to-use, and sibling pairing — sufficient for a simple tool.

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

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

Schema description covers 100% of the parameter ('Memory key to delete'). The description adds no additional parameter details beyond saying 'by key', so baseline 3 applies.

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

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

Description states 'Delete a previously stored memory by key' — a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by implying store/retrieve vs delete.

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: 'when context is stale, the task is done, or you want to clear sensitive data' and suggests pairing with 'remember' and 'recall'.

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 openWorldHint=true, but the description adds specifics: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a 'single text blob ready to drop at site-root/llms.txt'. This 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 two sentences, front-loaded with the core action and output, followed by a concise 'Useful for' list. Every sentence earns its place with no wasted words 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 tool with two parameters and no output schema, the description sufficiently explains the output format and use cases. It lacks detail on edge cases like handling of inaccessible URLs or JavaScript-heavy sites, but given the simplicity, it is largely complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'any URL' and 'key links' which loosely relates to 'url' and 'max_links', but does not add meaningful parameter 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 clearly states it 'Generate a production-ready llms.txt file for any URL' with specific verb and resource. It distinguishes itself from siblings by focusing on creating the llms.txt file, not just auditing or checking AI presence.

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

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

The 'Useful for' section provides explicit use cases: indexing a client's site, drafting llms.txt for a project, or auditing competitor AI crawler view. It gives clear context for when to use the tool, though it does not explicitly name alternative tools 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?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the safety profile is known. The description adds behavioral context by specifying the return values (total downloads, start date, end date) and accepted period formats, though it also introduces 'last-year' which is not present in the schema, creating a minor ambiguity.

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

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

Two sentences, front-loaded with the action and object. Every word earns its place, includes examples, and is easy to scan.

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

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

Given the simple read-only nature and presence of an output schema, the description is mostly complete. It covers return values and period formats. However, the 'last-year' discrepancy with the schema and lack of mention of the default period (which the schema does state) slightly reduces 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 description coverage is 100%, so the baseline is 3. The description largely repeats the schema's period list and adds 'last-year' which is not in the schema, potentially confusing. No significant new semantic meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Fetch') and resource ('npm download counts for a package') and clarifies scope with period types. This clearly distinguishes it from siblings like get_package or get_version_info which deal with other package data.

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

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

The description implies usage when you need npm download counts, but it does not explicitly state when to use this versus alternatives, nor does it mention any exclusions or alternative tools. The purpose is clear enough that an agent can infer, but explicit guidance is absent.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description need not restate that. It adds the set of returned fields, which gives some context about behavior, but does not disclose potential edge cases (e.g., behavior for non-existent packages) or limitations beyond the schema's note about exact name. This is adequate but not richly transparent.

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

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

The description is two sentences: the first states the tool's action and output fields, the second gives usage positioning. It is front-loaded and every sentence earns its place. No redundancy or filler.

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

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

For a simple tool with one well-documented parameter, strong annotations, and an output schema, the description provides the necessary context: what the tool does, which fields to expect, and when to use it. There are no critical gaps that would prevent correct invocation.

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

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

The sole parameter 'name' is fully described in the schema with an exact example and clarification ('Exact package name'). Schema coverage is 100%, so the description does not need to add parameter details. The description's mention of 'specific package' aligns with the schema but adds no new semantics.

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

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

The description clearly states the tool's purpose: 'Get full details for a specific package' and enumerates the exact fields returned (version, description, dependencies, homepage, repository, license). It distinguishes from sibling tools like search_packages and list_versions by focusing on a single package's detailed metadata and explicitly referencing the search-then-evaluate workflow.

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 usage guidance: 'Use after search_packages to evaluate a candidate package.' This tells the agent when to use this tool in a multi-step workflow, implying that it is not for discovery or broad queries. It clearly positions the tool relative to an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by enumerating the specific metadata fields returned (e.g., integrity hash, unpacked size, deprecation notice) and explaining version resolution semantics (exact version, dist-tag, or omit for latest). 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 compact and front-loaded: the first sentence states the purpose and output fields, the second sentence provides usage guidance and version syntax. Every sentence is informative, with no filler or redundancy.

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

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

For a simple read-only tool with two parameters and no output schema, the description is highly complete. It covers what the tool returns, common use cases, and version format options. The annotations cover safety/behavioral traits, and the sibling context shows clear differentiation from similar npm tools.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description largely repeats the version parameter semantics already present in the schema, adding only the contextual phrase about "dependencies of <pkg>@<version>". This provides marginal value beyond the schema but does not meaningfully compensate for any 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's purpose: obtaining metadata for a specific version or dist-tag of an npm package, listing the exact fields returned (dependencies, engines, license, tarball hash, etc.). It distinguishes itself from siblings like get_package and list_versions by focusing on a specific version rather than a package's general info or available 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 provides explicit use cases: "dependencies of <pkg>@<version>", pinned-version audits, and inspecting a particular release. It does not explicitly name alternative tools or state when not to use it, but the use cases are clear and contextualized within the sibling tool set.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the default filtering of inactive subscriptions and specifies the return fields, which is useful context beyond annotations since no output schema exists. However, it does not mention pagination or potential large result sizes.

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

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

Two sentences with no filler. The first sentence states the action and output; the second provides actionable use cases. Every word earns its place, and the structure is front-loaded with the core purpose.

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 list tool with one optional parameter, the description is complete: it names the tool's function, lists the return fields to compensate for the missing output schema, and gives usage context. Combined with strong annotations, this is sufficient 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 covers 100% of the parameters with a clear description for include_inactive. The description does not need to repeat this, and the active-subscription context already hints at the default behavior. The baseline of 3 is appropriate because the schema handles the semantic burden.

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

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

The description uses a specific verb 'List' and a clear resource 'the caller's active subscriptions'. It distinguishes itself from siblings like subscribe/unsubscribe by focusing on enumeration rather than creation or cancellation, and it explicitly lists the returned fields.

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

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

Explicit guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to use this tool versus adding or removing subscriptions, covering both pre-add and pre-cancel scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral details beyond annotations: versions are returned newest-first, and it includes package created/last-modified timestamps, which is not present in the schema or annotations.

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

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

The description is two sentences, front-loaded with the core action, and uses a parenthetical to list user questions without bloat. Every sentence contributes meaning, and there is no redundant restating of the tool name or schema.

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

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

For a simple 2-parameter tool with strong annotations and 100% schema coverage, the description is fully adequate. It explains what the tool returns, the ordering, and its intended use cases. No output schema is present, but the description already mentions the key output elements (versions, dates, dist-tags, deprecation notices, timestamps), so nothing 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 input schema has 100% description coverage: name is described as an exact package name with examples, and limit has a clear default and max. The description adds no further parameter semantics, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource ('List published versions of an npm package') and clearly states the delivered fields (publish dates, dist-tags, deprecation notices). It also names the exact user questions it answers, which effectively distinguishes it from siblings like get_version_info or get_package.

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

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

The description gives clear usage context by listing the questions the tool answers ('what versions exist', 'when was last published', 'is latest deprecated'). It does not explicitly name alternative tools or when not to use it, but the provided use cases are 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 are all false (not read-only, not destructive), but the description adds critical context: rate limit of 5 per identifier per day, no quota count, and the claim_token mechanism for tracking feedback without an account. It also discloses how to later retrieve fix status with the token, going well beyond structured fields.

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 every sentence adds needed detail (scope, token, rate limit, roadmap). It is front-loaded with purpose and uses clear punctuation. Slightly long but justified given the tool's complexity.

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

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

Despite no output schema, the description explains the expected return (claim_token) and the workflow for submitting and following up. Together with 100% schema coverage, this is fully sufficient for correct invocation.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by giving a concrete usage pattern for claim_token ('pipeworx_feedback({claim_token:"pwfb_…"})') and instructing to describe issues in terms of tools/packs, not paste user prompts. This supplements 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist', using a specific verb and resource. It explicitly differentiates from sibling tools by scoping feedback to Pipeworx connection tools only, and the title 'Send Pipeworx Feedback' 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?

Provides explicit triggers: bug, feature/data_gap, praise. Also includes an exclusion: 'if the tool came from a different MCP server... file it with that server instead' and a heuristic ('Pipeworx tool names are the ones this connection lists'). This is exemplary when-to-use guidance.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count).' It also discloses caching behavior ('Cached 5min-1h depending on window'), which is useful for freshness expectations.

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, with a lead sentence for purpose, a returns statement, a numbered list of use cases, and two sentences on data origin/privacy and caching. Every sentence provides distinct value with 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?

For a simple one-parameter read-only tool with no output schema, the description covers the return shape ('top tools, top packs, total call volume', '(pack, tool, count)'), the time windows, use cases, data source, privacy, and caching. This is sufficiently complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with the single 'window' parameter fully described in the schema (enum values and semantics). The description reiterates the window options but adds no new parameter meaning beyond the schema. 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's function with a specific verb and resource: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume.' This distinguishes it from sibling tools like ask_pipeworx or discover_tools, which handle queries or discovery rather than aggregate trending signals.

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

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

The description provides explicit use cases: 'discovering what data sources are hot for current events', 'confirming a popular tool is the canonical choice', and 'seeing whether your use case aligns with what most agents need.' It lacks explicit exclusion or alternative tool references, so it does not fully meet the 'when-not/alternatives' bar, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavior beyond that: partition-sum deviations >3pp emit signals, placeholders like 'will-person-X' are filtered, Jaccard similarity ≥0.30 prevents bad cross-event pairing, and fill checks price against live CLOB depth. It even discloses failure modes like skipped_low_similarity and thin_legs[]. No contradiction with annotations.

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

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

The description is quite long, but it is structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every segment adds a necessary constraint or behavior. It is front-loaded with the core purpose, but the length is still substantial for a tool with only two parameters. A 4 reflects that it earns its length yet could be tightened.

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 the absence of an output schema, the description is remarkably complete: it covers input modes, expected output shape (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check fields), edge cases (placeholder slu, threshold limits), and how to follow up with polymarket_fill_risk. The agent has enough to invoke and interpret results correctly.

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

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

Schema coverage is 100% (both event and topic are documented), but the description goes far beyond the schema with concrete slug examples ('fed-decision-may-2026'), mode-specific semantics (event walks child markets, topic flattens related events), and how the two modes differ. It also explains what happens in each mode (partition_check in event mode, cross-event comparator in topic mode), adding meaning that the bare schema lacks.

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' — a specific verb+resource+mechanism. It clearly distinguishes from sibling tools like polymarket_edges by naming the unique detection method, so an agent can immediately understand this is the arbitrage-detection 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?

Explicit when-to-use guidance is provided: 'event (recommended for a specific market)' versus 'topic (for cross-event scanning)', with a concrete example of what each mode covers. It also points to an alternative tool ('For custom sizing use polymarket_fill_risk') and warns when not to trade ('realizable_edge_pp ≤ 0 … do not trade it'). This gives clear decision rules beyond generic 'use for arbitrage'.

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

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

Beyond the readOnly/idempotent annotations, the description discloses significant behavioral details: 'Cached 1h at the KV level keyed on all knobs,' diagnostics like '_diagnostics{concentrated_longshot:{...funnel counters},category_counts,filter_skips},' and a '24h-move warning' when the market move exceeds the edge. It also reveals that Fed bets are excluded from ranking due to unreliable signals, which is non-obvious and valuable for the agent.

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 lengthy and dense, but it is well-structured: it starts with the purpose, categorizes model families, describes the response structure, then details knobs and diagnostics. Given the absence of an output schema, explaining the response segments and fields is necessary. While some details like specific α values (tennis 1.02) could be trimmed, the overall organization earns a 4 rather than a 3.

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 the return values, and it does: 'RESPONSE TOP-LEVEL: by_segment{model_driven,structural_arbitrage,concentrated_longshot}, fed_candidates/fed_note ... and _diagnostics.' It also covers edge fields (edge_pp_net, kelly_fraction, market.liquidity) and behavior (caching, warnings, filters), making it complete for a complex tool with nine parameters.

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 has 100% coverage with descriptions, so the baseline is 3. The tool description adds value by explaining the purpose and interaction of knobs, e.g., 'Tradeable-edge filter. Set to 5000 to drop thin-book opportunities where executing the edge would walk the book past breakeven' for min_liquidity, and clarifying that min_partition_leg_kelly 'applies to the per-leg Kelly inside top_legs instead' of the parent level. This contextual guidance 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 states a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly defines the tool's purpose and differentiates it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreement. The phrase 'Built for "what should I bet on today"' further clarifies the intended use.

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: 'agents discover opportunities without paging hundreds of markets.' It explains when to use the tool (for discovering betting opportunities) and gives guidance on adjusting knobs (e.g., 'Set to 2 to require tight books'). However, it does not explicitly compare to alternative tools or state when not to use it, so it stops short of a 5.

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

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

Adds substantial behavioral detail beyond annotations: 60-day snapshot TTL, history starts when snapshotting was enabled, snapshots written only on cache-miss (gaps = no scan), decay computed from daily closes not intraday, and signed edge_pp_net (negative = SELL YES). Annotations are readOnly/openWorld/idempotent and the description complements them without contradiction.

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

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

The description is long, but every paragraph earns its place: purpose, args, response fields with meanings, and limitations are clearly sectioned (Args, RESPONSE, LIMITS). Front-loaded with the core purpose, no filler, and the structure improves scannability without losing precision.

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

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

For a read-only telemetry tool with no output schema, the description fully explains the return structures (tracked, expired, snapshot_dates), their semantics, and edge cases like gaps, TTL, and sign conventions. Parameter coverage is complete via schema, making the tool ready for correct invocation and result interpretation.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by introducing 'snapshot family' semantics for window and clarifying days as lookback with a max of 30. It also ties window into the RESPONSE structure, adding context the schema alone does not provide.

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

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

States specific verb+resource: 'Edge persistence and decay telemetry' and answers the concrete question 'how long has this edge existed and is it shrinking?'. Clearly distinguishes from sibling 'polymarket_edges' by focusing on time-series persistence rather than current edge detection.

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?

Implies when to use via the example that a fresh wide edge and a 3-week-old wide edge are different trades, and mentions the 'competition clock' of median lifespan. However, it does not explicitly name alternatives or exclusion criteria, though the niche is clear from the purpose and the sibling list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: it walks the order-book ladder, interprets size_usd differently per mode, returns specific metrics (top_of_book, vwap_fill_price, capture_ratio, etc.), and names forced_directional_risk as a specific output. 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?

Although long, the description is tightly packed and front-loaded with the core purpose. It uses clear mode separators (SINGLE-MARKET / BASKET), every sentence earns its place, and it avoids redundant phrasing. The detail is justified by the tool's two-mode complexity and absence of an output schema.

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

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

With no output schema, the description fully enumerates return fields for both modes, explains the risk model, and provides usage context. It lists all relevant outputs (e.g., verdict, thin_legs[], max_clean_notional_usd) and addresses failure modes (partial fills, stranded positions). For a complex tool, this is exemplary 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%, but the description adds significant meaning: it explains side auto mode ('auto — sell if partition sum > 1, buy if < 1'), interprets size_usd as 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional S (shares per leg; each share pays $1)' for basket mode, and clarifies the clamp range. This goes well beyond the schema's basic descriptions.

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

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

The first sentence clearly states a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by explicitly positioning it as a pre-trade risk check before executing those strategies.

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 direction is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the why (partial basket fills create unhedged directional risk) and distinguishes single-market vs basket modes, including input requirements and default behaviors.

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/non-destructive, and the description adds extensive behavior beyond that: compatibility_warning and compatibility_codes can be non-empty even with matches, unclassified legs are never paired, skipped_cross_type/cross_subtype counters exist, and topic-mode matches are keyword-based rather than source-backed. It clearly discloses the tool's limitations and safety semantics.

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?

Long, but every sentence carries a distinct piece of operational or safety-critical information. It is front-loaded with the core purpose, then modes, then response shape, then safety fields and codes. No filler or tautological phrasing; the density is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so in detail: per-venue prices, `top_spreads_pp`, compatibility codes, low-confidence pairs, temporal alignment, and skipped counters. An agent has enough information to invoke the tool and interpret its result correctly in both 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?

Input schema coverage is 100% and each parameter already has a description. The description adds meaningful context by enumerating the 10 topic shortcuts, explaining that `topic` auto-fetches matching events on both venues, and clarifying that explicit parameters override the mapped side. This goes beyond the schema without being redundant.

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

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

States a specific, non-trivial function: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It also distinguishes itself from the many Polymarket-only siblings by making the cross-venue nature and the two operating modes explicit.

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

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

The description clearly explains when each mode applies: pre-mapped `topic` shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug` pairings. It also warns that pre-mapped does not imply tradeable and that most topics currently return compatibility warnings, which is useful usage guidance. It does not explicitly compare against sibling tools like polymarket_arbitrage, but the in-tool mode selection is strong.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds scoping to agent identifier (anonymous IP, BYO key hash, account ID) and the behavior of listing all keys when argument omitted. 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?

Three sentences, front-loaded with the core action; each sentence adds necessary context (usage, scoping, pairing with siblings).

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?

Tool is simple, output schema absent but not needed; description covers core behavior, scoping, and relationship to siblings, sufficient for an agent to invoke correctly.

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

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

Schema documents the single key parameter with 100% coverage, including the omit-to-list-all behavior. Description adds no further parameter detail beyond what schema provides, so baseline 3.

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

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

The description states a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and explicitly contrasts with sibling tools (remember, forget), making it clearly distinct.

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

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

Clearly states when to use (look up context stored earlier) and explicitly names alternatives (remember to save, forget to delete), plus contrasts with re-deriving from scratch.

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 state readOnlyHint: true, implying no state changes, but the description explicitly describes a mutating behavior: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the read-only annotation, making the tool's side effects unclear and potentially misleading for agents relying on the read-only hint.

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 of dense, relevant information: purpose, return contents, filtering, mark_read behavior, polling suitability, and an alternative REST endpoint. No wasted words, front-loaded with the action verb, and every sentence contributes to understanding the 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?

For a tool with 5 optional parameters and no output schema, the description covers the key behaviors: return fields, filtering, mark_read side effect, and polling. It lacks details on pagination and handling of unread_only, but the schema covers these. The main completeness gap is the unresolved contradiction regarding read-only vs. read-write behavior, which affects trust in the description.

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

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

The schema covers all 5 parameters with descriptions (100% coverage), so baseline is 3. The description adds valuable semantics beyond the schema: provides an example type ('sec_8k'), clarifies that 'since' uses an ISO timestamp, and explains the state-changing effect of mark_read. This extra context helps the agent select and use parameters correctly.

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: 'Pull fired events from your subscription feed.' It specifies the return content (source, citation_uri, raw event payload) and differentiates from sibling tools like list_subscriptions and subscribe by focusing on retrieving alert events rather than managing subscriptions.

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

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

The description provides clear usage context: filtering by type and since, using mark_read, and confirming that polling works. It also offers an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly state when to prefer this tool over sibling tools for alert-related tasks, though the name and description make this self-evident.

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

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

Annotations already mark the tool as read-only and idempotent, but the description goes far beyond: it reveals fan-out to SEC EDGAR, GDELT→GNews fallback with rate-limit/5xx conditions, USPTO PatentsView sunset soft-fail, and the return structure with citation URIs. 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?

Although longer than average, every sentence carries valuable information—sources, fallback behavior, soft-fail details, and output format. It front-loads the purpose with relatable natural-language examples and has no filler.

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

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

With no output schema, the description responsibly explains the return value (structured changes[] grouped by source, total_changes, pipeworx:// URIs). It also covers edge cases (API sunset, fallback conditions) and the alternative tool, making it 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?

The input schema already covers all three params at 100%, including the since format and value type. The description repeats and lightly reinforces with examples ('AAPL', '0000320193') but adds no meaning beyond the schema, 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 explicitly states this is a 'change feed for a company in the last N days/weeks/months', with specific verbs like 'what's new' and 'updates on'. It clearly distinguishes itself from siblings by naming entity_profile as the static-profile alternative.

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

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

Provides natural-language trigger examples and explicit guidance: 'Use entity_profile instead when you want the static profile...' This clearly communicates when to use this tool versus an alternative.

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

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

Beyond annotations, the description discloses scoping ('scoped by your identifier') and persistence differences ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). It also explains the write nature and storage format, adding significant value beyond the readOnlyHint/idempotentHint annotations. No contradiction found.

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

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

The description is five well-structured sentences, each serving a purpose: main action, usage guidance, storage mechanism, persistence behavior, and companion tools. It is front-loaded with the primary function and wastes no words.

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

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

For a simple write operation with two parameters and no output schema, the description fully covers purpose, usage, storage semantics, persistence, and tool integration. The annotations already address safety (non-destructive, idempotent), so the description is complete enough for an agent to select and invoke correctly.

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

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

The schema already has clear descriptions for both parameters with examples. The description adds extra semantic value by mentioning key-value scoping by identifier, and provides additional examples of keys/values (resolved ticker, target address). This goes slightly beyond the schema's coverage, so a 4 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 begins with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes itself from siblings by mentioning complementary tools (recall, forget) and explains the key-value storage model. The purpose is unambiguous and covers cross-session persistence.

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 when you discover something worth carrying forward...' and provides concrete examples. It also ties to alternatives by saying 'Pair with recall to retrieve later, forget to delete,' giving clear usage context and tool relationships.

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, indicating a safe, non-destructive, idempotent lookup. The description adds significant behavioral context: the tool cascades through multiple endpoints, degrades gracefully (GLEIF/OpenFIGI unavailability still returns EDGAR data), and explicitly states unresolved identifiers under an 'unresolved' field. No contradiction with annotations.

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

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

The description is front-loaded with actionable examples and a clear usage directive. The structured sections (SUPPORTED TYPES with sub-descriptions) are information-dense without being verbose. Every sentence provides necessary context, and there is no wasted text.

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 thoroughly explains what the tool returns: identifiers with source labels, unresolved list, and graceful degradation. It addresses multi-source cascading behavior, edge cases (ISIN handling), and type-specific behavior. This is complete for a complex lookup tool.

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

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

Schema coverage is 100% with both parameters described. The description goes well beyond the schema by explaining the types of values accepted (ticker, CIK, ISIN, name for company; brand/generic for drug), giving examples, and detailing special behavior like ISIN-to-LEI mapping. This adds significant meaning for the agent.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides specific example queries and lists supported types (company, drug) with detailed explanations. The phrase 'Use FIRST whenever you have a name but need an ID' distinguishes it from siblings like entity_profile, which likely provides details on already-resolved entities.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to invoke this tool. It also describes the supported input types and what they resolve to, and mentions that it replaces 2-3 manual lookups, giving the agent a strong understanding of its utility.

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

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

With annotations already confirming read-only, idempotent, and non-destructive behavior, the description adds valuable behavioral detail: it explains that the tool calls ai_visibility_check per entity, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and clarifies the operational mechanism and output.

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, efficiently front-loaded with the core action, and every clause contributes meaningful information (mechanism, ranking, use case, output). 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 description fully covers the tool's behavior, use case, and output structure. With schema providing parameter details and annotations covering safety, nothing critical is missing. It even explains why the tool is useful (competitive audits) and how it leverages ai_visibility_check.

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 all four parameters, so the baseline is 3. The description adds extra semantics by clarifying that the first entity is treated as the 'subject' for narrative while the rest are competitors, which is not in the schema. This additional context justifies a 4.

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

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

The description clearly states the tool's function: "Compare AI visibility across multiple entities side-by-side." It also specifies the mechanism (probes each entity with ai_visibility_check), the ranking behavior, and what it surfaces (most/least recognized), distinguishing it from the single-entity sibling tool ai_visibility_check.

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

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

The description gives an explicit use case for competitive AI-marketing audits and even provides an example question. It implicitly differentiates from single-entity tools by mentioning multiple entities, but it does not explicitly state when not to use this tool or name alternative tools (e.g., compare_entities for generic comparison), so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses valuable behavioral traits: it fans out across two services, handles partial failures gracefully, mentions possible 5-30s delay on first bundlephobia measurement, and explains the 'sources_failed' field. No contradiction with annotations.

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

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

The description is compact yet information-dense, front-loaded with the core purpose, followed by usage, return block, limitations, and failure behavior. Every sentence adds unique value; 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?

Given the complexity of a composite tool (two external services) and lack of output schema, the description is remarkably complete. It explains the return payload (summary fields, per-advisory details, links, alternatives), ecosystem limitation, and graceful degradation. No important behavioral or output aspect is left unaddressed.

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 covers both parameters (package, version) at 100%, so baseline is 3. The description adds meaningful constraint context: 'NPM ecosystem only in v1' clarifies the valid values for 'package' and indicates when not to use this tool. It also describes the output structure, aiding parameter interpretation.

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 'Composite ... check in ONE call' for npm packages, with specific verb ('scan') and resource ('dependency'). It distinguishes itself from siblings by explicitly listing the data sources (deps.dev, bundlephobia) and the types of questions it answers ('is X safe / popular / small').

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

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

It explicitly says 'Use whenever an agent asks ...' and gives specific example queries. It also provides a when-not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding agents to alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the return field list, which is useful but not deeply behavioral. It does not disclose pagination, rate limits, or edge cases.

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

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

Two concise sentences with all necessary information, front-loaded with the action. There is 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?

Simple 2-param search tool with an output schema and strong annotations. The description covers what, when, and return content; nothing critical is missing.

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

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

Schema coverage is 100% with both parameters having descriptions. The description adds no parameter-specific detail beyond the schema, 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 it searches npm for packages by keyword and lists the returned fields. It does not explicitly contrast with sibling tools like get_package, but the search/retrieval distinction is implicit.

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

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

The phrase 'Use when discovering libraries for a task' provides clear context for when to use this tool versus alternatives. It does not mention exclusions or name specific alternative tools, so it earns a 4 rather than 5.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive annotations, the description discloses specific behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and flagging, and returns character offsets and similarity scores. 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 three dense sentences, each adding value: purpose, usage guidelines, and technical behavior. It is front-loaded with the core function and every sentence earns its place without extraneous 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 explains return format (passages with offsets and similarity scores) and caveats (truncation, char cap). It also covers the tool's role in a RAG-like flow, making it complete for an agent to understand expectations despite missing 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?

The input schema covers all three parameters (text, query, limit) with descriptive text (100% coverage), so baseline is 3. The description adds further meaning by providing examples of 'text' (SEC 10-K, article) and clarifying the purpose of 'limit' as top-N passages, which enriches understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning passages with offsets and similarity scores. It distinguishes itself from sibling tools like ask_pipeworx_grounded and search_packages by specifying the input is already-pulled text, making the purpose specific and unambiguous.

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

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

Explicitly states when to use it: 'when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding over relevant passages. This provides clear context for use vs. alternatives, meeting the criteria for explicit when/when-not guidance.

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

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

The description adds significant behavioral context beyond annotations: it states that an OAuth account is required, returns the new subscription id, details delivery channels (feed always on, email/sms optional with caps and verification requirements), and even notes the phone number must be verified with a 10/day SMS cap. No contradiction with annotations is present.

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

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

The description is dense but well-structured: it front-loads the purpose, then provides prerequisites, supported types, and delivery options. It is a single block of text but every clause adds useful information. While it could be bulleted for readability, it remains efficiently compact.

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

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

Given the tool's complexity (multiple types, nested params, multiple delivery channels) and no output schema, the description covers prerequisites, return value, supported types, and delivery details, including optional email/sms. It omits webhook delivery in the main description, but the schema covers it. Overall, 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 coverage is 100%, so the baseline is 3. The description adds extra meaning by providing concrete examples for each subscription type (e.g., items:['5.02'] = officer change, topic:'fed') and after the 10/day SMS cap which is not in the schema. This pushes it 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 begins with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this tool from siblings like unsubscribe, list_subscriptions, and recent_alerts by focusing on creation and mentions it returns the new subscription id.

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

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

The description provides context on when to use the tool, stating it requires a Pipeworx OAuth account and explaining the feed channel can be pulled via recent_alerts or a GET endpoint. It gives supported types and delivery options, but does not explicitly mention alternatives like list_subscriptions or when not to use, though these are 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds value by explaining the response structure (category-bucketed examples with tool+argument shapes) and the optional topic focus 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 long but front-loaded with example queries and packed with valuable details. Every sentence earns its place—categories, return payload, parameter behavior, and usage timing—though it could be slightly tightened.

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 clearly communicates what the user will get (categorized example questions with tool+argument shapes), how to vary the output, and when to use it. It fully serves its onboarding purpose.

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

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

Schema coverage is 100% and already describes topic, but the description adds semantic meaning: calling with no arguments gives the full spread, while passing topic focuses the results. It also gives concrete examples like 'finance', 'pharma', 'betting'.

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 exactly what the tool does: it returns category-bucketed example questions for onboarding, each with the exact tool and argument shape needed. This clearly distinguishes it from siblings like discover_tools and ask_pipeworx by positioning it as the meta-level entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. It also explains the no-argument vs topic-filtered modes, providing concrete when-to-use guidance.

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

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

Beyond annotations, the description discloses that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. It also notes ownership enforcement, adding permission 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?

Two concise sentences, front-loaded with the primary action and immediately followed by key behavioral details. No 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?

For a simple one-parameter mutation tool with good annotations, the description covers purpose, ownership, and post-effect. No output schema is needed for this simple operation.

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

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

Schema coverage is 100% with a clear description of the id parameter. The tool description adds no additional param info beyond 'by id', 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 states the tool cancels a subscription by ID, using the verb 'Cancel' and resource 'subscription'. It distinguishes from siblings like subscribe and list_subscriptions by specifying ownership enforcement and the deactivation 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?

Provides clear context that only your own subscriptions can be cancelled and that deactivation preserves historical events via recent_alerts. It doesn't explicitly name alternatives, but the context implies it's the cancellation counterpart to subscribe.

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 idempotentHint=true; the description adds critical behavioral nuance by explaining that could_not_verify is a system failure (not evidence) and unsupported means no source coverage. This prevents misuse of verdict values, which is valuable 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 longer than average but front-loaded with trigger phrases and a clear purpose. Each section (examples, routing, verdict semantics, efficiency) earns its place, though the 'Replaces 4–6 sequential calls' benefit could be considered 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?

For a tool with no output schema, the description thoroughly explains the return values (verdicts), the distinction between could_not_verify and unsupported, and the two processing paths. It also provides usage guidance and tolerance configuration, making it 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 covers 100% of parameters with clear descriptions, so baseline is 3. The description adds practical semantics for tolerance_pct, explaining it overrides the wording-implied tolerance and recommending 1-2% for hallucination detection, which goes beyond the schema's generic 'max percent deviation.'

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

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

States a clear verb+resource: natural-language claim verification against authoritative sources. Distinguishes from siblings by explaining the SEC EDGAR/XBRL fast path for company-financial claims and automatic fallback for any other claim. Examples of user phrasings make the purpose immediately recognizable.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides trigger phrases. It also notes the tool replaces multiple sequential calls, implying it is the canonical verification entry point. However, it does not name specific sibling tools to avoid.

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