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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these: it routes to thousands of sources, returns structured answers with stable citation URIs, works on every tier, and makes a single fast call. It also notes that it already routes to live news for breaking-news queries, which is not inferable from annotations. No contradiction.

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

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

The description is fairly long, but every part serves a purpose. It is front-loaded with 'PREFER OVER WEB SEARCH' and structured with clear guidance, examples, and escalation paths. A few phrases could be condensed, but overall it earns its place for a default entry-point 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?

Even without an output schema, the description specifies the return type ('structured answer with stable pipeworx:// citation URIs') and covers the tool's domain breadth, limitations (when to step up), and example use cases. It is complete for a routing tool of this complexity.

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

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

Schema description coverage is 100% (all parameters are documented, mainly aliases for 'question'). The description does not add meaning beyond the schema; it repeats the alias list and provides examples. Baseline for high coverage is 3, and the description adds no extra semantic depth for the parameters.

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

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

The description clearly states the tool's purpose: it routes questions to the right tool among 5,439 tools across 1,412 sources and returns structured answers with citations. The verb 'asks' and the resource 'Pipeworx' are clearly defined, and it distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different use cases.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives. It also lists example query types and domain areas, making it easy for an agent to decide when to invoke this tool versus its siblings.

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

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

Annotations provide safety profile, but description adds crucial context: candidate routing improvements are live only when under test, currently no candidate active, so it matches ask_pipeworx exactly, and it falls back to nothing (full working router). 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?

Well-structured and front-loaded, but includes a specific retirement date and extra qualification that, while useful, make it slightly longer than needed. Overall efficient.

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

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

Covers purpose, current status, usage, and response shape (same as ask_pipeworx), which is adequate for a router tool with a simple one-required-param schema. No output schema exists, but description explicitly references ask_pipeworx for response shape.

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

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

Schema has 100% coverage with question and five aliases fully described. Description only repeats 'same arguments' without adding new semantics, 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 it's a beta version of ask_pipeworx, an identical universal router with same 5,439 tools, arguments, and response shape. This clearly distinguishes it from sibling tools (ask_pipeworx, ask_pipeworx_grounded) and explains its experimental edge.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when wanting newest routing, and notes results are compared against stable router. It doesn't enumerate when-not-to-use vs all siblings or mention grounded 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 the readOnly/openWorld/idempotent annotations, the description discloses the internal flow (routing, filling arguments, fetching data), the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), and explicit refusal behavior with enumerated refusal_reason values. It also flags the extra LLM call cost, providing rich behavioral context.

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

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

The description is front-loaded with the core purpose, followed by behavior and usage guidance. Every sentence contributes valuable information—routing, extraction guarantee, refusal reasons, use cases, and cost tradeoff—without redundancy or fluff.

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

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

Given the tool's complexity in a large ecosystem and the absence of an output schema, the description thoroughly covers return values, refusal scenarios, routing behavior, and use-case boundaries. It even names the sibling ask_pipeworx for contrast, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, with the question parameter and all aliases fully documented. The description adds no additional parameter-level meaning beyond the schema, so a baseline score of 3 is appropriate per the rubric.

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 defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb (extracts), resource (answer from tool results), and scope (grounded in fetched data). It also distinguishes itself from the sibling ask_pipeworx by explaining the extraction/refusal behavior, making the purpose unmistakable.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples like financial verdicts and legal claims. It also provides a clear exclusion and alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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

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

The description goes far beyond the annotations (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?

Goes well beyond the annotations (readOnly, openWorld, idempotent). Discloses account/paid-tier requirements, parallel decomposition across 5,439 tools, returns gaps[] for unanswered facets, never invents findings, includes contradictions[] scans, exposes hop fields and citation_uri formats, and describes semantic excerpting behavior and latency (15-60s, up to ~90s). No contradiction with annotations.

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

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

The description is long (~350 words) but every sentence adds distinct value—prerequisites, alternatives, behavior, depth semantics, latency. It is front-loaded with the account requirement and a direct alternative for non-signed-in users. Slightly verbose but not padded; receives 4 for being dense yet organized.

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

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

Given the tool's complexity, the description is remarkably comprehensive. It covers what it does, how it works, what it returns (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, citation_uri), prerequisites, latency, and explicit exclusions (not open-web search). No output schema exists, so the description fully compensates.

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?

While the schema already documents both parameters (100% coverage), the description enriches them substantially: explains that 'quick=3 facets single hop', 'standard=5' with gap recovery, 'thorough=8' with iterative chase, and notes that 'thorough needs a paid plan'. Also clarifies that broad/multi-part questions are acceptable and that decomposition is the point of the 'question' parameter.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' in one call. It distinguishes from siblings by explicitly warning 'this is NOT open-web search' and directing users to ask_pipeworx for single lookups and breaking news. Examples ('compare X and Y's regulatory + financial exposure') further clarify scope.

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

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

Provides explicit usage context: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also specifies when deep_research is ideal (broad/multi-part questions over structured data) and explains the depth options for iterative research.

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 provide no hints (all false), so the description carries full burden. It discloses rate limiting ('5 per identifier per day'), quota treatment ('doesn't count against your tool-call quota'), processing cadence ('team reads digests daily'), and content expectations ('don't paste the end-user's prompt'). These are genuinely helpful behavioral details beyond what schema or 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 front-loaded with the core purpose in the first sentence. Every subsequent sentence earns its place: exclusions, rate limits, quota, content guidance, and roadmap impact. It is dense but not padded, though it could arguably be tightened into a more scannable format without losing value.

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

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

Given the tool's simple functional surface (submit feedback), the description covers all necessary context: when to use, what types exist, exclusions, rate limits, quota, processing, and content guidelines. No output schema exists, but no return-value explanation is needed for a fire-and-forget feedback submission. The description is complete for this complexity level.

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 rich description (e.g., the 'type' enum defines each option). The description adds extra semantic guidance for the 'message' parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which goes beyond the schema's plain-text description. While the schema handles most param meaning, this additional context nudges it above the baseline.

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

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

The description opens with a clear, specific verb+resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates the feedback types (bug, feature/data_gap, praise) and is unmistakably distinct from sibling tools, which are research or subscription tools. No ambiguity about what this tool does.

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

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

The description gives explicit when-to-use scenarios ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...', 'when something worked surprisingly well') and a clear exclusion/alternative: 'if the tool came from a different MCP server... file it with that server instead.' It even clarifies how to identify Pipeworx tools for uncertain cases. This is exemplary 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?

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description isn't burdened with basic safety disclosure. It adds rich behavioral context beyond annotations: two modes, response shape, compatibility_warning trigger conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. This fully discloses potential failure modes and edge cases.

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

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

The description is long (~300 words) but every sentence carries information: modes, response fields, warning logic, and a realistic note about pre-mapped ≠ tradeable. It is front-loaded with the core purpose and structured into numbered modes and safety-field explanations. Slight verbosity but acceptable for the complexity.

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

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

With no output schema, the description fully explains return values: leg-by-leg prices, matched spread[] with top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It covers input modes, edge cases, and interpretation caveats. A complete resource for an agent to decide whether the spread is meaningful.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema. It explains the two-mode interaction (topic vs explicit overrides) and enumerates the 10 topic shortcuts, which the schema also lists but the description contextualizes. The 'Overrides the topic-mapped side' behavior is mentioned in both, but the description frames it as mode selection.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the tool's unique niche (cross-venue spread) and distinguishes it from siblings like polymarket_arbitrage and polymarket_edges by specifying the two-venue comparison and two operating modes.

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

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

The description explains when to use the tool (to compare cross-venue prices for equivalent bet shapes) and when not to: it warns that compatibility_warning fires when bet shapes are non-equivalent or events are semantically unrelated. It also sets expectations that most pre-mapped topics return warnings today. However, it does not explicitly name sibling tool alternatives, which prevents a top score.

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

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description details data sources (SEC EDGAR, RxNorm), output fields (ticker, CIK, RxCUI, ingredient, brand), citation URIs, and auto-disambiguation. It clearly portrays the tool as a non-destructive lookup, consistent with annotations.

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

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

The description is dense but well-structured with intent examples, a SUPPORTED TYPES section, and internal cascade note. Every sentence contributes useful info, though it is slightly long than ideal; still, it earns its space.

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

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

Given the tool's moderate complexity and lack of output schema, the description covers inputs, outputs, data sources, citation links, and disambiguation, fully informing the agent of the tool's behavior and results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the type-specific return values and accepted input formats (e.g., CIK with leading zeros, 'ozempic' example), which complements the schema's already detailed parameter descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with explicit examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes itself from sibling tools by focusing on identifier lookup rather than profiles or comparisons.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also highlights that using this tool replaces 2-3 manual lookups, implying it is the preferred first step for entity identification.

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?

The description goes well beyond the annotations by disclosing the dual-path behavior: the SEC EDGAR + XBRL structured path with exact percent-delta math, and the grounded pipeline with verbatim evidence. It also explains tolerance semantics, default behavior, and the return format with specific verdicts and citations. This adds substantial context beyond the read-only and idempotent hints.

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

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

The description is long but information-dense, front-loaded with concrete trigger examples. It covers purpose, usage, routing, and return values without redundant repetition of schema fields. Some sentences are complex, but each contributes meaningful guidance, so it earns a high but not perfect score.

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

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

This complex tool has no output schema, but the description fully explains the return values (verdict, actual value, citation, reasoning) and the two execution paths. It also addresses tolerance override behavior, making the description self-sufficient for an agent to understand what happens and what to expect.

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

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

With 100% schema coverage, the baseline is 3, but the description enriches the parameter semantics. It explicitly explains that tolerance_pct 'Overrides the tolerance implied by the claim wording' and notes the default 'implied by wording, capped at 5', which the schema does not state. This adds practical guidance for when and how to set the parameter.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from research or entity tools by focusing on the truthfulness of a user's statement, and even mentions replacing 4–6 sequential calls, clarifying its specific role.

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

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

The description provides strong when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing for company-financial claims vs. other claims, but does not explicitly name alternative sibling tools or state when not to use this tool. Thus it has clear context but lacks direct exclusions or alternative recommendations.

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