Bundlephobia

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

Beyond the annotations (read-only, open-world, idempotent), the description adds valuable behavioral details: the default model (Workers AI Llama-3.3-70b free), the optional Anthropic key with direct billing, and the return structure including per-model score, confidence, signals, and raw_response. This supplements the safety hints effectively, though it doesn't cover error handling or rate limits.

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

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

The description is remarkably concise at three sentences, front-loading the core purpose and then layering key details (default model, billing, return format, use cases). Every sentence earns its place with zero fluff.

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

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

With no output schema, the description compensates by explicitly stating the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers the default/free option, optional paid Anthropic integration, and realistic use cases, making it complete for an agent to select and invoke the tool effectively.

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

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

Schema description coverage is 100% for all four parameters, so the schema already documents each parameter adequately. The description adds context about the default model and _apiKey usage, but this is largely redundant with the schema's parameter descriptions. The baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Probe one or more LLMs') and clearly defines the resource (what LLMs know about a business/brand/product/topic) and output (visibility score 0-100 per model). This distinguishes it from siblings like ask_pipeworx or compare_entities by focusing on AI visibility scoring.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use it. However, it does not explicitly name alternatives 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?

Annotations already declare read-only, open-world, and idempotent behavior. The description goes further to disclose routing across 5,743 tools, argument filling, and stable pipeworx:// citation URIs in the result, adding substance beyond annotation-only safety information.

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

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

The description is long but every sentence earns its place: guidance, examples, and triage rules. The most critical instruction ('PREFER OVER WEB SEARCH') is front-loaded, making it easy for an agent to act decisively.

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 the lack of an output schema, the description clearly explains return format (structured answer with citation URIs), the breadth of coverage, and the tool's default role across tiers. This is sufficient for correct invocation and expectation-setting.

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

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

Schema description coverage is 100% and the schema itself documents aliases for the question parameter. The description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description identifies a clear verb+resource: routes a factual question to the appropriate verified source and returns structured answers with citations. It explicitly distinguishes itself from web search, ask_pipeworx_grounded, and deep_research by naming what each sibling is for.

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

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

Provides explicit 'PREFER OVER WEB SEARCH' and 'START HERE' directives, lists concrete trigger phrases and examples, and explains when to step up to ask_pipeworx_grounded or deep_research. This fully instructs an agent on when to use this tool versus alternatives.

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

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

The description adds substantial behavioral context beyond the annotations: it explains the tool is an experimental edge, that candidate routing improvements are enabled live when under test, that no candidate is currently active, and that results are compared against the stable router. This is rich, relevant disclosure that helps an agent calibrate 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 front-loaded with the core identity of the tool, then current state, then usage guidance. It is somewhat repetitive (mentions matching ask_pipeworx both explicitly and implicitly), but the extra detail about live candidates and evaluation purpose earns its place.

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

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

For a routing tool with no output schema, the description sufficiently explains what the tool is, how it behaves, how to use it, and how it differs from the stable version. Minor gaps include not describing a typical output or giving an example, but the aliases and response shape are covered via schema and the reference to ask_pipeworx.

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

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

The input schema fully documents all six parameters and aliases at 100% coverage, so the description does not need to add parameter-level detail. The description mentions 'same arguments' but does not elaborate; with the schema carrying the burden, the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, states it is an identical universal router with the same 5,743 tools, arguments, and response shape, and distinguishes it by its experimental routing improvements. It is specific about the resource and how it relates to the stable sibling, making its purpose unambiguous.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and contrasts it with the stable router. It gives clear context and a specific condition, though it does not enumerate when not to use it or mention other sibling alternatives like ask_pipeworx_grounded.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial context: it returns verbatim evidence and confidence, refuses with specific refusal_reason values when the data doesn't answer, and costs one extra LLM call. No contradiction with annotations.

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

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

The description is longer than minimal but every sentence carries operational value: behavior, output shape, refusal conditions, and usage guidance. It is front-loaded with the core promise, though some internal details (tool count, argument filling) could be trimmed without losing essential guidance.

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

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

No output schema exists, yet the description fully documents the success and refusal return shapes. It also covers when to prefer this tool, the extra cost, and the routing behavior, leaving no material gap for an agent deciding whether and how to invoke it.

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

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

Schema description coverage is 100%: all parameter aliases are documented as aliases for question, and the question parameter explains the aliases. The description adds no additional parameter semantics, but the schema already fully covers it, so the baseline of 3 applies.

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

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

Clearly describes a specific tool behavior: a hallucination-resistant, grounded answer mode that routes like ask_pipeworx but extracts answers only from tool results. It differentiates itself from the sibling ask_pipeworx by emphasizing evidence-based, refusal-capable answers.

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: high-stakes reads where answers will be quoted, cited, or acted on. It also names the alternative (ask_pipeworx) and the trade-off (extra LLM call), directing casual lookups elsewhere.

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, detailing fan-out logic, resolver confidence levels, parent_event extraction, GDELT/GNews fallback behavior, status codes for low-confidence/closed markets, illiquid spread warnings, and resolution-rule risk (including the refund_50_50 flat-50¢ loss scenario). This is a rich, multi-layered disclosure of how the tool behaves and what could go wrong, with no contradictions to 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 extremely long and dense, with numerous all-caps section headers and repeated concepts (e.g., low-confidence paths are mentioned in both the SAFETY and RESOLVER CONTRACT sections). While the first sentence is a strong front-loaded summary, the excessive length and redundancy make it less scannable and more token-expensive than necessary for an agent to efficiently parse.

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

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

With no output schema, the description thoroughly documents the expected response shape: result.market fields, result.analysis with model probabilities and edge warnings, result.evidence keying, resolver match contract, parent_event structure, news fallback metadata, and special statuses. It covers edge cases like closed markets and low-confidence matches, ensuring the agent knows exactly how to interpret every possible outcome.

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

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

The input schema already provides 100% coverage with thorough descriptions: the market parameter types, depth options, and include_raw behavior are all clearly defined. The tool description adds illustrative fan-out examples but does not reveal new semantic meaning beyond what the schema and response-shape text already convey. Baseline 3 is appropriate.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which gives a specific verb+resource+method and distinguishes it from broader sibling tools like deep_research or ask_pipeworx. It also provides explicit use cases ('should I bet on X', 'what does the data say about Y'), making the tool's 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?

The description gives clear usage context with phrases like 'Use for...' and provides examples of when to rely on it (sports bets, elections, etc.). It also warns users to inspect match confidence and resolution-rule risk before sizing bets. However, it does not explicitly contrast with alternative sibling tools (e.g., 'use polymarket_edges for cross-market edge detection'), so it falls just short of a 5.

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

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

The description adds substantial behavioral detail beyond the read-only/idempotent annotations: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. No contradiction with annotations.

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

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

The description is dense but not bloated; it front-loads trigger examples and preference guidance, and each subsequent clause adds value (data sources, sorting, efficiency). While longer than minimal, it earns its length for a tool that needs this context.

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 effectively covers return semantics ('Returns paired data + pipeworx:// citation URIs per entity') and result ordering, plus entity-specific metrics. The annotations handle safety, and the description covers selection, invocation, and data scope comprehensively.

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

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

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description enhances parameter understanding by explaining how the 'type' parameter changes data retrieval and providing concrete examples for the 'values' array (e.g., ['AAPL','MSFT'] vs ['ozempic','mounjaro']). This adds meaningful context beyond the schema.

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

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

The description clearly identifies the tool's function: side-by-side comparison of 2-5 entities in a single parallel call. It provides trigger phrases ('X vs Y', 'which is bigger') and explicitly distinguishes from sequential single-entity lookups, making the purpose unambiguous.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also describes the two entity types and their respective data sources, enabling the agent to choose appropriately between company and drug comparisons.

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

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

Annotations already signal read-only and idempotent behavior, but the description adds substantial behavioral detail: parallel tool routing, findings packet structure, gaps[] never-invented guarantee, contradictions[], hop field, citation_uri fetchability, semantic excerpting, and latency expectations. It also discloses the paid-tier constraint for thorough depth, all beyond the annotation signals.

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

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

The description is long, but every sentence earns its place by covering a distinct and material aspect: auth, sibling routing, sourcing, return packet, gaps, contradictions, citations, excerpting, and latency. Critical caveats are front-loaded at the very beginning, and the rest is organized logically.

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 is a high-complexity tool with no output schema, so the description correctly carries the full burden of explaining the return value. It does so exhaustively: evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop, and performance expectations. There is no missing operational detail an agent would need to call or interpret this tool correctly.

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

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

Schema coverage is 100% and the schema already documents both parameters richly, so a baseline of 3 applies. The description adds genuine extras: the account/paid-plan prerequisite, what 'standard' vs 'thorough' do at a higher level, and example question shapes. It doesn't need to document question syntax because the schema already handles that.

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 ('research') and identifies the precise resource (Pipeworx's 1500 STRUCTURED data sources, with concrete examples like SEC filings, FRED/BLS, FDA). It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, so an agent cannot mistake it for a related 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?

The description gives clear when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly says to use ask_pipeworx for single lookups and for breaking/colloquial current-news topics. It also states the account prerequisite and that depth:'thorough' requires a paid plan, plus the signed-out fallback.

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 covered. The description adds valuable context about behavior: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations to explain what the user gets and how to use the 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 concise but information-dense. It packs the action, use case, domain list, return behavior, and usage advice into three sentences with no redundancy. The structure front-loads the verb and resource, making it easy to scan.

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

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

Given its simplicity (one required parameter, no output schema), the description fully covers what the tool does, when to use it, what it returns, and how the output is ready for direct use. It is complete for a discovery tool and leaves no major gaps in understanding.

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

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

Schema description coverage is 100%, so all parameters (query, aliases, limit) are already well documented. The description does not add additional parameter semantics beyond what the schema provides, but it includes examples that reinforce the query format. With high schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task' and enumerates the domains it covers, making the purpose specific and actionable. It differentiates from sibling tools by emphasizing discovery and 'Call this FIRST' for exploring available tools, which is distinct from direct-answer or research tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance, though it stops short of naming specific alternative tools or explicit exclusions, which would push it to a 5.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds substantial behavioral depth well beyond that: USPTO soft-fail behavior, empty sections meaning 'real no data' not a bug, private companies returning resolved:false with a notes line, and a sources_used/sources_failed mechanism. It also discloses the parallel fan-out across SEC, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, GDELT/GNews, and GLEIF. This is rich, honest 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 it is dense with necessary information for a complex multi-source tool. It front-loads usage examples and the 'ALWAYS PREFER' directive, then proceeds through scope, fan-out sources, return sections, edge cases, and input flexibility. No sentence is filler; length is justified by the tool's complexity.

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

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

With no output schema to fall back on, the description effectively serves as the return contract: it enumerates cik, company_name, resolved_from/resolved_to, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also covers failure modes and the private-company case. Given the tool's complexity and absence of an output schema, this description is complete enough for an agent to call and interpret the result 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 covers both parameters at 100%, so the baseline is 3. The description adds real value on top: type is explicitly noted as accepting 'company' or 'ticker' interchangeably, and value is clarified to accept a ticker, zero-padded CIK, or company name with name resolution via SEC EDGAR. Concrete examples ('AAPL', '0000320193', 'Moderna') further sharpen the semantics.

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

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

The description opens with concrete user phrasings and states a specific verb-resource pair: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from chained single-source lookups and names sibling-style alternatives like SEC/XBRL/news lookups. This is a model of a purpose-stated description.

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

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

The description explicitly tells the agent when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It gives many trigger examples such as 'tell me about X' and 'brief me on Tesla.' However, it does not address when not to use it or how it compares to siblings like compare_entities, resolve_entity, or deep_research, so it stops just short of full alternative-routing 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 discloses that it deletes a stored memory and mentions clearing sensitive data, adding context beyond the destructiveHint and idempotentHint annotations. It does not contradict annotations, though it could elaborate on idempotent behavior for non-existent keys.

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

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

The description is three sentences, each serving a purpose: action, usage conditions, and related tools. It is front-loaded with the core function and is efficiently structured.

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 destructive tool, the description covers purpose, usage, and related tools. The annotations provide destructive and idempotent hints, and no output schema is needed, so the context is 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 schema already documents the key parameter with a description and example, achieving 100% coverage. The description adds no further parameter details beyond saying 'by key,' so it does not enhance 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 'Delete a previously stored memory by key,' using a specific verb and resource. This distinguishes it from sibling tools like remember and recall by indicating the deletion action.

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 provides when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also recommends pairing with remember and recall, giving clear guidance on alternative usage.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds behavioral detail: it fetches the page, extracts title/description/key links, and outputs standard markdown. It also states the output is a single text blob ready for site-root placement, which is useful context beyond annotations.

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

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

Three sentences with no filler. The first sentence states the core function, the second explains the process, and the third lists use cases. Perfectly front-loaded.

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

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

The tool is simple with two parameters and no output schema, and the description covers the workflow, output format, and use cases. Given the low complexity, this is fully complete.

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

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

Schema coverage is 100%, so both parameters (url and max_links) are fully described in the schema. The description doesn't add parameter-specific semantics beyond what's already there, but it does clarify the output format and the purpose of the extraction, so a baseline of 3 is appropriate.

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

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

The description opens with a specific verb ('Generate') and resource ('llms.txt file for any URL'), explaining the goal of making a site indexable by AI crawlers. It also walks through the extraction process, clearly differentiating it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which are about checking presence rather than generating files.

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 lists concrete scenarios: getting a client's site indexed, drafting for own project, or auditing a competitor. This gives clear guidance on when to use it. It doesn't mention exclusions or alternatives, but the context is strong enough.

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/destructive safety. The description adds the limit of 5 versions 'to avoid timeouts' and the 'side-by-side' output format, providing useful behavioral context 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 a single well-structured sentence, front-loaded with the verb 'Fetch', and every clause adds value. No wasted words.

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

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

With an output schema present, return values are covered. The description includes all necessary usage constraints (version limit, purpose) and the read-only/idempotent annotations provide additional context, making the tool fully usable.

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

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

Schema coverage is 50% with only the 'versions' parameter described. The description compensates by explaining 'up to 5 specified versions' and the comma-separated format. It adds meaning without contradicting 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 states 'Fetch minified + gzipped bundle size for each of up to 5 specified versions of an npm package' with the specific purpose of 'size regression tracking'. It clearly distinguishes from sibling tools like 'size' by emphasizing multi-version comparison.

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

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

The phrase 'for size regression tracking' gives clear context for when to use this tool, implying comparison of multiple versions. However, it does not explicitly name alternatives or exclude cases, so it stops short of a full 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds context by listing the exact fields returned and noting that it shows active subscriptions by default, which implies filtering behavior beyond the annotations.

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

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

Two sentences, front-loaded with purpose and return fields, followed by actionable usage guidance. Every word earns its place.

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

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

For a simple list tool with one optional param and good annotations, the description covers purpose, returned fields, and usage scenarios. No output schema is present, but the field list suffices. Complete and well-rounded.

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 sole parameter (include_inactive) is fully documented. The description does not add extra meaning beyond the schema, though it marginally hints at active-only default behavior. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('subscriptions'), clearly scoped to the caller's active subscriptions. It distinguishes itself from sibling tools like subscribe and unsubscribe by being a read-only listing operation.

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: 'before adding more' subscriptions and 'to find an id to cancel.' This implicitly points to the alternatives (subscribe/unsubscribe) and gives concrete 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 are all false and provide minimal safety signals, so the description carries the burden. It discloses rate limits ('5 per identifier per day'), the claim_token workflow, that it's free and doesn't count against quota, and that feedback is read daily and affects roadmap. This goes well beyond the structured 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 lengthy but every sentence serves a purpose: scope definition, when-not-to-use, token mechanism, rate limits, and privacy guidance. It is front-loaded with the core action and then layered with essential details, 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?

Despite having no output schema, the description explains what returns to expect ('returns a claim_token' and 'returns the status and what changed'). It covers exclusions, parameter workflow, and operational constraints. For a feedback tool with 4 params, it is fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds concrete usage context beyond the schema, such as the example for claim_token passing and 'with no other arguments.' While it doesn't detail every parameter, it enriches the most complex one (claim_token) with a practical pattern.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool's purpose and differentiates it from siblings by focusing on feedback rather than querying or research, making it unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states an exclusion: 'if the tool came from a different MCP server... file it with that server instead,' which is a clear 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 indicate a safe, read-only, idempotent operation. The description adds valuable behavioral context: caching behavior (5min-1h), data lineage (CF analytics-engine), privacy (no PII), and output structure (pack, tool, count). This goes beyond the annotations and enhances transparency.

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

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

The description is somewhat long but well-structured with a lead sentence, return summary, and bulleted use cases. Each section serves a purpose, and the layout makes it scannable, though it could be more concise by trimming redundant wording.

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

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

Without an output schema, the description adequately explains return values (top tools, top packs, total call volume) and data shape (pack, tool, count). It also covers caching, use cases, and privacy, making it complete for a 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 coverage is 100% with the 'window' parameter fully documented, including enum values and trade-offs. The description mentions the window options but does not add new semantics beyond what the schema already explains, so the 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?

The description clearly states it returns top tools, top packs, and total call volume over a window, uniquely distinguishing it from sibling tools like discover_tools by focusing on what other AI agents are calling. The verb 'Returns' is specific and the resource is well-defined.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment with agent needs), which gives clear context for when to use it. It does not explicitly compare to alternatives or state when not to use it, but the use cases serve as strong guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description discloses important behavioral nuances: the semantic anchor threshold (Jaccard ≥0.30), partition filter placeholder logic, and the fill check condition 'realizable_edge_pp ≤ 0 means... do not trade it'. It also explains the response structure and edge cases, adding substantial context beyond the structured fields.

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

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

The description is quite long but extremely well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and bolded mode emphasis. Every sentence adds unique, non-redundant context. It is not concise, but the complexity of the tool justifies the length; the structure makes it easily 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?

There is no output schema, so the description carries the full burden of explaining return values, which it does thoroughly: 'Response: opportunities[] (gap_pp, suggested_trade, reasoning...) and in event mode partition_check{...}'. It also covers edge cases, thresholds, and what to do when the signal is not tradeable. For a tool with complex behavior and no output schema, this is complete.

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

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

Schema coverage is 100%, but the description goes far beyond the schema. It explains what event slugs look like with examples, what topic seed questions work, and what each mode does internally (e.g., 'walks child markets, checks date-axis / threshold-axis ordering'). It adds meaning that the input schema does not provide, such as accepting full URLs and describing cross-event behavior.

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

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

The description opens with a specific action: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and differentiates from siblings by explaining the exact methodology. This is a textbook example of purpose clarity with specific verb+resource+scope.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan' and 'event (recommended for a specific market)' vs 'topic (for cross-event scanning)'. It even names an alternative tool: 'For custom sizing use polymarket_fill_risk.' This exceeds the bar for 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 goes far beyond the readOnly/idempotent annotations, revealing internal model families, specific thresholds, response fields, diagnostics, and even 1h caching behavior. It also explains why Fed candidates are excluded, providing rich context about the tool's behavior.

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

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

The description is a dense wall of text with extensive technical details (model formulas, alpha values, threshold changes) that could be moved to documentation. While it has some section headings, it is far too long for a tool description and not front-loaded beyond the first sentence.

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

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

With no output schema, the description thoroughly covers the response structure, including by_segment, fed_candidates, and _diagnostics, as well as all filters and caching. It is complete enough for an agent to understand what to expect and why.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description additionally explains the rationale behind key knobs, especially min_partition_leg_kelly and tradeable-edge filters, adding meaning beyond the schema's definitions.

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

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

The opening sentence clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It also provides a specific use case ('what should I bet on today') and distinguishes itself from siblings by focusing on discovery and data disagreement.

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 frames the tool for discovering bet opportunities without paging hundreds of markets. It also explains how to adjust knobs like slippage and filters to get tradeable edges, but does not explicitly mention alternative tools or when not to use this one.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral detail beyond these: history depth bounded by 60-day TTL, snapshot gaps on cache-miss days, decay computed from daily closes not intraday, and the sign convention for edge_pp_net. This goes far 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 with Args, RESPONSE, and LIMITS sections, and it front-loads the core question. It is longer than minimal but every sentence contributes value. A slight reduction in verbosity could make it even cleaner, so 4 rather than 5.

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

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

With no output schema, the description fully covers the response structure: tracked[], expired[], and snapshot_dates[], including field explanations, calculation methods (trend, decay_pp_per_day), and limitations (TTL, start time, daily close basis). This is a complete specification for a complex telemetry 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 descriptions for both parameters, and the description largely repeats the schema defaults (days default 14, max 30; window default '1wk'). It adds the concept of 'snapshot family' but this is already in the schema. No significant new semantics are provided, 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 identifies the tool as providing 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, answering the specific question 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools that likely just list current edges, such as polymarket_edges.

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

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

The description provides clear context for when to use the tool (to assess edge longevity and decay) and distinguishes it from taking a fresh wide edge. However, it does not explicitly name alternative tools or state exclusions, so it earns a 4 rather than 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?

Even with readOnlyHint=true and idempotentHint=true, the description goes well beyond annotations by disclosing the execution behavior: 'walks the ladder,' the exact return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), per-leg filling details, and the warning about forced directional risk. This gives the agent a clear model of what happens on invocation.

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

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

Though detailed, the description is tightly organized (SINGLE-MARKET, BASKET, USE THIS) with every sentence delivering necessary information. No repetition or filler; the length is justified by the tool's dual-mode 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?

Given the tool's complexity and lack of an output schema, the description thoroughly covers both modes, return values, parameter interpretations, and high-risk use cases. It even names the dominant failure mode (partial basket fills into unhedged positions), ensuring the agent can act appropriately.

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

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

Schema descriptions are already rich (100% coverage), but the description adds essential interpretive context: size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode; side has mode-specific meanings; and it explains the default auto-selection for basket side. This goes 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 a precise statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which clearly defines the tool's function. It differentiates itself from sibling analytical tools by targeting pre-trade risk validation for polymarket arbitrage/edge signals, and details two operational 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 provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (thin books, partial fills) and describes input-mode selection criteria (market vs event).

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 only indicate read-only, idempotent, non-destructive behavior. The description goes far beyond that by disclosing specific safety fields, semantics of compatibility_codes, the meaning of null in temporal_alignment, the gross-vs-net fee limitation, and the rule that unknown legs are never paired. This is a model of behavioral transparency.

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

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

The description is long, but every sentence carries a distinct operational fact. It is front-loaded with a one-sentence purpose before moving into modes, response shape, safety fields, and caveats. The density is justified by the tool's complexity, though a bit more paragraphing would improve scannability.

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

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

With no output schema, the description must fully explain the return payload, and it does: leg-by-leg prices, top_spreads_pp, compatibility_codes, skipped counters, temporal_alignment, and the standing fees_note. An agent can invoke the tool and interpret its results correctly without needing external documentation.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful value by enumerating the 10 valid topic values, providing format examples for kalshi_event_ticker and polymarket_event_slug, and explaining that explicit parameters override the topic-mapped side. This gives an agent enough context to choose 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 first sentence clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It goes on to describe two concrete modes, distinguishing it from single-venue siblings like polymarket_edges and polymarket_arbitrage. The purpose is specific, actionable, and not a tautology.

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 context for when to use each mode: topic shortcuts for pre-mapped macro questions and explicit ticker/slug for custom pairings. It also warns that pre-mapped topics often return compatibility_warning and that pre-mapped does not mean tradeable. It does not explicitly name alternative tools, but the usage conditions are clear enough.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the list-when-omitted behavior. This goes beyond the structured fields without contradicting them.

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

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

Three sentences, front-loaded with the primary action, followed by use case and scoping. No redundant or filler content. Every sentence earns its place.

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

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

For a simple tool with one optional parameter, the description covers purpose, usage, scoping, and relationships to siblings. Annotations handle safety, so no return-value details are necessary. It is fully complete for the tool's complexity.

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

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

The schema already covers the key parameter completely (100% coverage). The description enrichs this by providing concrete examples of what keys represent (user's target ticker, address, research notes) and clarifies the omit-to-list behavior, adding meaning beyond the schema's own description.

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: retrieving a value saved via remember, or listing all saved keys when the key argument is omitted. It names the specific verb+resource (retrieve value/list keys) and distinguishes from sibling tools like remember (save) and forget (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?

It explicitly explains when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also names companion tools ('Pair with remember to save, forget to delete'), providing clear guidance on relationship 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?

The description discloses the side effect of mark_read (flagging events read so future calls return only newer ones) and details the return payload (source, citation_uri, raw event payload). This adds meaningful context beyond the readOnlyHint and idempotentHint annotations, with no contradiction.

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

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

The description is a tightly knit paragraph of about 60 words, each sentence contributing to the tool's purpose, return format, filtering, read behavior, or alternative access. No redundant or vague language.

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

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

Despite lacking an output schema, the description explains what each alert contains (source, citation_uri, payload) and covers key filtering/polling behavior. It also mentions an HTTP endpoint for non-interactive use, ensuring the agent understands the tool's full capabilities and limitations.

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 practical value by giving a concrete example for type ('sec_8k') and explaining the behavioral impact of mark_read on subsequent calls, which helps the agent 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 opens with 'Pull fired events from your subscription feed,' which clearly states the tool's function and resource. It distinguishes itself from sibling tools like list_subscriptions or recent_changes by focusing on fired alerts and their source.

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 guidance: 'Polls work fine' and notes the same feed is available via HTTP for scripts/dashboards, implicitly steering the agent to use this tool for interactive polling. It does not explicitly compare to alternative tools but clarifies the context of use.

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 behavior thoroughly: fans out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fails due to PatentsView API sunset, and the return structure (changes[] grouped by source + total_changes + citation URIs). 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 densely informative with no wasted words. It front-loads the purpose and usage examples, then covers sources, parameter details, return format, and alternatives—all in a compact structure that justifies its length.

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 specifies the return shape (changes[] with source grouping, total_changes, citation URIs) and notes caveats (USPTO soft-fail). Combined with strong schema and annotations, this makes the tool's behavior complete enough for an agent.

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

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

The input schema already fully describes all parameters (type, since, value) with examples and typical usage. The description adds no meaningful semantic information beyond the schema, so the baseline of 3 for high schema coverage applies.

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

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

The description clearly states it is a change feed for a company in the last N days/weeks/months, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly contrasts with entity_profile, making the purpose and differentiation from siblings clear.

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 example queries ('What's new with X', 'latest on Y') to signal appropriate use cases. Directly states to use entity_profile instead when a static profile is needed, giving clear when-to-use vs. alternative 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 fully cover the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds the data source and an interpretive framing ('community interest') and implies results are dynamic since 'most recently measured' shifts over time, but it does not disclose operational details such as ordering guarantees or time windows. 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?

A single front-loaded sentence with the verb and resource up front. The closing clause ('showing current community interest in bundle-size analysis') adds interpretive value that aids purpose clarity rather than pure filler, keeping the entry compact and 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?

For a low-complexity tool with zero required parameters, a fully documented parameter, comprehensive annotations, and an existing output schema, the description is largely sufficient. The only minor gaps are implicit ordering (recency) and a lack of any stated time window, which are easily inferred from 'most recently measured.'

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% — the limit parameter is already fully documented as 'Max entries to return (default 25)'. The description adds nothing about parameters, so it sits at the baseline for tools whose 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?

States a specific verb ('Return'), resource ('npm packages most recently measured on bundlephobia.com'), and interpretive context ('showing current community interest'). The domain mention clearly distinguishes it from sibling tools like recent_alerts and recent_changes without needing to open any schema.

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

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

Usage context is implied through domain-specific language — an agent can infer it is for fetching recently measured npm packages or gauging community bundle-size interest. However, it never explicitly says when to choose this over sibling tools like pipeworx_trending, discover_tools, or recent_changes, and names no alternatives or exclusions.

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

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

Annotations already declare idempotentHint and destructiveHint, and the description adds valuable behavioral context: 'scoped by your identifier,' 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This goes beyond annotations by clarifying retention and scoping, which are important for an agent invoking the tool.

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

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

The description is compact, front-loaded with the primary action, followed by use cases and operational details. Each sentence adds essential information without redundancy, making it concise and well-structured.

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

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

Given the tool's simplicity, the schema fully covers parameters, annotations cover safety traits, and the description adds retention behavior and sibling tool relationships. No output schema is needed. The only minor gap is unspecified overwrite semantics, but the overall context is sufficient for correct invocation.

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

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

Schema coverage is 100%, with both key and value described with examples, so the baseline is 3. The description adds the concept of scoping by identifier, which enriches understanding of the key's role, but it does not provide additional parameter-level detail beyond the schema. Thus a score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later.' It explicitly identifies the resource as a key-value store and distinguishes itself from related tools by mentioning 'Pair with recall to retrieve later, forget to delete.' This makes the purpose unambiguous and differentiates from siblings.

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

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

The description provides explicit use cases: 'when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also directs pairing with recall and forget for complementary actions. While it does not explicitly state when not to use the tool, the given context is strong enough to guide selection.

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

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

Beyond the annotations, the description discloses substantial behavior: ambiguous matches return figi_candidates without asserting a result, unresolved identifiers are explicitly listed under unresolved, LEI/FIGI enrichment degrades gracefully if upstream APIs are unavailable, and every identifier is labeled with its source. This is exactly the kind of behavioral transparency that helps an agent predict tool outcomes.

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

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

The description is long and dense, but nearly every sentence carries useful operational guidance or an edge-case warning. It is front-loaded with the purpose and the critical 'Use FIRST' directive. The structure could be cleaner — the company sub-description is a large parenthetical run-on — yet it remains appropriately detailed for a tool with this much behavioral nuance.

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

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

For a tool with no output schema, the description is remarkably complete: it covers input forms, supported entity types, return-behavior quirks (figi_candidates, unresolved), data sources, fallback behavior, and cross-tool value. An agent has enough context to call the tool correctly and interpret results without further manual discovery.

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

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

The schema already covers the value parameter thoroughly, including input formats and the bond issuer-name warning. The description adds meaningful parameter-level semantics by explaining what each supported type resolves to: company returns CIK, ticker, company_name, LEI, ownership, and FIGI; drug returns RxCUI, ingredient, and brand. This goes beyond the schema's bare enum, though much of the value-parameter guidance is duplicated from the schema rather than newly added.

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

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

The description immediately states the core function: resolving a user-spoken name to canonical identifiers that other tools require as input, reinforced by multiple concrete examples ('What's the ticker for...', 'find the CIK for...'). It also enumerates the supported entity types and, by framing the tool as a name-to-ID resolver, distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups, which helps an agent understand its place in the pipeline. However, it does not explicitly state when not to use it or name alternative sibling tools for already-resolved entities or profile retrieval, so it falls short of full exclusion guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the description rightly focuses on behaviors beyond annotations: probing with ai_visibility_check, ranking by score, and returning a ranked list with score/confidence/signal density. It also hints at real-world usage and model support. No contradictions.

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 an illustrative quote, front-loaded with the core action and output. Every sentence contributes value—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?

Despite no output schema, the description specifies the return format (ranked list with score, confidence, signal density). It explains the relationship to ai_visibility_check and notes multi-entity scope. Combined with comprehensive parameter schema, this is complete for a comparative audit 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 tool description adds minimal parameter-specific meaning beyond what the schema already provides (e.g., 'entities' as subject vs competitors is already in the schema). There is no extra clarification in the description itself, so it remains at 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 uses a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), clearly distinguishing it from the single-entity ai_visibility_check and the generic compare_entities. It states it ranks by score and surfaces most/least recognized, leaving no ambiguity about the tool's purpose.

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

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

Provides a clear use case ('competitive AI-marketing audits') with an example question, and implies this is the multi-entity version of ai_visibility_check. However, it does not explicitly name alternatives or exclusions (e.g., when to use compare_entities instead), so it falls short of a full 5.

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

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

The description goes well beyond the readOnly/idempotent annotations, disclosing the composite fan-out, graceful partial failure behavior, 5-30s first-measurement timeout, and the sources_failed field. This gives the agent an accurate model of runtime 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?

Dense and information-rich, with the purpose and usage front-loaded and each sentence conveying a distinct aspect (purpose, usage, return values, ecosystem scope, failure behavior). Slightly long but justifiable given the tool's complexity.

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

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

There is no output schema, so the description must explain return values, and it does comprehensively, listing the summary block fields, per-advisory detail, links, and alternative versions. It also covers ecosystem limitations and failure handling, making it complete for an agent to invoke and interpret results.

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

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

The input schema already fully documents both parameters with descriptions, achieving 100% coverage. The description does not add extra parameter-level semantics beyond what the schema provides, so the baseline 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?

Clearly identifies a specific composite check for npm packages, naming the exact question it answers and the data sources it combines. It is well-differentiated from the sibling tools, which focus on AI visibility, research, or prediction markets.

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 'Use whenever an agent asks...' and gives concrete examples like 'is X safe / popular / small' or 'what does adding lodash cost me'. It also defines the boundary by noting NPM-only scope and pointing to deps.dev directly for other ecosystems.

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 reveals internal mechanics beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output structure (passages, character offsets, similarity scores). This is rich disclosure that adds actionable context without contradicting the readOnly/idempotent hints.

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

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

Four sentences, each serving a distinct purpose: action+example, use case, workflow pairing, technical detail. It is front-loaded with the core action and contains zero redundancy or filler, making it efficient and 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 no output schema, the description explicitly states what to expect (top-N passages, character offsets, similarity scores). It covers input limits, truncation behavior, and integration with ask_pipeworx_grounded. Combined with strong annotations and full parameter coverage, nothing critical is left ambiguous.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds semantic value by framing 'text' as a fetched record, providing query examples, and clarifying the relationship between the two required parameters. While the schema already documents each field, these examples and contextual clues elevate it from the baseline 3.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' naming a specific verb and resource. Concrete examples (SEC 10-K, article, tool result) and the explicit contrast with ask_pipeworx_grounded distinguish this from sibling tools.

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

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

It provides explicit guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, showing how to integrate search_within into a workflow. The alternative of grounding over whole document is implied, giving clear when-to-use vs. when-not-to-use context.

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

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

Annotations already indicate readOnly and non-destructive behavior, so the description's burden is lower. It adds valuable behavioral detail by specifying the return includes minified + gzipped bundle sizes, which goes beyond the schema or annotations. 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?

A single, dense sentence that front-loads the action and includes the key output detail (bundle sizes) and purpose. No wasted words.

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

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

Given the simple tool, rich annotations, and existing output schema, the description covers the core behavior and purpose well. The only missing context is the 'version' parameter semantics, which prevents a perfect score.

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 0%, so the description must explain parameters. It clarifies the 'package' param as the given package, but completely omits the 'version' parameter, leaving its purpose and optionality unexplained. This is a significant gap.

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

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

The description uses a specific verb ('Return') and resource ('npm packages with similar functionality to the given package'), clearly distinguishing this tool from siblings like 'size' or 'compare_entities'. It also states the output includes minified + gzipped bundle sizes, 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?

The phrase 'to aid migration or replacement decisions' gives clear context for when to use this tool. It does not explicitly name alternatives or exclusions, but the context is strong enough to infer appropriate usage without confusion.

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, so the safety profile is covered. The description adds meaningful context by enumerating the specific analysis dimensions (minified+gzipped size, tree-shakeability, dependencies, ESM/CJS), which informs the agent about the tool's output focus. It does not describe error behavior or return format, but that is acceptable given the output schema exists.

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

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

The description is a single, information-dense sentence: 'Bundle size analysis — minified + gzipped, tree-shakeability, dependencies, esm/cjs detection.' Every element adds value, and the dash after the main phrase highlights the key features. There is zero 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 lookup tool with three well-documented parameters, strong annotations, and an output schema, the description provides sufficient context. It identifies the core purpose and key output dimensions, and the schema and annotations cover parameters and safety. No critical information for agent invocation is missing.

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

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

Input schema coverage is 100%, with clear descriptions for each parameter (package, version, record). The description adds no parameter-specific guidance beyond what the schema already provides. Since the schema fully documents parameters, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: bundle size analysis, listing specific metrics (minified + gzipped, tree-shakeability, dependencies, ESM/CJS detection). This distinguishes it from sibling tools like scan_dependency, which focuses on dependencies but not bundle size. The verb 'analysis' is implied and the resource is the npm 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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or scenarios where another tool might be more appropriate (e.g., 'Use scan_dependency for dependency vulnerabilities'). The usage context must be inferred solely from the tool name and description.

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 context beyond the annotations: it discloses the OAuth requirement, the persistence limitation for anonymous/BYO accounts, phone verification and the 10/day SMS cap, and the always-on feed behavior with an endpoint to pull from. It also states the return value. These details are not present in the annotations (which only declare readOnly=false, idempotent=true, etc.) and are useful for invoking the tool safely. No contradiction with annotations.

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

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

The description is a single dense paragraph, but it is well-organized: it starts with the core action and return value, then covers prerequisites, supported types with examples, and delivery channels. Each sentence contributes operational information. However, it is long and could be broken into bullet points for scanability; it also omits webhook from the main text (though the schema covers it).

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 nested objects, enums, and multiple delivery options, the description is highly complete: it covers prerequisites, all three delivery channels (feed, email, sms) with constraints, and the return value. Missing webhook details are fully supplied by the schema, and output schema is absent but the description names the returned subscription id. Sibling tools fill the management side (list/unsubscribe), so the description adequately scopes this tool.

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

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

The schema already documents all parameters (100% coverage), so baseline is 3. The description adds meaningful semantic details beyond the schema: it explains that item code '5.02' means officer change for sec_8k, and it adds the SMS delivery cap (10/day) and verification step, which are not in the schema. These extras elevate the contribution above baseline.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' – a specific verb+resource that clearly distinguishes this from sibling tools like list_subscriptions and unsubscribe. It also states the return value ('Returns the new subscription id'), reinforcing the create-and-return purpose.

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

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

It provides clear prerequisites (Requires a Pipeworx OAuth account; anonymous + BYO cannot persist subscriptions) and explains when each subscription type is appropriate with concrete examples (e.g., items:['5.02'] = officer change). It also mentions alternative consumption methods (recent_alerts or GET registry.pipeworx.io/alerts.json) for the always-on feed, giving context on how the feed is used. However, it does not explicitly contrast with alternative tools like list_subscriptions or unsubscribe, though the sibling list implies those exist.

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, open-world behavior. The description adds valuable context beyond that: output consists of category-bucketed examples with tool/argument shapes, drawn from a live catalog, and that it can be called with or without arguments. It does not contradict annotations and provides useful behavioral 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 a single dense paragraph but front-loads example queries and the core purpose before getting into mechanics. Every clause contributes meaning, and the progression from 'what this is' to 'how to call' is logical. It is longer than strictly necessary 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?

For a tool with no output schema, the description does a good job explaining what the returned data will contain (category-bucketed examples with exact tool/argument shapes) and how to invoke it. It also mentions the live-catalog source and meta-tools. It doesn't specify the exact JSON structure, but given the tool's simple purpose and good annotations, this is adequate.

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

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

Schema coverage is 100% for the single 'topic' parameter, which already lists valid values. The description adds meaning by explaining the no-argument case ('Call with no arguments for the full spread') and giving concrete examples ('finance', 'pharma', 'betting') that align with the schema. This goes beyond the schema's description.

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: 'Returns category-bucketed example questions... each with the exact tool + argument shape that answers it.' It identifies itself as 'the onboarding entry point' and gives concrete example queries, distinguishing it from sibling tools by positioning it as the first thing to call when unfamiliar with the system.

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

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

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two calling modes: no arguments for the full spread, or pass a topic to focus. This clearly tells the agent when and how to use it.

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

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

The description discloses important behaviors beyond the annotations: ownership enforcement, deactivation instead of deletion, and the preservation of historical events. This aligns with destructiveHint=false and adds context about the actual state change.

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 purpose, and each sentence adds distinct value (purpose, ownership, side effect). No wasted words.

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

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

For a single-parameter mutation tool with clear annotations, the description covers purpose, constraints, and post-condition behavior. It also references the related 'recent_alerts' tool, providing enough context for an agent to decide 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 covers 100% with a clear description of the 'id' parameter ('Subscription id (uuid) returned by subscribe'). The description doesn't add extra parameter semantics beyond restating 'by id', 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 uses a specific verb ('Cancel') and resource ('subscription') and clarifies the action as deactivating rather than deleting. It distinguishes itself from siblings like 'subscribe' and 'recent_alerts' by stating the effect on historical events.

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 states ownership enforcement ('you can only cancel your own subscriptions'), which is a key usage constraint. It references 'recent_alerts' as a way to keep historical events, but doesn't explicitly contrast with list_subscriptions or other alternatives. The guidance is clear but could be more explicit about when not to use.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses key behaviors: the special meaning of 'could_not_verify' (not evidence, includes verification_error), the difference between that and 'unsupported', and the automatic routing logic. This goes well beyond the annotations and provides essential context for interpreting results.

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

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

The description is long but dense. Every section earns its place: trigger phrases, routing logic, return values, and the critical caveat about 'could_not_verify'. The 'IMPORTANT for callers' call-out improves scannability. Slightly verbose but justified given the tool's complexity.

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

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

Despite having no output schema, the description fully details the returned verdict set, the error field, and the difference between 'could_not_verify' and 'unsupported'. It covers both routing paths and the replacement claim. This is complete for an agent 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?

The schema already covers both parameters with descriptions, so baseline is 3. The description adds extra semantics for 'tolerance_pct' (overrides implied tolerance, default behavior, recommended values for hallucination detection), which is valuable 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's purpose: natural-language claim verification against authoritative sources, with specific trigger phrases. It distinguishes itself from siblings by describing its two verification paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else) and its single-call replacement of a multi-step 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear when-touse guidance. It also explains the two routing paths, but doesn't explicitly list 'when not to use' or recommend alternative tools for edge cases (e.g., non-factual queries).

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