Nrel

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavior: default free model (Workers AI), optional Anthropic probing with BYO key, and response structure (score, confidence, signals, raw_response). 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 sentences that front-load the primary action and resource, followed by key details (default model, key requirement, return structure). Every sentence adds value with no redundancy or fluff.

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

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

Given the moderate complexity (4 parameters, no output schema), the description thoroughly covers the tool's purpose, parameters, default behavior, optional setup, and return format. It leaves no major gaps for an agent to interpret how to invoke the tool.

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

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

Schema description coverage is 100% with good parameter descriptions. The description adds value by explaining the default model, the need for _apiKey with Anthropic, and the purpose of context. While the schema already does well, the description enhances understanding of parameter usage.

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: probing LLMs for brand/topic awareness and scoring visibility (0-100). It specifies the resource (LLMs) and action (probe and score), and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring rather than scanning.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies when to use but does not explicitly exclude alternatives or name sibling tools. The context is clear enough for an agent to decide, but lacks explicit when-not-to-use guidance.

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

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

Annotations (readOnly, openWorld, idempotent, non-destructive) are consistent, and the description adds context beyond them: routing across thousands of tools, argument filling, citation URIs, and tier/performance info ('works on every tier, one fast call'). It could mention rate limits or error behavior, but the core behavioral profile is well covered.

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 informative but verbose and repetitive (e.g., 'PREFER OVER WEB SEARCH' and 'START HERE' appear multiple times). It is not front-loaded: the purpose statement appears after several directives. While examples and alternatives add value, it could be condensed by half without losing content.

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

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

Given the tool's complexity and lack of output schema, the description explains return value ('structured answer with stable pipeworx:// citation URIs'), covers when to use it vs alternatives, and provides real-world examples. It is complete enough for an agent to select and invoke correctly, though it could specify response format or error handling.

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 each parameter described (including aliases), so the baseline is 3. The description does not add much beyond schema—it merely states the question is in 'natural language' and lists examples. However, since the schema already handles parameter semantics, no further compensation is needed.

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: 'Routes the question to the right one of 5,462 tools across 1419 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' It also positions it as the default entry point ('START HERE for most questions'), distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and clearly names alternatives with specific conditions: 'for a hallucination-resistant single answer use ask_pipeworx_grounded; for a broad/multi-part question use deep_research'. It even gives example queries and notes breaking-news handling.

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

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

Annotations already declare read-only, idempotent, open-world hints, but the description adds valuable context: the experimental nature, live candidate status, current equivalence to stable, and that it 'falls back to nothing' yet is a full working router. This goes well beyond the annotations and clarifies potential misconceptions about beta 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?

Three dense sentences convey identity, current status, usage guidance, and a clarifying note about fallback behavior—all without redundancy. The description is front-loaded with the beta designation and avoids fluff, making it highly concise and structured.

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

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

For a complex universal router with no output schema, the description covers the essential context: experimental nature, current equivalence, usage instructions, and behavior comparison. It references 'same response shape' as ask_pipeworx, which provides sufficient context for expected output without needing to restate 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?

The input schema provides 100% coverage with descriptions for all six parameters (question and its aliases), so the description's mention of 'same arguments' adds minimal semantic value. The description does not elaborate on parameter behavior beyond referencing ask_pipeworx, which is sufficient given the 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?

Description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,462 tools, and distinguishes it from the stable sibling by highlighting candidate routing improvements. The verb+resource ('Ask Pipeworx Beta') is specific and the reference to 'identical universal router' anchors its purpose precisely.

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 to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router to decide merges. It also notes the current inactive state, giving clear context for when it matches stable and implying the alternative stable router for non-experimental use.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds substantial behavior: return format with answer/evidence/confidence/source/fetched_at, explicit refusal reasons, and cost tradeoff. 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 every sentence earns its place. It front-loads the core value proposition, then covers return shape, refusal modes, use cases, and cost comparison in a compact, structured way. No filler.

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

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

Despite having no output schema, the description compensates fully by specifying the exact success and refusal return structures. Given the tool's complexity (routing across 5,462 tools, grounding, refusal reasons), this description gives the agent everything needed to decide 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% and all parameters are aliases for the same 'question' field, so the schema already documents everything. The description adds no additional parameter meaning beyond mentioning the question is used for routing, but this is already implied by the schema descriptions.

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

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

The description clearly states the tool is a hallucination-resistant answer mode that extracts answers only from actual tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction, evidence quotes, and refusal behavior. The verb 'answer' and resource 'Pipeworx' are 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?

Explicitly tells when to use: whenever an answer will be quoted, cited, or acted on and facts cannot be invented. Also tells when not to use: prefer ask_pipeworx for casual lookups due to extra LLM call cost. Names the alternative directly.

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 is exceptionally transparent, detailing the resolution process, fan-out logic, response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, and resolution-rule risks. This goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) and provides rich behavioral context without contradiction.

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

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

The description is well-structured and front-loaded with the core purpose, but it is quite lengthy (multiple paragraphs). Given the tool's complexity and the absence of an output schema, the detail is warranted, though some sentences could be condensed without losing meaning.

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

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

The description fully compensates for the lack of an output schema by comprehensively detailing return shapes (result.market, result.analysis, result.evidence), resolver contract, parent event, news fields, safety mechanisms, and edge cases (closed markets, low confidence, wide spreads). It covers all aspects needed to use 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?

The description adds significant value beyond the input schema. It explains that 'market' can be a slug, URL, or question text; describes 'depth' with examples of quick vs thorough fan-out and default; and elaborates on 'include_raw' with guidance on when to enable it. This complements the 100% schema description coverage effectively.

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

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

The description opens with a clear statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research/pull) and resource (Polymarket bet, Pipeworx data), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on comprehensive research rather than specific analysis.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to employ the tool. However, it does not explicitly mention when not to use it or directly contrast with sibling tools, which would have made it 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 indicate read-only, idempotent, non-destructive. Description adds extra behavioral context: data sources (SEC EDGAR/XBRL, FAERS), off-calendar handling, sorting, citation URIs.

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

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

Front-loaded with query examples, each sentence adds value. Slightly verbose but justified by completeness.

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 2 parameters, no output schema, and rich annotations, description covers entity types, data sources, constraints, and use cases sufficiently.

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 parameters fully (type enum, values array). Description adds concrete examples (tickers/CIKs for company, names for drug) and bounds (min 2, max 5).

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 clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, listing specific data sources and result attributes.

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 to prefer over sequential single-pack lookups and provides example queries. Could add when NOT to use (e.g., single entity).

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context beyond those: account/paid-plan requirements, does not do open-web search, returns explicit gaps[] for unanswered facets (never invented), includes contradiction detection for standard/thorough, semantic excerpting rather than head-truncation, and expected latency ranges. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with the most critical operational constraints (account requirement, alternative tool). Each sentence carries meaningful information about behavior, output, or usage. Slightly verbose but 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?

For a tool with a complex output (findings packet with evidence, confidence, citations, gaps, contradictions), the description comprehensively explains what to expect in the result, how to choose among alternatives, and behavioral limitations. No output schema exists, so the description carries the full burden of explaining the return format, which it does thoroughly.

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

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

Schema description coverage is 100% for both parameters, so the schema already explains the 'depth' enum and 'question'. The description adds a few useful constraints (e.g., 'thorough' needs a paid plan, 'standard' is default) but does not significantly enrich parameter understanding beyond what the schema already provides.

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

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

The description clearly states this is a grounded multi-source research tool that decomposes questions into facets, routes them to thousands of specialized tools in parallel, and returns a findings packet with evidence and citations. It explicitly distinguishes itself from open-web search and from the sibling 'ask_pipeworx' tool by noting the single-lookup 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 explicit alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Even covers account-level fallback: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by explaining the return format (top-N tools with names, descriptions, schemas, examples) and noting that results are ready to call directly, which is helpful behavioral context beyond the annotations.

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

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

The description is well-structured: starts with a verb phrase, lists specific use cases, explains the return value, and gives a usage directive. Every sentence adds value, and it's appropriately sized for the complexity of the tool.

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

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

Despite having no output schema, the description thoroughly explains what is returned (names, descriptions, schemas, examples) and that results are ready to call. The sibling context confirms this tool is the discovery entry point, and the description fully supports an agent's understanding of when and how to use 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%, with all 6 parameters having descriptions. The description reinforces that 'query' accepts natural language and lists aliases, but doesn't add meaning beyond what the schema already provides. Baseline 3 is appropriate given 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 'Find tools by describing the data or task' and lists many specific domains (SEC filings, FDA drugs, etc.), making it unmistakable what the tool does. It distinguishes itself from sibling tools by being the meta-discovery tool for exploring available options.

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 guides the agent to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides a list of example use cases, giving clear when-to-use context. No when-not-to use is stated, but the positive guidance is sufficient.

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. Description adds cross-source fan-out details, patents API sunset soft-fail, and return fields. No contradiction.

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

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

Description is detailed but well-structured with examples, preferences, and source list. Slightly long but every part adds value. Could be more compact but effective.

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, so description carries burden. Lists all returned fields (cik, filings, fundamentals, patents, news, LEI) and notes soft-fail. Adequate for complex multi-source tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that names are not supported and reminding to use resolve_entity, slightly exceeding 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?

Description uses clear verb+resource: 'full cross-source profile of a US public company'. Examples show exact usage. Distinguishes from sibling resolve_entity by stating names not supported.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view'. Also says to use resolve_entity if only a name. Clear when-to-use and when-not.

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 destructiveHint=true and readOnlyHint=false. The description confirms deletion but adds no further behavioral details (e.g., irreversibility, return value). With annotations present, this is adequate but not enhanced.

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

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

Three sentences, each serving a distinct purpose: action, usage condition, and pairing. Highly concise with no wasted words.

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

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

For a simple delete tool with one required parameter and no output schema, the description covers purpose and usage adequately. It lacks details on return values or errors, but these are not critical 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% and describes the 'key' parameter. The description does not add any additional meaning or constraints 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 explicitly states 'Delete a previously stored memory by key', identifying the verb and resource. It also mentions pairing with siblings 'remember' and 'recall', distinguishing it from related 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 specifies when to use: when context is stale, task is done, or to clear sensitive data. It suggests pairing with remember and recall. However, it does not explicitly state when not to use 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 indicate read-only, idempotent, non-destructive. The description adds behavioral details: fetches the page, extracts title/description/key links, emits standard format. This aligns with annotations and provides additional context beyond structured fields.

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

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

Three sentences that efficiently cover purpose, process, output, and use cases. No redundant information; 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?

Given the simple tool with 2 parameters and no output schema, the description sufficiently explains the process, output format (single text blob), and the standard llms.txt format. It is complete for an AI agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that max_links controls the number of link entries with default 25 and max 50, enhancing the parameter meaning beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'Generate' and resource 'llms.txt file'. It distinguishes from siblings like ai_visibility_check by focusing on llms.txt generation specifically, and includes use cases.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own projects, auditing competitors. While it doesn't explicitly state when not to use it, the context is clear and the use cases provide good 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 indicate readOnly, idempotent, non-destructive. Description adds specific return fields and default behavior (active only). No contradictions.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Highly efficient.

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

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

Given the simple parameter set and annotations, the description covers necessary information, including return fields and usage 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?

Schema coverage is 100% for the single boolean parameter. Description does not add extra meaning beyond schema, meeting the baseline.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates return fields. It distinguishes from sibling tools like subscribe and unsubscribe by specifying the use case.

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 tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for tool selection.

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

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

Annotations provide only false hints, so the description carries the behavioral burden. It adds important constraints: rate-limited to 5/day, free, doesn't count against quota, and team reads digests daily which affects roadmap. This goes beyond annotation defaults, though it doesn't describe submission confirmation or what happens immediately after.

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 purpose, then usage, exclusions, and constraints. Every sentence adds value—rate limit, quota, scope, and feedback content guidance—without fluff. Despite moderate length, it is tightly 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?

Covers scope, exclusions, constraints, and expected outcome (team reads digests, affects roadmap). With no output schema, no return-value explanation is needed. Nested context parameters are explained in schema and reinforced by the 'tools/packs' guidance. Highly complete for a feedback 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 semantic guidance for the 'message' field (be specific about tool, error, missing data) and for 'context' (frame in terms of Pipeworx tools/packs), improving on the schema's plain 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 purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names a specific verb, resource, and feedback categories, distinguishing it from sibling research, memory, and subscription 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?

Gives explicit when-to-use examples (bug, feature/data_gap, praise) and when-not-to-use: for tools from a different MCP server, with instruction to file there instead. Also restricts scope to Pipeworx tools and advises not to paste end-user prompts.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds 'self-aggregating signal', 'no PII', and caching policy (5min-1h). No contradictions. Adds value beyond annotations.

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

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

Three sentences with bullet-like use cases. No fluff. Front-loaded with purpose, then use cases, then provenance. 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 single-param tool with good annotations, the description explains returns (top tools, packs, volume) and caching. Lacks output format, but given simple trending data, it's likely sufficient.

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%. Description adds context for 'window' parameter: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the enum 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?

Clearly states it returns top tools, packs, and total call volume on Pipeworx over a window. Verb 'calling on' and resource 'Pipeworx' are specific. Differentiates from siblings by focusing on trending signals.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool choice, and aligning use case. Lacks explicit when-not-to-use or alternatives, but the use cases are helpful.

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

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

Adds substantial behavioral details beyond annotations: fill check with CLOB depth, semantic anchor with Jaccard similarity, partition filter for placeholders, and response structure. Annotations (readOnly, openWorld, idempotent) are consistent; no contradiction.

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

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

The description is well-organized and informative, covering all necessary aspects without redundancy. Each sentence adds value, though it is lengthy; given the complexity, the structure is efficient.

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

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

Despite no output schema, the description fully explains the return structure (opportunities array with fields, partition_check for event mode, fill check details). Covers edge cases like placeholder filtering and similarity skips, making it complete for informed usage.

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 with examples, accepted formats (URLs, slugs), and mode-specific behavior. Explains internal logic like similarity thresholds, adding value beyond the schema.

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

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

The description clearly states the tool detects arbitrage opportunities via monotonicity violations and partition-sum checks, detailing three distinct modes (trending_scan, event, topic). It provides examples and differentiates from related tools like polymarket_fill_risk.

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 explains when to use each mode: no args for trending_scan, event for specific markets, topic for cross-event scanning. Includes examples and notes when not to trade (realizable_edge_pp ≤ 0). Does not fully contrast with sibling tools but points to polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds deep behavioral context: caching at KV level, response structure with diagnostics, model family details and limitations (e.g., Fed bets excluded), and tradeable-edge knob effects. 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 lengthy but well-structured with clear sections for model families, knobs, and response fields. Every sentence adds value—no tautology or fluff. Front-loaded with purpose and then detailed 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 complex tool with 9 params and no output schema, the description is remarkably complete. It explains internal models, caching, diagnostics, filter skips, and edge cases (Fed bets). An agent can fully understand invocation and interpretation.

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

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

Despite 100% schema coverage, the description adds substantial meaning: e.g., slippage_pp explains zero fees but thin depth, max_spread_pp recommends 2, min_partition_leg_kelly explains relationship to min_kelly. This goes well beyond 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific verb 'scan' and resource 'edges'. It distinguishes from sibling tools by focusing on disagreement detection and model-driven signals.

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

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

The description explicitly targets 'what should I bet on today' and explains knobs like min_liquidity and max_spread_pp. However, it does not provide explicit when-not-to-use guidance or compare directly to siblings like polymarket_arbitrage, but the context is clear enough for 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 annotations (readOnly, idempotent), the description provides extensive behavioral details: snapshot-based data, trend/decay computation, expired opportunities, limits (60-day TTL), and snapshot gaps. 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 fairly concise given the complexity, front-loading the key question. Slightly long but every sentence adds value; could be tightened.

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

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

Despite no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and addresses limitations, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. The description adds context like defaults, valid ranges, and window family meanings, enhancing understanding beyond the schema.

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

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

The description clearly defines the tool's purpose as providing edge persistence and decay telemetry, answering a specific question about edge age and trend. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series and decay.

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 when to use (to understand edge persistence vs freshness) and hints at alternatives (polymarket_edges for current edges). However, it does not explicitly state when not to use or list alternatives.

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

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

Annotations already provide readOnlyHint, destructiveHint, etc. The description adds critical behavioral context: depth-checking, return fields like verdict (clean|degraded|cannot_fill), forced directional risk; no contradiction with annotations.

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

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

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS), front-loaded with main purpose. Slightly verbose but every sentence adds value.

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

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

No output schema, but description details all return fields, edge cases (thin legs, forced directional risk), and usage scenarios, 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 parameters are well-described. The description adds extra clarity on dual-mode usage (market vs event) and default side logic, which goes beyond schema.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use the tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Provides rationale about theoretical overround on thin books and partial basket fills converting arbs into unhedged positions.

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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds rich behavioral context: response structure (spread, safety fields), temporal alignment checks, skipped counters for mismatched bet shapes, and explicit conditions for compatibility warnings. 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 information-dense and well-organized with uppercase section headers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence serves a purpose, though it could be slightly more concise. The length is justified by complexity, earning 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 the tool's complexity (cross-venue comparison, matching logic) and absence of an output schema, the description thoroughly explains response fields (spread, compatibility_warning, temporal_alignment, skipped counters) and edge cases. It provides everything an agent needs to correctly invoke and interpret results.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the 'topic' parameter with the exact list of 10 shortcuts, defines that explicit parameters override the topic mapping, and clarifies that the topic may not yield tradeable spreads. This goes far beyond the schema's simple type/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 defines the tool as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' with a specific verb ('computes spread') and resource ('cross-venue spread'). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two-venue comparison rather than single-venue 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 explicitly outlines two modes ('topic' for pre-mapped shortcuts, 'explicit' for custom pairings) and provides guidance on when to use each. It also warns that most pre-mapped topics return compatibility_warning and are not tradeable, effectively telling the agent when not to expect useful results.

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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and listing behavior, adding value beyond structured fields.

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

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

Two concise sentences with all essential information, no unnecessary words.

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

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

Given simplicity (one optional param, no output schema), description covers purpose, usage, scoping, and pairing. Lacks explicit return format but implied by actions.

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

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

Schema coverage is 100% with a clear parameter description. The tool description adds little 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?

Clearly states it retrieves a saved value or lists all keys, distinguishes from sibling tools 'remember' and 'forget'.

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 describes when to use with examples (target ticker, address, notes), scoping, and pairing with remember/forget, but lacks explicit when-not-to-use or alternatives among 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?

Description discloses that setting mark_read:true mutates state by flagging events as read, contradicting the annotation readOnlyHint:true. Score is 1 per rubric for contradiction.

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

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

Description is concise with a clear front-loaded purpose sentence. It packs multiple details without excessive length, though it could be slightly more 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?

Covers the tool's function, parameters, return fields, and alternative access. Missing details on pagination and ordering beyond 'most recent', but sufficient for most use cases.

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

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

Input schema covers all 5 parameters (100% coverage), and the description adds value by explaining filtering examples (type 'sec_8k', ISO timestamp) and the effect of mark_read and unread_only, going beyond the schema.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts. The verb 'Pull' and resource 'fired events' are specific, but there is no explicit differentiation from sibling tools like recent_changes or list_subscriptions.

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

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

The description mentions that polling works and provides an HTTP alternative for scripts/dashboards, but does not specify when not to use this tool or compare it to other available tools.

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, non-destructive behavior. The description adds substantial behavioral context: fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail condition), and describes the return structure (changes grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is concise for the complexity, front-loaded with example queries. Every sentence provides useful information, though slightly verbose in the source enumeration. No wasted words.

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

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

Despite lacking an output schema, the description fully explains the return structure and limitations (USPTO soft-fail). It covers inputs, sources, and edge cases, making it complete for an AI agent's invocation needs.

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

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

Schema coverage is 100% with descriptions for all parameters, so baseline is 3. The description adds value by explaining the window concept for 'since', providing example formats, and clarifying that 'value' accepts ticker or CIK. It also describes the output format, which is not in the schema.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with specific verb+resource and example queries. It distinguishes from sibling 'entity_profile' explicitly.

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: when to ask 'what's new' queries, and when not to (use entity_profile for static profile). It also notes the fallback behavior between GDELT and GNews.

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 indicate idempotentHint true and destructiveHint false. The description adds behavioral context: key-value storage, identifier scoping, 24-hour retention for anonymous users, and companion tools. No contradictions; it enriches understanding beyond annotations.

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

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

Four sentences, front-loaded with purpose, no fluff. Every sentence adds necessary information. Well-structured and easily digestible.

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 with no output schema, the description covers usage, storage details, persistence, and companion tools. No gaps; fully informs agent behavior.

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 key and value. The description adds examples of key formats ('subject_property', 'target_ticker') and value types ('findings, addresses, preferences, notes'), significantly enhancing meaning beyond raw 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 'Save data the agent will need to reuse later' and provides specific examples like resolved ticker, target address, user preference, research subject. It distinguishes from sibling tools 'recall' and 'forget' by explicitly naming them as companions.

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 says 'Use when you discover something worth carrying forward' and gives concrete scenarios. It also explains scoping by identifier and persistence differences between authenticated and anonymous sessions. Explicitly instructs to pair with recall and forget.

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

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

The description adds substantial behavioral detail beyond the annotations (readOnly, idempotent): it discloses internal cascading lookups, the exact return fields (ticker, CIK, RxCUI), and the citation URIs. This goes far beyond what annotations alone convey.

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

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

The description is well-structured and front-loaded: it opens with example natural-language queries, then states the core purpose, then provides detailed supported-type breakdowns. Every sentence contributes actionable information, and the length is justified by the tool's dual-type complexity.

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

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

Given that there is no output schema, the description adequately covers return values, input formats for both entity types, and even includes citation URI formats. It also addresses efficiency and usage scope. No important operational aspect is omitted.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by explaining output structure (e.g., 'returns ticker + 10-digit CIK + company_name'), the auto-disambiguation behavior, and the accepted input variants, enriching the meaning of both parameters beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with a specific verb+resource ('resolve a user-spoken NAME to the canonical/official identifier'). It distinguishes from sibling tools by positioning itself as the go-to tool when a name needs an ID, and it lists concrete example queries.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear when-to-use directive. It also notes that each call replaces 2-3 manual lookups, giving a strong context for when this tool is the right choice.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description explains the tool probes with ai_visibility_check, returns a ranked list with score, confidence, and signal density. This adds valuable behavioral context not present in annotations.

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

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

Two sentences with clear action and front-loaded purpose. Every sentence adds value 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 no output schema, the description fully explains the output format. All parameters are documented in the schema. The tool's purpose and behavior are completely understandable for an AI 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%, so the description adds little beyond the schema. It mentions entities as brand/business/product names and context as disambiguation, but does not provide new details beyond the parameter descriptions.

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

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

The description clearly identifies the tool as comparing AI visibility across multiple entities, using ai_visibility_check, ranking by score, and surfacing most/least recognized. This distinguishes it from similar tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example question. It does not explicitly exclude other use cases or mention alternatives, but the context is sufficiently clear for appropriate selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed will list timeouts, and the rest of the data still returns. 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 detailed but front-loaded with the core purpose and composite nature. While it contains some extra detail (e.g., exact output fields), every sentence adds value. It could be slightly more concise but is 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 two parameters, no output schema, the description fully details the return value (summary block, per-advisory, links, alternative versions) and explains partial failure behavior. It covers all necessary context for an agent to invoke correctly.

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

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

Schema coverage is 100%, with both parameters described. The description adds that scoped packages (e.g., '@types/node') are accepted and that version defaults to latest when omitted, which goes beyond the schema 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 clearly states the composite purpose: a single call that checks license, advisories, version history, and bundle size for npm packages. It specifies the verb 'scan' and the resource 'dependency', and distinguishes from sibling tools by noting ecosystem limitations ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing clear context. Also gives when-not-to-use guidance for other ecosystems, pointing to alternative deps.dev endpoints.

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, non-destructive behavior. The description adds significant context: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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?

Single paragraph front-loaded with key concept. All sentences add value. Could use slight structural improvement (e.g., separate sentences for technical details) but remains concise and clear.

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

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

For a complex tool with no output schema, the description covers input format, search algorithm, output (passages with offsets and scores), limitations (200K chars, truncation flag), and recommendations for use. Exceptionally complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context: text max 200K chars, query examples, limit default value. This provides meaningful usage guidance beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). It distinguishes from sibling ask_pipeworx_grounded by explaining the different use case (search inside vs. ground over passages).

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and recommends pairing with ask_pipeworx_grounded. Provides clear context for when to use this tool versus alternatives.

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

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

Provides rich behavioral context beyond annotations: auth requirements, type-specific parameters, delivery constraints (e.g., SMS cap, webhook secret returned once). 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?

Front-loaded purpose and return value. Detailed but slightly verbose; could be more concise while retaining necessary information. Good structure with clear sections.

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?

Very complete given complexity: covers return value, auth, multiple subscription types, delivery channel details, and constraints. No output schema but return value described.

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 100% and description adds extensive detail: enumerates type options with examples, details params for each type, explains delivery fields with constraints and verification requirements.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Specific verb and resource, distinguishes from sibling tools like list_subscriptions and recent_alerts.

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 prerequisites (Pipeworx OAuth account) and supported types with examples. Mentions delivery channels and caps. Lacks explicit when-not-to-use or direct alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description goes beyond by detailing the output format (category-bucketed examples with tool+argument shapes) and the fact it uses the live catalog. This provides rich behavioral context.

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

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

The description is somewhat long but well-structured: it starts with alternative phrasings, states the core purpose, describes the output, and gives usage patterns. It is front-loaded with key information. Minor redundancy in listing categories could be trimmed, but overall it is effectively concise.

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 fully explains what the tool returns (category-bucketed example questions with tool+argument shapes). It also covers usage with/without arguments and mentions meta-tools. No critical gaps remain for an AI agent to understand how to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a bit more context for the topic parameter by listing example values (finance, pharma, betting) and stating 'Omit for a cross-category spread.' This aligns with the schema description but doesn't add substantial new meaning.

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 returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings like ask_pipeworx and discover_tools by being the first tool to use when unsure what to ask.

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

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

Explicitly says to use this tool FIRST when you don't know what Pipeworx can do, and explains how to pass a topic for focus. However, it doesn't explicitly state when not to use it (e.g., if you already know what to ask, skip this). Still, the guidance is clear and helpful.

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 include destructiveHint=false and idempotentHint=true; the description adds that the row is deactivated (not deleted) and historical events remain available via recent_alerts. 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?

Three concise sentences cover the action, ownership constraint, and behavioral nuance. Every sentence is informative with no 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?

For a single-parameter tool with clear annotations and schema, the description is mostly complete. However, it lacks any mention of success/failure responses or return values, which would add completeness.

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

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

Schema coverage is 100%, so the schema already describes the 'id' parameter as a subscription UUID. The description adds no additional meaning 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 clearly states it cancels a subscription by ID, using specific verbs ('cancel') and resource ('subscription'). It distinguishes from sibling tools like 'subscribe' (opposite action) and 'list_subscriptions' (listing).

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

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

The description explains ownership enforcement and deactivation behavior, but does not explicitly state when to use versus alternatives or provide exclusions. It implies usage after obtaining a subscription ID from 'subscribe'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, but the description adds rich behavioral detail: internal routing logic (structured vs grounded pipeline), exact percent-delta math for financial claims, verdict categories, and return structure with citations. There is 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 lengthy (~10 sentences) but well-structured: starts with example queries, states usage, details internal behavior, and ends with output format. While every sentence adds value, a slight reduction in redundancy (e.g., repeated mention of routing) could improve conciseness.

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

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

Despite having no output schema, the description thoroughly explains the return values (verdict types, value, citation, reasoning) and the dual-verification process. It covers most aspects for an agent to use the tool correctly, though edge cases like unverifiable claims or unsupported statements are not elaborated.

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

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

Schema coverage is 100% (both parameters described). The description adds meaning: for 'claim', it provides natural-language examples; for 'tolerance_pct', it explains override use case for hallucination detection, default behavior, and percentage range. This goes well beyond the schema descriptions.

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

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

The description opens with concrete examples of natural-language queries ('Is it true that...', 'fact check') and explicitly states the tool's function: claim verification against authoritative sources. It differentiates from siblings by detailing a two-path internal routing (SEC EDGAR vs grounded pipeline) and claims to replace 4–6 sequential calls, establishing a unique role.

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

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

The description clearly defines when to use the tool ('whenever the agent needs to check factual correctness') and provides examples of claim types. However, it does not explicitly list scenarios where an alternative sibling tool (e.g., deep_research, ask_pipeworx) would be more appropriate, nor does it mention when not to use this tool.

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