Reactome

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond that: the default model is free (Workers AI Llama-3.3-70b), using Anthropic requires a BYO key with direct costs to the user, and the output includes per-model details. There is no contradiction with 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 three sentences long, front-loaded with the core purpose, then model options and output structure, and finally use cases. Every sentence contributes meaning without redundancy or fluff.

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

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

Despite having no output schema, the description explicitly lists the return fields per model (score, confidence, signals, raw_response) and mentions a combined view. It also covers cost behavior, default model, and practical use cases. For a 4-parameter tool with these annotations, this is fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema: it clarifies that `models` can be omitted for the default workers-ai, `_apiKey` is only needed if 'anthropic' is in models, and that providing a key incurs Anthropic charges. This enriches the parameter understanding beyond the raw field descriptions.

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

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

The description states the tool 'probes one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb ('probe') tied to a clear resource (LLMs about an entity) and output (visibility scores). It distinguishes itself from sibling tools by focusing on cross-model visibility scoring rather than general Q&A or entity resolution.

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

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

The description gives concrete usage contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This clearly implies when to use the tool, but it does not explicitly name alternatives or exclusion criteria. Since no sibling alternatives are referenced, it stops short of the highest standard, but the context is clear.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds genuine behavioral context: it routes to the right tool, fills arguments, returns structured answers with citation URIs, works on every tier, and is a single fast call. It doesn't discuss failure modes or edge cases, but it goes well beyond simply restating 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 relatively long but well-structured: the key preference statement is front-loaded in caps, followed by the data domains, trigger phrases, examples, and explicit escalation guidance. Nearly every sentence earns its place, though the list of data categories is slightly redundant with the general 'current or historical data' phrase.

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 default router tool with no output schema, the description is remarkably complete. It explains the return type (structured answer with citation URIs), scope (current/historical data), tier support, and when to escalate to sibling tools. This gives an agent all the context needed to select and invoke the tool correctly.

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

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

All six schema parameters have descriptions, including aliases for the question field, so schema coverage is 100% and the baseline is 3. The description offers example question values, but it adds no parameter-level semantics beyond what the schema already defines in detail.

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

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

The description clearly states that ask_pipeworx routes questions to one of 5,462 tools across 1,419 verified sources and returns structured answers with stable pipeworx:// citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its purpose and scope unmistakable.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and provides concrete trigger phrases like 'what is', 'look up', 'find', and 'get the latest' along with example queries. It explicitly states 'START HERE for most questions' and names alternatives for specific needs: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions.

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 key behavioral trait that routing improvements are enabled live whenever a candidate is under test, and that the last candidate was retired. It also states this is a full working router with no fallback, adding meaningful context beyond the readOnly/openWorld/idempotent annotations.

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

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

The description is somewhat long but information-dense, conveying beta status, current state, usage, and comparison to the stable router. Every sentence contributes to understanding, though it could be tightened (e.g., the specific retirement date is extra detail).

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

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

Given the complexity of a universal router with 5,462 tools and no output schema, the description sufficiently covers what the tool is, its current experimental status, its relationship to ask_pipeworx, and its response shape. It gives an agent enough context to use it correctly as an experimental alternative.

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 all 6 parameters, each defined as an alias for 'question'. The description only briefly mentions 'same arguments' as ask_pipeworx, adding no new parameter-specific meaning beyond what the schema contains. Baseline 3 is appropriate.

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

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

The description explicitly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded by being the experimental edge with candidate routing improvements.

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

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

It provides clear usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router and notes that results are compared to decide merges, plus clarifies that when no candidate is active it currently matches ask_pipeworx exactly.

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?

Behavioral transparency is excellent. It discloses that the tool extracts answers only from tool results, returns a structured response with evidence and confidence, and explicitly returns refusals with specific reasons (not_in_source, no_tool_match, etc.). This goes well beyond the annotations' readOnlyHint and openWorldHint, adding critical context about failure modes and grounding. 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 well-structured, front-loading the core value proposition and then detailing behavior, use cases, and tradeoffs. It is longer than ideal, but every sentence contributes information not available elsewhere (e.g., refusal reasons, cost comparison, use-case guidance).

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

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

The description is remarkably complete for a tool with no output schema. It explains the return shape, refusal variants, success/failure conditions, and the rationale for choosing this tool over alternatives. Given the complexity of routing across 5,462 tools and handling high-stakes queries, this fully satisfies the need for contextual 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?

The input schema already covers all six parameters (all aliases of 'question') with clear descriptions, achieving 100% schema description coverage. The tool description adds little about parameter semantics beyond saying the tool 'fills arguments' internally, implying the user only supplies a natural language question. This is adequate but does not meaningfully supplement 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 this is a 'Hallucination-resistant answer mode for high-stakes reads' that routes through the same tool selection as ask_pipeworx but extracts answers using only the tool result. It distinguishes itself from the sibling ask_pipeworx by emphasizing groundedness and refusal behavior, making the purpose and unique value explicit.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and provides a clear exclusion: 'prefer ask_pipeworx for casual lookups.' It also explains the tradeoff (costs one extra LLM call), which further informs tool selection.

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

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

Beyond the read-only/open-world/idempotent annotations, the description discloses extensive behavioral details: fan-out to category-specific data packs, resolver contract with market_match_confidence, parent_event extraction, news fallback fields (_fallback_attempted), safety short-circuits for low-confidence or closed markets, illiquidity flags, and resolution-rule risk parsing. No contradictions with annotations.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and a front-loaded purpose. Each section contributes functional details that help an agent use the tool correctly. While verbose, the organization makes it navigable and the length is justified by the tool's complexity.

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

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

With no output schema, the description thoroughly documents return shapes (result.market, result.analysis, result.evidence), the resolver contract, parent_event extraction, safety statuses (low_confidence_match, market_closed_or_inactive), and resolution-rule risk. It covers edge cases like GDELT 429s, wide spreads, and flat-50¢ void settlements, providing enough context 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?

The input schema already provides complete descriptions for all three parameters (market, depth, include_raw) with examples, defaults, and enums. The tool description repeats the market format and gives examples of depth's effect ('quick = 2-3 evidence sources') but adds no substantial meaning beyond the schema. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the action (research/pull data), and includes example use cases like 'should I bet on X'. It distinguishes itself from sibling tools that focus on arbitrage, edges, or tracking by concentrating on single-bet 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?

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives concrete fan-out examples for various bet types. It does not explicitly name alternative tools for exclusion, but the context and examples make it clear when this tool is appropriate.

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

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

Annotations already declare readOnly/openWorld/idempotent safety. The description adds meaningful behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and citation URIs. It doesn't address limitations like latency or data availability, but the added context is solid.

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 front-loaded with query examples, but it is longer than strictly necessary. Every sentence contributes useful information, and the structure flows from usage to data details to output format, earning 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?

For a tool with no output schema, the description covers input constraints, data fields per type, sorting behavior, return format (paired data + citation URIs), and efficiency benefit. This is enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches both parameters: type is explained with per-enum data details, and values gets explicit examples, count constraints, and formatting guidance (ticker/CIK vs drug names). This goes well beyond the basic schema descriptions.

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

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

The description clearly identifies the tool as a side-by-side comparison for 2–5 companies or drugs in one parallel call, with concrete query examples ('X vs Y', 'rank these companies'). It distinguishes from sequential single-pack lookups by emphasizing 'ALWAYS PREFER' and 'Replaces 8–15 sequential lookups', and from sibling tools by specifying a unique comparison 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?

Explicitly states when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides usage scenarios via example queries. It also clarifies the two modes (company vs drug) and what data each pulls, giving clear contextual guidance.

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

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

Goes far beyond annotations, disclosing account plan requirements, parallel tool routing, gaps[] behavior (never invented), citation availability, contradictions[] for certain depths, semantic excerpting, and expected latency. Annotations already mark readOnly/openWorld/idempotent, and the description adds rich operational context without contradicting those 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?

Although long, every sentence earns its place: account prerequisite, core operation, comparisons to alternatives, depth semantics, output format, and performance expectations. It is front-loaded with the most critical caveats (account, not open-web) before detailed behavior. No fluff or repetition.

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

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

No output schema exists, so the description must explain return values and does so: 'findings packet: verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers error cases (empty gaps), citation resolvability, contradictions, timing, and account restrictions, making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema by explaining implications of depth values (e.g., thorough is paid, standard re-angles gaps, contradictions appear for standard/thorough) and giving example questions. This is meaningful, though partially redundant with the schema's own depth descriptions.

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

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

The description clearly states what the tool does: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources ... in ONE call' with specific verbs and resources. It distinguishes from siblings by explicitly noting 'this is NOT open-web search' and from ask_pipeworx as the multi-faceted research alternative.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when not to use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also notes account requirement and fallback to ask_pipeworx if not signed in, plus alternative tools for open-web topics.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by detailing what the tool 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.' No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and includes actionable usage guidance. The long list of data categories is useful for scoping the tool's coverage, though the list of synonyms ('browse, search, look up, or discover') is slightly redundant. Overall, it is appropriately sized for a discovery tool.

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

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

The description is complete for a discovery tool with no output schema. It explains what it returns (top-N relevant tools, names, descriptions, full input schemas, curated examples), states that results are directly callable, and provides clear 'when to use' guidance. The schema covers all parameters, and the description fills the return-value gap adequately.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much beyond the schema for parameters; it only reinforces the query concept ('describing the data or task'). The schema itself already documents the 'query' field and its aliases with examples, so the description adds marginal value.

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 a specific verb and resource: 'Find tools by describing the data or task,' and further elaborates with concrete domains (SEC filings, financials, FDA drugs, etc.). It distinguishes itself from sibling tools by emphasizing 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 context: 'Use when you need to browse, search, look up, or discover what tools exist for...' and prescribes 'Call this FIRST...' when many tools are available. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough to guide an agent.

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

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

Beyond the annotations (read-only, idempotent), the description discloses important behaviors: parallel fan-out across sources, the USPTO API sunset and soft-failure, GDELT→GNews fallback, and sorted fundamentals. These details are not in the annotations and provide meaningful operational context for the agent.

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

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

The description is relatively long but every sentence serves a purpose: example queries, preference directive, source enumeration, return fields, and name limitation. It is front-loaded with the primary use case and structured logically. No filler or repetition.

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

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

Given the tool's complexity, absence of an output schema, and multiple data sources, the description is exceptionally complete. It details the return values (cik, filings, fundamentals, patents, news, LEI), ordering, fallbacks, and constraints. An agent can confidently invoke the tool without needing additional context.

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

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

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by providing concrete examples (ticker "AAPL", zero-padded CIK "0000320193") and reiterating the name limitation, which reinforces the parameter semantics beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's function: producing a full cross-source profile of a US public company in one parallel call. It distinguishes itself from siblings by explicitly preferring it over chaining multiple single-purpose lookups, and it enumerates the specific data sources and return fields.

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

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

The description provides explicit when-to-use guidance, instructing to prefer this tool for holistic profiles over chaining lookups. It also gives a clear when-not-to-use: when only a name is provided, directing users to resolve_entity first. This properly frames both the intended use and exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds context about clearing sensitive data and that memories were previously saved by the agent, but doesn't disclose additional behaviors like return values or error handling.

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

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

Two sentences, front-loaded with the verb and object, no filler. The pairing note and usage conditions are concise and relevant.

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 destructive operation with idempotent annotation, the description covers purpose, trigger conditions, and relationship to related tools. It is complete for the tool's complexity even without an output schema.

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

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

The input schema covers 100% of the parameter with a description ('Memory key to delete'). The tool description simply says 'by key,' which adds no new semantic detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' identifying the specific action and resource. It distinguishes itself from sibling tools like remember and recall by naming them as companions, implying its complementary role as the deletion 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?

It gives explicit when-to-use guidance: stale context, completed tasks, or clearing sensitive data. It also mentions pairing with remember and recall, but does not explicitly state when not to use it or name alternatives beyond these collaborators.

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 value by disclosing that it fetches the page, extracts specific elements, and emits a markdown blob, which are behavioral traits not covered by the annotations. It doesn't mention error handling or edge cases, but given the strong annotation coverage, a 4 is appropriate.

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

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

The description is three sentences, front-loaded with the core purpose, followed by process details and use cases. It contains no fluff or redundant information, 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 (2 well-documented params, strong annotations, no output schema), the description adequately covers what the tool does, how it works, and when to use it. The output format is specified ('single text blob'), making this complete for its scope.

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

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

Both parameters (url and max_links) have complete descriptions in the schema, achieving 100% coverage. The tool description adds little new meaning about parameters—it mostly restates what the schema already says (e.g., 'any URL'). With high schema coverage, the baseline is 3, and the description does not elevate it further.

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 generates a 'production-ready llms.txt file' for any URL, and explains the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This specific verb-resource combination distinguishes it from siblings like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description includes a 'Useful for:' section listing three concrete scenarios (client indexing, drafting for own project, competitor auditing), which provides clear context on when to use it. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing that it lists only the caller's subscriptions (scoping) and by enumerating the returned fields (id, type, params, created_at, last_fired_at, fire_count). 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?

Two concise sentences: the first states the action and return value, the second gives usage guidance. No wasted words, and the most critical information (what it lists) is front-loaded.

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

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

For a simple list tool with no output schema and minimal parameters, the description is complete. It explains what is returned, that it is scoped to the caller, and why you would use it (review monitoring or find id to cancel). No significant gaps given the tool's simplicity.

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 include_inactive parameter already having a clear description in the schema. The tool description does not repeat or add extra meaning to the parameter, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'List' and identifies the exact resource: 'the caller's active subscriptions'. It also mentions the return fields, making the purpose unmistakable. While it doesn't explicitly name sibling alternatives, the resource and action clearly differentiate it from subscribe/unsubscribe and other 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?

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and a practical use case, though it does not mention when not to use it or alternatives.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, covering safety. However, the description adds no behavioral traits beyond that, such as return behavior, ordering, or limitations. It simply states purpose, which is already evident from the name and schema.

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

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

The description is extremely concise at five words, with no wasted language. It front-loads the core concept, though it may be too terse to serve as a strong standalone definition.

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 a rich schema (100% param coverage), output schema, and annotations, the description can be minimal. However, it lacks usage context, examples, or any differentiation from siblings, making it only minimally complete for safe invocation.

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

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

The input schema describes both parameters with 100% coverage ('Source Reactome event id' and 'Target species'). The description does not add extra semantic meaning beyond the schema, but the schema itself is sufficient, 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 'Orthologous pathways/reactions in another species' clearly indicates the resource (orthologous pathways) but lacks an explicit verb like 'get' or 'find'. It distinguishes from siblings like 'pathway' by mentioning 'in another species', but the noun-phrase construction leaves the action implied.

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

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

No guidance is provided on when to use this tool versus alternatives. The sibling list contains related tools like 'pathway' and 'pathways_for_entity', but the description gives no context for choosing this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no behavioral context beyond the annotations, such as output format, rate limits, or any special behavior. No contradiction, but no added 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 extremely short, but this is under-specification rather than conciseness. It is a fragment with no sentence structure or useful information, providing no value despite its brevity.

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?

Although an output schema exists, the description does not leverage it. With one required parameter and a vague purpose, the description is far from complete for an agent to invoke the tool correctly. It fails to explain what the tool returns or how the input relates to the output.

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

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

With 0% schema description coverage, the description must compensate for the 'id' parameter, but it does not. It is unclear whether 'id' refers to a pathway ID, participant ID, or entity ID. The description gives no hint about what value to pass or how it is used.

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 'Entity participants of a pathway' is a noun phrase without a verb, making it unclear what action the tool performs. It vaguely hints at retrieving participants but does not specify whether it lists, gets, or resolves them, and it does not distinguish from sibling tools like 'pathway' or 'pathways_for_entity'.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or any exclusions. Given the sibling tools, there is no indication how 'participants' fits into the broader toolset.

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 the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds context about the stable id requirement and the 'full' nature of the record, which is useful. However, it does not disclose rate limits, error behavior, or the structure of the returned data beyond what the output schema presumably provides.

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, directly stated sentence that is front-loaded and free of any redundant information. Given the simplicity of the tool (one parameter), it is appropriately sized and 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?

The tool has one parameter, an output schema, and comprehensive annotations. The description sufficiently explains the input and the nature of the response ('full pathway record') for a simple lookup. It could mention potential failure modes or the specific domain of the stable id (Reactome), but with the output schema and annotations present, the description is largely complete.

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

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

The input schema provides only a parameter name and type with no description, and the schema description coverage is 0%. The description compensates by clarifying that the 'id' is a stable pathway identifier and gives a concrete example (R-HSA-68886). This significantly aids the agent in understanding what value to supply, even though it could offer more detail about the id format or source.

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 that the tool retrieves a full pathway record using a stable identifier, with a concrete example. It distinguishes itself from sibling tools like 'pathways_for_entity' by emphasizing the full record for a single pathway. However, it lacks an explicit verb (e.g., 'Get' or 'Return'), which prevents a perfect score.

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

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

No explicit guidance is given on when to use this tool versus the many sibling tools such as 'pathways_for_entity' or 'entity_profile'. The phrase 'by stable id' implies usage when the agent has a stable identifier, but there is no mention of alternatives, exclusions, or specific scenarios. This is essentially no guidance beyond the basic 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context beyond what the schema provides (e.g., citing external resource id). With annotations covering the safety profile, the description meets the baseline but does not enrich transparency with details like return variability or pagination.

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: 'Pathways containing an entity, looked up by external resource id (e.g. UniProt accession).' Every word earns its place, no redundancy or filler.

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

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

The tool is a simple read-only lookup. It has a rich input schema, annotations for safety, and an output schema. The description, while brief, tells the agent what it does and the input style. It is sufficiently complete for this complexity level, though it could mention that multiple pathways may be returned, but the openWorldHint and output schema mitigate this.

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 has 100% coverage: all three parameters (species, resource, entity_id) are described with defaults and examples. The description only reinforces the entity_id example (UniProt accession), adding no extra semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description states the tool finds pathways containing an entity via external resource id, with a concrete example (UniProt accession). This clearly differentiates it from siblings like 'pathway' (which likely fetches a specific pathway) and 'participants' (which lists entities in a pathway). The verb 'containing' and resource scope are specific.

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

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

The description implies usage context: use this when you have an external resource identifier and need to find associated pathways. It does not explicitly state when not to use or mention alternatives, but the context is clear enough for a simple lookup tool.

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

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

All annotation hints are false, so the description carries the full transparency burden. It discloses rate limiting (5/identifier/day), quota exemption, daily digest processing, and that incorrect filing delays the user. It does not explicitly describe the return/confirmation behavior, but the essential side effects and constraints are clear.

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

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

The description is longer than average but stays focused: each sentence covers use-triggers, scope boundary, content rules, or operational constraints. No filler or redundancy; the density is justified by the tool's nuanced filing criteria.

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 feedback tool with no output schema, the description covers the complete workflow: why it exists, when to file, what to include, scope limits, rate limit, quota impact, and that the team reads digests daily. With full schema parameter documentation, there are no critical gaps 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 covers all parameters at 100%, providing baseline 3. The description adds value by explaining how to populate message content (describe via Pipeworx tools/packs, don't paste end-user prompt) and when to choose bug vs feature vs praise, going beyond schema descriptions. Context parameter's purpose (pack/tool/vertical) is implied by 'in terms of Pipeworx tools/packs'.

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

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

Description opens with a specific action and resource ('Tell the Pipeworx team'), enumerates feedback categories (broken, missing, praise), and explicitly restricts scope to Pipeworx-served tools, distinguishing it from all sibling query/research tools. Clear differentiation from siblings that all do data retrieval.

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 triggers (wrong/stale data, missing tool, praise) and an explicit exclusion: if the tool came from a different MCP server, file it there instead. Also gives formatting guidance (use Pipeworx tool/pack names, avoid end-user prompts) and rate-limit/quota context, covering both use and non-use cases.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses behavioral traits: self-aggregating, derived from CF analytics-engine, no PII, caching behavior (5min-1h), and output structure (pack, tool, count). This adds valuable context not present in structured data.

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

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

The description is front-loaded with a clear opening sentence, followed by a well-structured list of use cases and a final note on data characteristics. It is slightly verbose but every sentence contributes useful information, earning a strong score.

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

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

For a read-only tool with one optional parameter and no output schema, the description is thorough: it clarifies what is returned, why it is useful, how data is sourced, and its freshness. No important aspect is left unaddressed.

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

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

Schema description coverage is 100%, with the window parameter fully explained in the schema (enum values and tradeoffs between windows). The description only briefly mentions the window in passing without adding any new semantics, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool returns trending data ('top tools, top packs, and total call volume') from 'other AI agents' calling on Pipeworx. It distinguishes from sibling tools like ask_pipeworx (question answering) and discover_tools (discovery) by focusing on aggregated call trends.

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

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

The 'Useful for' section explicitly lists three concrete scenarios (discovering hot data sources, confirming canonical tool, checking alignment). It provides clear context but does not explicitly mention when not to use it or name alternative tools, keeping it slightly below the highest tier.

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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral context: partition filters, placeholder check, fill check with realizable edge explanation, and a direct warning 'do not trade it' when the edge is not realizable. This far exceeds the baseline.

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 long, the description is meticulously structured: leading summary, then mode-by-mode breakdown, with bolded section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) improving scannability. Each sentence contributes distinct information—no filler or repetition.

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

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

Given no output schema and complexity, the description fully compensates by describing response shapes (opportunities[], partition_check{}), edge cases, and recommended actions. It also contextualizes the tool among siblings and covers failure/skip conditions, making it self-sufficient for an agent.

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

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

Schema coverage is 100% with meaningful property descriptions, but the tool description goes well beyond: it gives concrete examples (e.g., 'fed-decision-may-2026'), explains what each mode does with those parameters, and describes the no-arg behavior. This adds substantial semantic depth.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by detailing its three modes (no-args, event, topic) and relation to other Polymarket 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?

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event... or topic'. It even recommends event mode for specific markets, explains cross-event advantages, and points to 'polymarket_fill_risk' for custom sizing, setting clear boundaries with alternatives.

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

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

The description adds substantial behavioral context beyond the annotations: caching at KV level for 1 hour, edge computed net of slippage, Kelly caps at 0.25, Fed bet exclusion rationale, diagnostic funnel counters, and knob behavior. It aligns with the readOnly/idempotent annotations and provides rich detail about internal mechanics.

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 very long and dense, covering model family details, edge calculations, knobs, and response structure. It front-loads the core purpose well, but the extensive detail makes it less concise than ideal. While every detail has informational value, the length may overwhelm agents that need quick comprehension.

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

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

With no output schema, the description carries the full burden of explaining the return structure. It does this thoroughly: top-level by_segment keys, per-opportunity fields like edge_pp_net and kelly_fraction, diagnostics with funnel counters, and reasons for empty segments. This is comprehensive for a complex tool with 9 parameters.

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

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

Schema coverage is 100%, so each parameter has a detailed description. The tool description mentions the tradeable-edge knobs (min_liquidity, max_spread_pp) and min_partition_leg_kelly, but these are already explained in the schema. The description does not add significant semantic value beyond the schema, though it does reinforce the relationship between knobs and filter 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 clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It names the three response segments and three model families, effectively distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 a clear use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It indicates the intended context and gives details on filters and exclusions, but does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: 60-day snapshot TTL, snapshot gaps when no scan occurred, decay computed from daily closes (not intraday), and the response structure including expired opportunities. This is rich, non-obvious information that helps the agent anticipate behavior.

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

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

The description is long but well-structured, starting with a clear purpose, then args/response/limits. Every sentence earns its place, though the 'Args:' section somewhat duplicates schema information. Slightly verbose 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?

No output schema exists, so the description compensates by thoroughly explaining return fields (tracked[], expired[], snapshot_dates[]), their semantics, and edge cases (snapshot gaps, TTL limits). It also clarifies that decay is computed from daily closes. This is complete 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 params: days (lookback, default 14, clamp 2-30) and window (24hr | 1wk | 1mo, default 1wk). The description restates these defaults and adds the 'snapshot family' context, but adds no additional value beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling polymarket_edges by focusing on time-series tracking rather than raw edges, and differentiates fresh vs old 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: when you need to know edge persistence and decay. It explains the significance ('a fresh wide edge and a 3-week-old wide edge are different trades') and mentions the source (polymarket_edges snapshots). It doesn't explicitly name alternatives or exclusions, but the context strongly implies appropriate use cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description reinforces this without contradicting it. It adds significant behavioral detail beyond annotations: walks the order book ladder, returns specific fields like slippage_pp and max_fillable_usd, and discloses partial-fill risks and forced_directional_risk naming legs that could strand the user unhedged.

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 long, dense paragraph but every clause carries functional information. It is front-loaded with the purpose and required parameter, then details modes and outputs. A bit more structure (e.g., sections for single-market vs basket) would improve scannability, but it's not padded.

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 two modes, no output schema, and no required parameters, the description is exceptionally complete: it covers both modes, key return fields, default behaviors, edge risks, and the exact usage threshold. It also explains the dominant loss mode (partial basket fills) which gives the agent actionable context for when to invoke 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?

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains how size_usd is interpreted differently in single-market vs basket mode, how 'side' defaults in basket mode based on partition sum, and that market/event modes are mutually exclusive. This is far beyond what the schema provides.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by framing it as a pre-trade risk check rather than a signal finder.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk rationale (theoretical overround not capturable on thin books, partial fills convert arb into unhedged position), giving clear when-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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read operation. The description goes far beyond this by detailing edge cases: compatibility_warning fires under two distinct conditions, temporal_alignment flags when spreads are meaningless, and skipped_cross_type/subtype expose why leg-pair comparisons were dropped. It also discloses that most pre-mapped topics are not tradeable, warning of a potential false impression. 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?

Although the description is long, it is well-structured into clear sections (intro, modes, response, safety fields, temporal alignment, counters, warning). Every sentence conveys actionable information with no filler. The density is justified by the tool's complexity—two modes, safety fields, and caveats. It is front-loaded with the purpose and then details in a logical order.

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

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

With no output schema, the description must explain the return value, and it does thoroughly: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning semantics, temporal_alignment structure, and skip counters. It covers all major behavioral outcomes and caveats (e.g., non-equivalent bet shapes, temporal mismatch, unrelated events). The description is complete for a read-only, idempotent tool with three optional parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema: it explains the `topic` parameter is a shortcut (and lists all 10 values), and explicitly states that `kalshi_event_ticker` and `polymarket_event_slug` override the topic-mapped side. This clarifies the interaction between parameters, which the schema alone does not convey.

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

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

The first sentence states the tool's exact function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (Kalshi/Polymarket), the verb (compute spread), and the scope (same resolving question). It also distinguishes itself from siblings by emphasizing 'cross-venue,' which is different from intra-venue arbitrage tools like polymarket_arbitrage.

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

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

The description clearly explains two usage modes: macro shortcuts (`topic`) and explicit tickers (`kalshi_event_ticker` + `polymarket_event_slug`). It also provides strong 'when-not' guidance: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' However, it does not explicitly name alternative tools or contrast with siblings, so it misses the full bar for a 5.

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

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

Annotations already declare read-only, idempotent, and safe behavior. The description adds valuable context about the tool's scope ('Scoped to your identifier') and the two operational modes (retrieve vs. list all). This goes beyond the annotations without contradicting them, though it does not detail return format or error conditions.

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 concise sentences cover purpose, usage, scoping, and pairing with siblings. Each sentence delivers new information without redundancy. The examples are helpful, though the description could be slightly tighter without losing clarity.

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

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

For a simple tool with one optional parameter and strong annotations, the description is sufficiently complete. It explains the two output behaviors, usage context, and data isolation. It does not describe the return format, but given the simplicity and presence of annotations, this is a minor gap.

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 fully documented there. The description adds meaningful semantics by explaining that omitting the key triggers listing behavior and that the key refers to a previously saved memory. This enriches the schema's simple 'key' 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 two modes: retrieving a saved value and listing all keys. It explicitly names the related operations ('remember' and 'forget'), distinguishing it from siblings. The verb 'retrieve' and resource 'saved memory keys/values' 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?

Provides explicit when-to-use context: 'Use to look up context the agent stored earlier' with concrete examples. It also implicitly states when not to use it by mentioning alternatives ('Pair with remember to save, forget to delete'). This clearly directs the agent to the correct sibling for write/delete operations.

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 annotation readOnlyHint=true is contradicted by the description's explicit statement that setting mark_read:true flags returned events as read, modifying state. This is a direct contradiction. No other behavioral context compensates for this inconsistency.

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 compact paragraph. It front-loads the purpose, then concisely covers return contents, filtering, mark_read behavior, and polling suitability. Every sentence adds meaningful information without redundancy.

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

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

For a tool with 5 optional parameters and no output schema, the description covers return payload contents, filtering options, mark_read semantics, polling safety, and an alternative access URL. It lacks exhaustive edge-case details but is largely complete for practical use.

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

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

Schema coverage is 100%, so all parameters are documented. The description adds value by giving a concrete example for the type parameter (sec_8k) and explaining the cross-call effect of mark_read (next call only shows newer ones), which is not solely apparent from 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 pulls fired events from the subscription feed, using a specific verb and resource. It distinguishes from siblings like list_subscriptions by focusing on alert retrieval, and the mention of evaluator-written alerts adds specificity.

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: it is for retrieving recent alerts and is suitable for polling. It also mentions an alternative endpoint for scripts, but does not explicitly exclude other sibling tools or state 'use this instead of X'. Still, the intended usage is clear.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description goes well beyond by disclosing fan-out to multiple external APIs in parallel, the GDELT→GNews fallback, USPTO's soft-fail due to PatentsView sunset, and the return structure (changes[] grouped by source, total_changes, citation URIs). No contradictions with annotations.

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

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

The description is dense but well-structured: it starts with recognition patterns, defines the core behavior, enumerates sources with fallback details, and ends with the alternative tool. Every sentence contributes useful context without redundancy or padding.

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

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

Even without an output schema, the description covers the return format (structured changes[], total_changes, pipeworx:// citation URIs), source-level behavior, fallbacks, and parameter handling. It also positions the tool against entity_profile, making its scope fully understandable for an agent.

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

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

Schema description coverage is 100% — the schema already documents type, since, and value with format examples. The description repeats the `since` format and entity types but adds no new parameter-level meaning. Per the rubric, a high-coverage schema means a baseline of 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 natural-language queries and then explicitly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' listing sources (SEC EDGAR, GDELT/GNews, USPTO). It clearly distinguishes itself from the sibling entity_profile by contrasting the dynamic feed with the static profile.

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 concrete example phrasings for when to use the tool ('What's new with X' / 'latest on Y'), and explicitly directs users to 'Use entity_profile instead when you want the static profile...' It also describes fallback behavior (GDELT preferred, GNews on rate-limit/5xx), which informs usage decisions.

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 meaningful behavioral context beyond the annotations: memory is scoped by identifier, and persistence differs for authenticated vs anonymous sessions (permanent vs 24 hours). Annotations only indicate idempotence and non-destructiveness, so this extra context raises the score. It doesn't mention overwrite behavior, but the idempotentHint already implies safe repeated calls.

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, front-loaded with the core purpose, followed by usage context and persistence details. Every sentence earns its place—no redundant filler—and it is well-structured for quick scanning.

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 key-value store tool with two well-documented parameters, no output schema, and clear annotations, the description covers purpose, usage scenarios, persistence behavior, and related tools. It is complete enough for an agent to select and invoke the tool correctly without ambiguity.

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 (key and value) with examples and full coverage, so the description's additional mention of 'key-value pair' adds little semantic value. The description's note about scoping by identifier is more about the storage context than the parameters themselves, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Save data the agent will need to reuse later.' It distinguishes from siblings by giving examples (ticker, address, preference) and explicitly pairing with recall/forget, which are retrieval and deletion tools respectively.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names the related tools (recall, forget) to indicate complementary alternatives, making it clear when to use this tool versus the siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: internal cascading through endpoints, auto-disambiguation for companies, and citation URI generation. 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 well-structured with example queries up front, then type-specific details, and a concluding note on efficiency. Every sentence adds value; it is dense but not bloated.

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 fully explains return values (ticker, CIK, RxCUI, citation URIs), input formats, supported types, and the usage context. Combined with annotations, it is complete for effective 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 covers 100% of parameters with clear descriptions. The description adds examples for each type (ticker, CIK, name; brand/generic) and clarifies the return values, enriching understanding beyond the schema. Not just a 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 clearly states the tool resolves user-spoken names to canonical identifiers, with explicit examples ('ticker for…', 'CIK for…', 'RxCUI for…'). It distinguishes from siblings by emphasizing that the resolved ID is what other tools require as input, and mentions 'Use FIRST' for this purpose.

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not name specific alternative tools or explicitly state when not to use it, so it lacks full exclusionary guidance.

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

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

The description adds meaningful behavioral context beyond the annotations: it discloses that the tool 'Probes each entity ... with ai_visibility_check, ranks by score', and specifies the output as 'ranked list with score, confidence, signal density per entity'. It also notes that the first entity is treated as the 'subject', which is a non-obvious behavior. Annotations already declare readOnly/idempotent, so the bar is lower; this extra detail earns a 4.

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, front-loaded with the primary action, then mechanism and use case. Every sentence contributes: it states what it does, how it does it, and when to use it. There is no redundant filler or repetition of schema details.

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 moderately complex (4 params, no output schema), but the description compensates by summarizing the return format ('ranked list with score, confidence, signal density per entity') and the procedural behavior. It also hints at the dependency on ai_visibility_check. Without an output schema, this description is nearly sufficient for an agent to anticipate what the tool will return. A minor gap is lack of detail on error conditions or model selection behavior, but overall it 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 description coverage is 100%, and the description itself does not add parameter-level details beyond what the schema provides. The schema already documents that entities is an array of 2-8 with the first as subject, and explains models, _apiKey, and context. Per the baseline rule, when schema covers parameters fully, 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 starts with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the probing mechanism (ai_visibility_check) and the ranking output. The competitive audit use case is explicit, making the tool's purpose unambiguous.

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

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

The description provides a clear context: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' This tells the agent when to use the tool, but it does not explicitly state when not to use it or mention alternatives. It lacks the 'when-not' guidance that would earn a 5, but the context is sufficiently clear.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds valuable context beyond annotations: partial failures degrade gracefully, the bundlephobia first measurement can take 5-30s, and the sources_failed field lists timeouts. This clarifies expected runtime behavior and failure handling, which is especially useful for an agent deciding whether to invoke 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 concise for its content: each sentence adds distinct value—purpose, when to use, return structure, ecosystem scope, and failure mode. It is well-structured with a clear opener and logical flow, and avoids redundant fluff or repetition of schema details.

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 enumerates the return fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable, per-advisory detail, links, alternative versions). It also covers ecosystem limitations, timeout behavior, and partial failure, making it sufficient for an agent to decide on invocation 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?

Schema coverage is 100%, so the schema already documents both parameters fully. The description does not add new parameter-level details beyond what the schema provides (e.g., version defaults to latest, scoped packages accepted are already in the schema). It provides context in the overall narrative but not additional syntax or format specifics, so the baseline score of 3 applies.

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

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

The description opens with a specific, actionable definition: "Composite 'should I add this npm package to my project' check in ONE call." It clearly identifies the resource (npm package) and the main action (checking licenses, advisories, bundle size, etc.), and distinguishes it from any sibling tool by its unique composite nature across deps.dev and bundlephobia.

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 states when to use: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also provides a clear exclusion for non-NPM ecosystems ("PyPI / Maven / Cargo / Go fall under deps.dev:version directly"), serving as an alternative for those cases. It stops short of naming a specific sibling tool but gives actionable 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds behavioral detail about the return format: 'returns stable IDs and display names grouped by type', and indicates the scope ('across all object types'). This goes beyond the annotations and gives the agent useful expectations about 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 a single, tightly written sentence that front-loads the primary action and resource, then efficiently specifies scope and output. Every clause contributes, with no filler or redundancy.

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

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

The tool is relatively simple (3 parameters, one required) and a structured output schema exists, so the description need not explain return values. The description covers the search scope, object types, and output grouping, which is sufficient for an agent to select and invoke the tool correctly. The available annotations further complete the picture.

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

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

The input schema covers the 'types' and 'cluster' parameters with descriptions, but 'query' is undocumented. The description compensates by identifying 'query' as a keyword, and the enum examples (Pathway, Reaction, Protein, Complex) clarify valid 'types' values. This adds meaning beyond the schema, though not exhaustive.

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: 'Search the Reactome biological pathway database by keyword across all object types'. It uses a specific verb ('Search') and resource ('Reactome biological pathway database'), lists example object types, and specifies the output ('returns stable IDs and display names grouped by type'). This unambiguously distinguishes it from a generic search tool.

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

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

The description conveys clear usage context: it is a broad keyword search spanning all object types, making it appropriate as an initial discovery step. It does not explicitly mention alternatives or exclusions, but the phrase 'across all object types' implies a general-purpose search, and sibling tools like 'search_within' are implicitly different. This meets the 'clear context, no exclusions' level.

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?

Given annotations already state readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description adds significant behavioral detail: character offsets, similarity scores, BGE-base-en embeddings, cosine over 500-char overlapping windows, and a 200K char cap with truncation flagging. This goes well beyond the annotations and gives the agent concrete 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, well-structured paragraph that front-loads the core purpose and then packs each sentence with useful details: return format, use case, pairing, embedding algorithm, and limits. No sentence is wasted, and the length is appropriate for 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?

The tool has no output schema, but the description covers what the agent will receive (top-N passages with offsets and similarity scores). It also discloses truncation behavior, algorithm choice, and workflow pairing, making it fully self-contained for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical examples for text (SEC 10-K body, article, long tool result) and for query (supply-chain risk, fiscal year revenue), plus clarifies that text is something already pulled. This enriches the parameter understanding beyond the schema fields.

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,' giving a specific verb, resource, and scope. It clearly distinguishes from siblings like search by emphasizing the input is already-fetched text, and it references ask_pipeworx_grounded as a complementary tool.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context and returning only relevant passages. It also pairs with ask_pipeworx_grounded to show the intended workflow, though it does not explicitly list exclusions or when not 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?

Despite annotations already covering idempotency, non-readonly, and non-destructive behavior, the description adds meaningful context: authentication requirements, an always-on feed, optional email/sms delivery, phone verification, and daily SMS caps. It does not contradict annotations, though it omits webhook details that are covered in the schema.

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

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

The description is front-loaded with the core purpose, followed by prerequisites, supported types, and delivery channels. It is dense but not excessively long; some redundancy with the schema (e.g., SMS cap and type examples) makes it slightly less concise than ideal.

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

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

The description covers the return value, auth requirements, subscription types, and delivery options, and is complemented by a rich input schema that details all parameters. The absence of an output schema is mitigated by stating the return value, but the description alone does not explicitly mention webhook behavior, though the schema does.

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

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

Schema coverage is 100% and the schema already contains detailed type-specific parameter examples and delivery constraints. The description re-iterates examples and adds small semantics like 'items:["5.02"] = officer change,' but largely duplicates the schema, so it does not substantially elevate understanding beyond the structured definition.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream,' and states the return value. It clearly distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by being the creation 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?

The description provides clear context on when to use the tool—for ongoing proactive monitoring of live events—and lists supported subscription types with examples. It also notes a prerequisite (Pipeworx OAuth account), but does not explicitly describe when to prefer alternative tools for one-off queries or exclusions.

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

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

Annotations already flag readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: it returns category-bucketed example questions with exact tool and argument shapes from the live catalog, and explains how the 'topic' parameter affects the response. It doesn't mention performance or rate limits, but given annotations cover safety, this is sufficient.

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 comprehensive sentence that front-loads example queries and conveys the purpose, return value, and usage. It is efficient and every clause contributes meaningful information. While not as tightly structured as a two-sentence summary, it avoids fluff and is appropriately sized for the tool's scope.

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

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

For a simple read-only tool with no output schema, the description is fully complete. It explains what the tool returns (category-bucketed questions with tool+argument shape), when to use it, how to invoke it with or without the topic parameter, and its role relative to meta-tools. The agent has all necessary information to select and call this tool correctly.

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

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

The input schema has 100% coverage with a description for the single 'topic' parameter. The description enriches this by clarifying that omitting the parameter returns a full spread, while passing a topic focuses the results. It also provides concrete examples ('finance', 'pharma', 'betting'), which the schema lacks. This goes beyond simple restatement.

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 an onboarding entry point for an agent to discover what questions it can ask Pipeworx. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes it from siblings by positioning it as the 'FIRST' tool to use when unfamiliar with Pipeworx, unlike discover_tools or ask_pipeworx.

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

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

Explicitly states '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 provides clear guidance on when to pass the optional 'topic' parameter versus omitting it, and gives examples. This effectively tells the agent when to use this tool and the 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?

The description discloses that ownership is enforced and that the row is deactivated rather than deleted, preserving history. This goes beyond the idempotentHint and destructiveHint annotations, adding meaningful behavioral context that an agent needs to know.

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

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

Two concise sentences, front-loaded with the primary action, followed by essential behavioral details. No redundant information and 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 single-parameter mutation tool with no output schema, the description covers the action, ownership constraint, and the non-deletion effect. This is sufficient for an agent to understand the tool's behavior and select it correctly.

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

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

The schema already documents the single 'id' parameter as the subscription uuid returned by subscribe (100% coverage). The description adds 'your own subscriptions' context but doesn't provide additional syntax or format details, so the schema carries 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 uses the specific verb 'Cancel' with the resource 'subscription', clearly differentiating from sibling tools like 'subscribe' and 'list_subscriptions'. It states exactly what the tool does and its 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 states the action and the ownership constraint, implying when to use it (to cancel your own subscription). It doesn't explicitly name alternatives or exclusions, but the sibling context and 'recent_alerts' mention provide clear context for appropriate 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 readOnly/openWorld/idempotent, so the description adds significant behavioral context: the SEC EDGAR + XBRL fast path with exact percent-delta math, automatic fallthrough to the grounded pipeline, verbatim evidence, and the complete verdict set (confirmed / approximately_correct / refuted / inconclusive / unsupported). 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 moderately long but well-structured: triggers, purpose, usage, routing logic, return values, and value proposition. Each sentence earns its place, though the list of six example trigger phrases is slightly redundant. Front-loaded with purpose, so it earns a 4.

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 there is no output schema, the description explicitly enumerates the return tuple (verdict, actual value with pipeworx:// citation, reasoning). It covers financial vs. non-financial routing, tolerance behavior, and even notes it replaces 4–6 sequential calls. This is highly complete for a complex verification 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?

Both parameters are fully described in the schema (100% coverage), including tolerance_pct's override behavior and examples. The description adds minimal extra parameter-specific detail—it references the claim input implicitly and the exact percent-delta math, but largely reinforces what the schema already captures. 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 explicit natural-language triggers ('Is it true that…', 'fact check') and defines the tool as 'natural-language claim verification against authoritative sources'. It clearly distinguishes from siblings by specifying the full verification pipeline (SEC EDGAR fast path, grounded fallback) and return verdicts, rather than being a generic search/ask tool.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct', giving clear when-to-use context. It does not explicitly name excluded scenarios or alternatives, but it details the routing for financial vs. other claims. Slight gap: no explicit 'don't use for X' or sibling comparisons.

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