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 readOnly and idempotent, so the description adds value by explaining the routing behavior, citation URI output, and 'one fast call' performance. It goes beyond the safety profile without contradicting 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?

Front-loaded with 'PREFER OVER WEB SEARCH' and packed with high-value content: triggers, exclusions, examples, and escalation paths. Each sentence earns its place despite the length, making it dense but 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 complex tool with no output schema, the description covers the return format (structured answer with citations), source scope, typical use cases, and when to escalate to sibling tools. It omits error handling or result limits, but that is not critical for a query tool with clear guidance.

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

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

Schema description coverage is 100% and the description does not add additional meaning beyond the schema's aliases and natural-language field. The example questions in the description mirror the schema examples, so the description relies on the schema to define parameters.

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

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

The description clearly states it routes questions to 5,529 tools across verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly marking itself as the default entry point ('START HERE') and contrasting with ask_pipeworx_grounded and deep_research.

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

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

Provides explicit usage triggers ('Use whenever the user asks "what is", "look up"...') and concrete examples. It also states when not to use it and names alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.'

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

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

Beyond the annotations (readOnlyHint=true, etc.), the description discloses key behavioral traits: it is experimental, may have candidate routing improvements enabled live, and currently matches ask_pipeworx exactly. This adds significant value over the annotations by explaining the operational context and the comparison mechanism.

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 well-structured sentences that are information-dense without fluff. It front-loads the key facts (beta, identical, candidates), then provides current status, usage direction, and a final clarifying statement that it is a full router. 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?

The description is complete for a tool with a single required parameter and no output schema. It specifies the exact relationship to ask_pipeworx (identical, same response shape), explains the experimental nature, and gives current status. The agent has enough context to use it correctly without needing additional details.

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 six parameters (all aliases for 'question'). The description adds no additional parameter insights, but this is acceptable because the schema fully documents the parameters. The phrase 'same arguments' refers to ask_pipeworx but does not introduce new semantics.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It explicitly distinguishes itself from the sibling tool ask_pipeworx by highlighting the experimental routing improvements and the fact that it is a full working router.

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 it exactly like ask_pipeworx when you want the newest routing' and explains the beta's purpose (results compared against the stable router). It also clarifies that it is not a fallback ('Falls back to nothing'), which helps avoid misuse.

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

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

The description adds significant behavioral detail beyond the annotations: it reveals the return structure with evidence, refusal_reason enums, and the one-extra-LLM-call cost. The refusal behavior (explicit refusal when data doesn't directly answer) is disclosed, which is valuable for an agent relying on this tool. Annotations already indicate readOnly/openWorld, but the description enriches this with concrete 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?

The description is dense but well-structured: it starts with the core purpose, explains the mechanism, then details the output contract, usage guidance, and cost tradeoff. Some specifics like '5,529 across 1455 sources' add flavor but are not essential; however, they do not detract significantly. Overall it earns its length through high information density.

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 present, the description fully documents the return format: the success object fields and the refusal object with enumerated refusal_reason values. It also clarifies the tool's routing mechanism and the extra call cost. Together with the sibling distinction and usage guidance, this description is complete for an agent to invoke it correctly without additional knowledge.

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

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

The input schema has 100% description coverage across all six parameters (where five are aliases of 'question'). The description adds no additional parameter semantics beyond what the schema provides, but it does not need to because the schema is complete. Per the rubric, baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and contrasts with ask_pipeworx by emphasizing that it EXTRACTS the answer using ONLY what the tool result contains. This specific verb+resource and explicit behavioral distinction from the sibling tool make 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 when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also states when not to use it ('prefer ask_pipeworx for casual lookups') and explains the cost tradeoff. This is model-level guidance with clear alternatives.

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

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

The description goes far beyond the annotations, 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 declare readOnly/openWorld/idempotent/non-destructive, but the description adds critical context: account gating, paid tier for 'thorough', decomposition and parallel routing, findings packet with gaps[] and contradictions[], stable citation_uri, semantic excerpting, and latency. These go beyond annotations and shape invocation 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 long but each sentence adds a distinct point — account gating, tool characteristics, use cases, exclusions, depth behavior, citation guarantees, and performance. It is front-loaded with the most actionable constraint (account required) and structured to move from definition to guidance to 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?

Given no output schema, the description thoroughly explains what the caller receives: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps, contradictions, and hop field. It also covers both parameters, latency, and prerequisite auth, making it self-sufficient for a complex tool.

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

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

The schema already provides 100% coverage for both parameters, so baseline is 3. The description adds nuance to 'depth' by explaining the 'standard' gap-recovery hop and 'thorough' lead-chasing iterative pass, and to 'question' by stating broad/multi-part questions are fine. This slightly elevates the semantics beyond the schema text.

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

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

The description opens with 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and immediately contrasts with open-web search, then distinguishes from ask_pipeworx for single lookups and breaking news. This clearly states the verb (research), resource (structured data sources), and scope (multi-facet), making it distinct from siblings.

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

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

Explicitly states 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and for breaking news 'prefer ask_pipeworx'. It also outlines the account requirement and fallback if not signed in, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, 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 cover readOnly/idempotent/destructive semantics; the description adds valuable behavioral context: it fans out across multiple sources, returns up to 5 filings with URI format, sorts fundamentals by period_end DESC, notes the USPTO PatentsView API sunset with soft-fail, and describes the GDELT→GNews fallback. 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 and every section earns its place: usage examples, core definition, return fields, and input constraints. It is longer than average but not wasteful, though the input parameter section repeats the schema nearly verbatim, slightly reducing conciseness.

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

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

With no output schema, the description thoroughly explains return values (fields, counts, URIs, sorting, fallbacks) and limitations (patent API sunset, name unsupported). It also covers data sources and parallel-call nature, making it complete for a complex cross-source 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% and both parameters (type, value) are well described in the schema. The description repeats the same input constraints ('ticker or zero-padded CIK', 'names not supported') without adding meaning beyond the schema. Baseline 3 is appropriate since the schema carries the semantic weight.

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 produces a 'full cross-source profile of a US public company in ONE parallel call' and lists specific return fields (cik, recent_filings, fundamentals, patents, news, LEI). It distinguishes from sibling tools by explicitly saying to prefer it over chaining single-pack lookups and referencing resolve_entity for names.

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

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

Provides explicit when-to-use signals: example user intents ('Tell me about X', 'research Acme'), a directive to 'ALWAYS PREFER' this over chaining single-pack SEC/XBRL/news lookups for holistic views, and a clear exclusion ('names not supported — use resolve_entity first'). This gives an agent unambiguous selection criteria.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral detail: it explains response format, compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type/subtype counters. This goes far beyond the annotations, revealing edge cases where spreads are meaningless.

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

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

The description is well-structured with clear section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. It is long but every sentence carries substantive information about behavior, safety, or limitations. It could be slightly tighter, but the detail 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?

There is no output schema, so the description carries the burden of explaining return values. It covers the response format (leg-by-leg prices, spread[].top_spreads_pp), safety fields (compatibility_warning cases), temporal alignment, and skip counters. This is complete for a complex tool with potential mismatches and provides the agent enough context to handle edge cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how the three parameters interact (topic vs explicit override) and lists the 10 pre-mapped topics. It also clarifies the response structure enough to infer the parameters' roles, though the schema already documents the overrides.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison rather than intra-venue or edge detection.

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

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

The description explains two operational modes (topic shortcuts vs explicit pairing) and provides cautionary guidance that pre-mapped topics are often not tradeable ('pre-mapped ≠ tradeable'). It does not explicitly name alternative tools for when not to use this tool, but it gives clear context on when the tool is appropriate and how to interpret its safety warnings.

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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the source context (bundlephobia.com) and intent, but does not disclose details like result limits, pagination, or what 'most recently' means in terms of time window.

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

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

The description is a single, front-loaded sentence that conveys the action, resource, and context without any fluff. 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 zero-parameter, read-only tool with an output schema, the description is sufficiently complete. It explains what the tool returns and why it matters, leaving return structure to the output schema. The only minor gap is the ambiguity around the recency window.

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?

There are zero parameters, so the schema carries no semantic load. The description correctly introduces the tool's purpose without needing to explain parameters, earning the baseline score for no-param tools.

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

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

The description states a specific verb ('Return') and resource ('list of npm packages most recently measured on bundlephobia.com'), clearly distinguishing this from sibling tools like 'recent_alerts' or 'recent_changes'. It also adds context about 'community interest in bundle-size analysis'.

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

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

The description implies usage for gauging recent community interest, but does not explicitly state when to use this tool versus alternatives. No exclusions or direct comparisons to sibling tools are provided.

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?

Description adds valuable behavioral context beyond annotations, such as the cascade through multiple lookup endpoints, graceful degradation of LEI/FIGI enrichment, explicit declaration of unresolved identifiers under 'unresolved', and source attribution for each identifier. These details help the agent anticipate partial failures and output structure.

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

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

The description is long but densely packed with essential details. It's front-loaded with user query examples that make intent obvious, then systematically covers both types, return values, and failure modes. Some redundancy exists (e.g., repeating 'LEI' and 'FIGI' multiple times), but no sentence is wasted.

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

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

Despite lacking an output schema, the description thoroughly explains what the tool returns: canonical identifiers, source labels, unresolved items, and ownership hierarchy. It also covers edge cases like graceful degradation, making it self-sufficient for an agent to understand expected behavior and possible partial 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 schema already documents both parameters, but the description enriches them with concrete examples (ticker AAPL, CIK 0000320193, drug names) and clarifies the accepted input formats for each type. This goes well beyond the baseline schema coverage of 100%.

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

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

The description explicitly defines the tool's function with action verbs: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also provides concrete query examples and distinguishes between company and drug types, clearly differentiating it from siblings like entity_profile which would provide profiles rather than ID resolution.

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

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

It provides explicit instruction: 'Use FIRST whenever you have a name but need an ID.' This is clear context for when to invoke. However, it doesn't explicitly mention alternative tools or when not to use it, though it implicitly covers trade-offs with 'replaces 2-3 manual lookups.'

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

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

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.