Youtube

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destruction. The description adds context about free vs. paid model probing but does not cover rate limits, response size, or error behavior. 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?

Four sentences, each with distinct purpose: what it does, default/key note, return format, use cases. No fluff, front-loaded with core purpose.

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

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

Without an output schema, the description adequately details return fields (score, confidence, signals, raw_response, combined view) and scoring range. Lacks error handling or edge-case notes, but sufficient for typical 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 baseline is 3. The description adds value via examples (e.g., 'Pipeworx' for entity) and payment nuance for _apiKey, going beyond the schema's 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 verb ('probe and score') and resource ('LLM knowledge of an entity'). It explicitly distinguishes from siblings by focusing on multi-model visibility scoring, unlike single-query tools like ask_pipeworx or research tools like 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 identifies use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains model choices (free default vs. BYO key). However, it lacks explicit exclusions or comparisons to sibling tools like scan_competitor_ai_presence.

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 substantial behavioral context: it routes to 5,529 tools, fills arguments automatically, returns stable citation URIs, works on every tier, and is a single fast call. It also implicitly acknowledges that ask_pipeworx_grounded is more reliable for hallucination-resistant answers, which is a limitation disclosed. 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?

Though longer than typical, every sentence earns its place. It is front-loaded with the most important directive ('PREFER OVER WEB SEARCH'), then explains routing behavior, gives usage triggers and examples, and finally escalates to alternatives. The structure is logical and there is zero 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?

For a routing tool with no output schema, the description is remarkably complete. It explains the overall behavior (routing, filling arguments, returning citations), covers when to use, provides examples, mentions it works on every tier, and directs to alternatives for specific needs. The agent has enough context to select and invoke the tool correctly in nearly any scenario.

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 enhances parameter understanding by explaining that the tool accepts natural-language questions and by providing diverse examples ('current US unemployment rate', 'Apple's latest 10-K', etc.). It also clarifies that the user only needs to supply a question, not structured arguments, which adds value beyond the schema's alias list.

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 unambiguously states the tool's purpose: it routes a natural-language question to the correct tool among thousands of sources and returns a structured answer with citations. It also explicitly distinguishes itself from siblings (ask_pipeworx_grounded, deep_research) by naming them as alternatives for different scenarios, which is exactly what the dimension requires.

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', and gives a list of trigger phrases ('what is', 'look up', 'find', etc.) plus concrete examples. It also clarifies when NOT to use it—when a hallucination-resistant answer is needed, use ask_pipeworx_grounded; for broad multi-part questions, use deep_research. This is textbook when-to-use vs. 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond annotations: the experimental nature, that no candidate is active currently, that it currently matches ask_pipeworx exactly, and that it 'is a full working router' rather than a fallback stub. This enhances understanding of its behavioral state.

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 moderately dense sentences. The first sentence front-loads core identification (beta, identical router, same tools/arguments/response shape). The second clarifies current state and usage, the third reinforces it is fully functional. There is minor redundancy but no filler, making it well-structured and reasonably 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?

Although there is no output schema, the description mentions 'same response shape' but does not elaborate, requiring reliance on ask_pipeworx knowledge. However, it thoroughly covers the tool's scope (5,529 tools), experimental routing, current inactive candidate state, and comparison with the stable router, providing sufficient context for an agent to invoke it correctly.

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

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

Schema description coverage is 100% with all six parameters documented as aliases for 'question'. The description merely notes 'same arguments' without adding new parameter information. Since the schema fully explains parameters, the baseline of 3 is appropriate.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx: identical universal router' that routes questions to 5,529 tools, and distinguishes it from the stable ask_pipeworx by the experimental routing improvements. The specific verb 'ask' and resource 'pipeworx' are evident, making 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?

It explicitly says '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. This provides clear when-to-use guidance and implies the stable ask_pipeworx as the alternative, satisfying the dimension fully.

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 substantial behavioral details beyond annotations: it routes through 5,529 tools across 1,455 sources, fills arguments, fetches data, and returns an explicit refusal with specific reasons when the data doesn't answer. It also reveals the extra cost and the exact return structure, which is not apparent from annotations alone.

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 front-loaded with the core purpose and key differentiator. It packs essential information (routing, extraction, return format, refusal reasons, usage guidance) into a few sentences, with minimal redundancy.

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

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

Despite no output schema, the description fully explains the return format and refusal reasons, covers usage context, cost implications, and behavioral constraints. It is complete enough for an agent to decide when and how 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 schema already covers the primary parameter 'question' and its aliases with full descriptions. The description adds no parameter-specific meaning, but since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from the sibling 'ask_pipeworx' by explaining that it extracts the answer using ONLY the tool result and returns evidence, making the purpose specific and unambiguous.

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

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

The description explicitly states when to use this tool (for answers that will be quoted, cited, or acted on) and when to prefer the alternative 'ask_pipeworx' (casual lookups). It also notes the extra LLM call cost, providing clear guidance on trade-offs.

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

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

Annotations already declare readOnlyHint, idempotentHint, and not destructive. The description adds extensive behavioral context: low-confidence short-circuits, closed-market handling, wide-spread liquidity warnings, resolver contract details, news fallback behavior, and cancellation rule parsing. These go well 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?

The description is very long and covers many details. It is well-structured with section headers and front-loaded with the core purpose, but still verbose. Some trimming would 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?

Given the tool's complexity and lack of output schema, the description comprehensively explains return shapes, resolver contract, fan-out behavior, edge cases, safety mechanisms, and resolution rules. It is fully complete for an agent to use 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 detailed descriptions for all three parameters. The tool description adds minimal extra meaning beyond the schema, mostly repeating format hints. 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 researches a Polymarket bet by pulling Pipeworx data in one call. It uses specific verbs and resources, and the examples and classifier list distinguish it from sibling tools like polymarket_edges 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 explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It does not explicitly mention when not to use it or point to alternatives, but the context is clear enough for an agent to decide.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with description. Description adds specifics: data sources, handling of off-calendar fiscal years, return of paired data and citation URIs. No contradiction.

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

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

Description is detailed but every sentence adds value, covering examples, data sources, sorting, and usage guidance. Slightly lengthy but well-structured with front-loaded examples.

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 explains return format (paired data + citation URIs) and sorting. Could specify exact metrics returned, but overall sufficient for the complexity of 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 covers 100% of parameters. Description adds semantic meaning: explains enum for type with context (company pulls 10-K data, drug pulls adverse events), and values with examples, constraints (2-5), and edge-case handling (off-calendar fiscal years).

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 it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with examples like 'X vs Y' and 'rank these companies'. It clearly distinguishes from sequential single-pack lookups, and mentions specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs).

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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides context: when to use (comparison queries), format of queries, and limitations (2-5 entities). Also explains sorting by primary metric.

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

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

The description goes far beyond the annotations by detailing internal behavior: it decomposes questions into facets, routes to 5,529 tools in parallel, returns gaps[] for unanswered facets, never invents findings, and includes contradictions[] for standard/thorough depths. It also explains semantic excerpting, latency expectations (15-60s, up to ~90s), and the meaning of hop fields. This fully discloses what happens during execution.

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

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

The description is long but information-dense; every sentence carries essential operational or selection guidance. It is front-loaded with the account requirement, then logically moves from purpose to usage to behavioral details. While not concise in length, its structure is appropriate for the tool's complexity and avoids redundancy.

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

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

Despite no output schema, the description completely characterizes the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation_uri, gaps[], contradictions[], and hop fields. It also covers edge cases (news topics returning gaps), semantic excerpting behavior, and latency, making the tool fully understandable without additional documentation.

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

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

Schema coverage is 100% with both parameters fully described. The tool description adds marginal value beyond the schema: the paid-plan requirement for depth:'thorough' and a brief rephrasing of depth's effect on hops. Since the schema already documents depth's behavior thoroughly, the description doesn't significantly enhance parameter understanding.

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 precisely that the tool performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, explicitly distinguishing it from open-web search. It names specific resources (SEC filings, FRED/BLS, FDA, etc.) and provides use cases like 'compare X and Y's regulatory + financial exposure'. It also differentiates from sibling tools by referencing ask_pipeworx as 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?

Clear when-to-use guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also states account requirements (free sign-in, paid tier for 'thorough') and notes that non-signed-in users should use ask_pipeworx. This explicitly guides 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?

Describes exactly what the return contains (names, descriptions, full schemas, curated examples) and that results are directly callable. Annotations already safe, description adds significant behavioral context beyond annotations.

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

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

Single paragraph is packed with essential information, front-loaded with purpose and examples, no wasted words. Every sentence earns its place.

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

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

Despite no output schema, description fully explains return format. With 6 params (mostly aliases) and 100% schema coverage, no gaps remain. Complete guidance 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 baseline is 3. Description adds value by listing alias parameters and providing usage examples, but mostly reiterates schema info.

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?

Specifically states it finds tools by describing data or task, lists numerous example domains, and clearly distinguishes from siblings (no other discovery tool among siblings).

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

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

Explicitly instructs to call this FIRST when many tools are available, and provides clear usage context with examples. Does not omit when-not-to-use as it's naturally implied.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds rich behavioral detail: fans out across multiple sources, mentions patent sunset date and soft-fail behavior, and describes 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?

The description is thorough but somewhat lengthy. It is well-structured with example queries and a clear list of return fields. However, it could be tightened slightly without losing information.

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

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

Given the tool's complexity (multiple data sources, fallback behaviors, upcoming sunset), the description covers all important aspects: input format, output details, source dependencies, and error handling. No output schema, but the description compensates 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 coverage is 100%. The description adds meaning beyond the schema by explaining that 'value' must be a ticker or zero-padded CIK and that names are not supported, pointing to resolve_entity as an alternative. This clarifies usage beyond the enum and type.

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 provides specific example queries like 'Tell me about X' and 'brief me on Tesla', clearly indicating the tool returns a full cross-source profile of a US public company. It lists all components (SEC, XBRL, patents, news, LEI) setting it apart from sibling tools like resolve_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?

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and 'Pass ticker or CIK — names not supported (use resolve_entity first)'. Clearly tells when to use and when not to use this tool vs alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description confirms deletion but adds no extra behavioral context beyond what annotations provide.

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, no waste, front-loaded with the core action, and includes usage guidance efficiently.

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 (1 param, no output schema, adequate annotations), the description is complete enough for an agent to understand and use correctly. Minor omission: no mention of return value or success confirmation.

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

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

Schema has 100% coverage with a clear description for the only parameter 'key'. Description does not add additional 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 'Delete a previously stored memory by key' which is a specific verb+resource. It distinguishes from sibling tools 'remember' and 'recall' by indicating deletion.

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 scenarios ('stale context, task done, clear sensitive data') and references companion tools, 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 already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral details (fetches page, extracts title/description/key links, outputs markdown) that go beyond annotations, providing a clear picture of the tool's operation 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 two sentences and a concise list, with no fluff. It is front-loaded with the main action and immediately provides context and use cases.

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 params, no output schema, safe annotations), the description fully covers what the tool does, how it works, and when to use it. No gaps remain.

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 parameter descriptions. The description mentions default and max for max_links, but the schema already includes that. Thus, description adds no new meaning beyond the schema, which is adequate.

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 verb (generate), resource (llms.txt file for any URL), and purpose (so AI crawlers can index the site cleanly). It distinguishes from sibling tools by specifying its unique function of generating the standard llms.txt format.

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 lists three use cases: indexing a client's site, drafting for own project, and auditing competitor. It does not provide explicit when-not-to-use or alternatives, but the given contexts are 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 already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying the default active filter, the returned fields, and the optional include_inactive parameter, providing sufficient 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?

Two efficient sentences: the first states purpose and return data, the second provides usage guidance. No wasted words, well 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 one optional param, the description covers purpose, return fields, default behavior, and usage context. No output schema exists, but return fields are explicitly listed, making it 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 coverage is 100% with a clear description for the only parameter (include_inactive). The description does not add further parameter details, but the schema already provides adequate 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 the verb 'List' and resource 'subscriptions', specifying 'active' to distinguish from inactive. It also lists fields returned, and the tool is distinct from siblings like subscribe and unsubscribe.

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: 'before adding more' or 'to find an id to cancel'. This guides the agent away from using subscribe or unsubscribe when a list is needed.

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

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

Beyond annotations, the description discloses rate-limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for follow-up, and that the team reads digests daily. It explains that filing without an account returns a token to check status, which is not apparent from 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, followed by usage, exclusions, mechanics, and constraints. Every sentence adds value—no fluff, despite 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 4-parameter tool with no output schema, the description covers the full workflow: what to report, scope boundaries, how to follow up via claim_token, rate limits, and impact. This is complete enough for an agent to use 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful guidance not present in the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' It also clarifies the claim_token flow in prose, though much of the parameter detail is already in the schema.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' giving a specific verb and resource. It clearly distinguishes itself from sibling research and subscription tools as the only feedback channel.

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

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

It explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an exclusion with an alternative: if the tool came from a different MCP server, file it there.

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, openWorldHint, idempotentHint, and destructiveHint, indicating a safe, non-destructive read operation. The description adds beyond this: explanation of data source ('derived from CF analytics-engine'), privacy guarantee ('no PII'), and caching behavior ('Cached 5min-1h'). 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?

The description is front-loaded with a single sentence defining the core functionality, then lists use cases, and ends with technical details. Every sentence provides essential information without redundancy. Concise and well-organized.

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

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

Given the tool's simplicity (one parameter, no output schema or nested objects), the description covers all necessary aspects: purpose, usage, parameter semantics, and behavioral traits (caching, no PII). No gaps are evident for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% for the single parameter 'window.' The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema enum values and helps the agent choose appropriately.

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 clear and specific statement: 'What other AI agents are calling on Pipeworx right now.' It explicitly mentions the resource (Pipeworx trending data), the action (returns top tools, packs, call volume), and the temporal scope (recent window). This distinguishes it from siblings like 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?

The description provides three concrete use cases with bullet points, such as 'discovering what data sources are hot for current events.' While it doesn't explicitly name alternative tools, the context implies when to use trending vs. other tools. The use cases are clear and actionable.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds rich behavioral context: how scans work, monotonicity checks, partition sums, fill checks against live CLOB depth, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder fraction >20%). 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?

Description is long but well-structured with clear mode distinctions. Every sentence adds value; front-loaded with purpose. Could be slightly more concise, but the information density is high without being repetitive.

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 tool complexity (multiple modes, fill checks, filters, return structures), the description covers most aspects. No output schema, but it explains return fields (opportunities[], partition_check). References polymarket_fill_risk for custom sizing. Could clarify 'monotonicity violations' briefly, but overall comprehensive.

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 have descriptions). The description adds significant meaning beyond schema: explains modes (no args, event, topic), provides example slugs and seed questions, and describes how each parameter triggers different internal logic. Enhances understanding beyond the schema alone.

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 arbitrage opportunities via monotonicity violations and partition-sum checks. It clearly distinguishes three modes (trending scan, event, topic) but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_edge_tracker, which address related but distinct concepts.

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: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Includes fill check advice ('do not trade it' when realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing. Lacks explicit 'when not to use' statements.

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 (readOnlyHint=true, idempotentHint=true) are confirmed by 'scan' and caching behavior. The description adds context: caching at KV level keyed on all knobs, segmentation logic, diagnostics for empty segments, and model fidelity details (e.g., 'soft signal w/ halved Kelly'). 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 wordy but packs valuable detail. It front-loads purpose and then dives into model families and knobs. While every sentence earns its place, the length could be intimidating; a more condensed version might improve readability without losing info.

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

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

Despite no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics) and caching. It covers model families, edge calculations, tradeable-edge filters, and filter_skips for debugging. Completeness is high given complexity (9 params, 3 segments).

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

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

With 100% schema coverage, baseline is 3. The description adds substantial meaning: e.g., 'Edge is evaluated NET of slippage' for min_edge_pp, 'bump for very thin partitions' for slippage_pp, and examples for min_liquidity like 'Set to 5000 to drop thin-book opportunities'. All nine parameters are explained beyond 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 verb ('scan'), resource ('Polymarket markets'), and unique outcome ('opportunities where Pipeworx data disagrees with market price'). It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by being a discovery tool that surfaces opportunities across segments.

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 it's for 'what should I bet on today' and that agents discover opportunities without paging hundreds of markets. It details tradeable-edge knobs (min_liquidity, max_spread_pp) that help decide when to filter. However, it does not explicitly contrast with alternative tools like polymarket_arbitrage or provide clear when-not-to-use guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds details about snapshot TTL, decay computation from daily closes, and the meaning of gaps, which are beyond annotations and add significant 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 relatively long but well-structured with purpose, argument details, response format, and limits. Every sentence adds value, though some redundancy exists with schema. It is front-loaded with the main purpose.

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

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

Given the complexity of edge persistence telemetry and no output schema, the description covers response fields (tracked, expired, snapshot_dates) and limitations (TTL, decay source). It is fully self-contained for an agent to understand the tool's capabilities and 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?

Schema coverage is 100%, so baseline is 3. The description repeats default and clamp values already in the schema, adding no new semantic meaning. It provides a bit more context on window family but not enough to exceed 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 it provides telemetry on edge persistence and decay from daily snapshots. It distinguishes from sibling tools like polymarket_edges by focusing on historical persistence rather than current 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 explains the tool answers how long an edge has existed and whether it is shrinking, with a clear example contrasting new vs old edges. It provides argument defaults but does not explicitly mention when to use alternatives, though context implies it for historical analysis.

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, idempotentHint, destructiveHint=false, which are consistent. The description adds rich behavioral details beyond annotations: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, verdicts, and explains risks like thin legs and forced directional risk. 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 relatively long but extremely dense with essential information. It uses clear separation for single-market and basket modes, bullet-like formatting, and front-loads the main purpose. Every sentence adds value, though it could be slightly more streamlined 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?

Despite no output schema, the description thoroughly explains the return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.). It also covers edge cases like thin_legs, forced_directional_risk, and max_clean_notional_usd. The complexity of the tool (two modes, risk warnings) is fully addressed.

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

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

Schema has 100% coverage with descriptions for all 4 parameters. The description adds value by explaining the two modes (market vs. event) and the different interpretation of size_usd in single-market vs. basket mode. While schema already covers basic parameter meaning, the description provides functional context.

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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. Distinguishes two modes (single-market and basket) and lists the outputs for each. Differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying use before executing trades.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about the risk of partial basket fills converting an arb into an unhedged directional position, providing clear when-to-use and when-to-be-cautious 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 declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description goes far beyond by detailing response structure (leg-by-leg prices, matched spreads), safety fields (compatibility_warning temporal_alignment skipped counters), and edge cases (non-equivalent bet shapes, unrelated events). It explicitly warns that spreads are mathematically meaningless when temporal alignment is false. 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 every sentence adds necessary detail. It is front-loaded with the core concept and organized into logical paragraphs. Some structuring (e.g., bullet lists) could improve readability slightly, but the density of information justifies the 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?

No output schema is provided, so the description must cover return values comprehensively. It explains each venue's leg-by-leg prices, matched spreads in percentage points, and safety fields including compatibility conditions and temporal alignment. For a complex cross-venue analysis tool, the description is complete and leaves no gaps about what the agent can expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing all topic values, explaining the override behavior when both topic and explicit tickers are provided, and giving example values. This clarifies parameter usage beyond the schema's property 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by specifying the two-venue comparison. The two modes (topic shortcuts and explicit tickers) are explicitly described, leaving no ambiguity about what the tool does.

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

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

The description explains when to use each mode: topic shortcuts for pre-mapped macros, explicit tickers for custom pairings. It provides a warning that most pre-mapped topics return a compatibility_warning, advising that pre-mapped ≠ tradeable. However, it does not explicitly state when not to use the tool or mention alternative tools for single-venue analysis.

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, non-destructive. Description adds scoping detail (by identifier) and pairing with remember/forget. 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, each purposeful. Front-loaded with primary action, then additional context. 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 tool with one optional param and full annotations, the description covers behavior, scoping, and related tools. No gaps.

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

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

Schema coverage is 100% and already describes 'omit to list all keys'. Description does not add new parameter semantics but reinforces the usage pattern.

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

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

Clearly states action (retrieve/list) and resource (saved memory). Distinguishes from siblings remember and forget by specifying pairing and contrasting usage.

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: to look up stored context without re-deriving. Mentions omitting key to list all. Does not explicitly exclude other tools but context 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, idempotentHint, and no destructiveness. The description adds behavioral specifics: the effect of mark_read on subsequent calls, return format details, and the existence of an external REST endpoint. It does not contradict annotations and provides extra insight beyond structured metadata.

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

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

The description is five sentences with no filler. It front-loads the core purpose, then efficiently adds parameter details, usage tips, and an alternative access method. Every sentence contributes distinct 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 all essential aspects: what it returns (source, citation_uri, raw payload), how to filter (type, since, unread_only), and the side effect of mark_read. It also addresses polling behavior and provides an external alternative. No gaps are apparent given 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% (baseline 3). The description adds value by giving concrete examples (e.g., 'sec_8k' for type, ISO timestamp for since) and clarifying the interaction between mark_read and unread_only. It explains the behavioral effect of mark_read beyond schema definitions.

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

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

The description clearly states the tool pulls fired events from a subscription feed and specifies the return fields (source, citation_uri, raw payload). It uses a specific verb-resource combination and distinguishes itself from sibling tools like 'list_subscriptions' by focusing on event retrieval rather than subscription management.

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

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

The description implies usage for polling alerts and mentions an alternative REST endpoint, but it does not explicitly compare with sibling tools or provide when-not-to-use guidance. It gives context for typical usage (polling, marking read) but lacks direct alternatives among the tool list.

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

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

Beyond annotations (readOnly, idempotent), description discloses fan-out behavior to multiple sources, fallback logic (GDELT→GNews on errors), and soft-fail for USPTO. 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?

Description is well-structured, starting with example queries, then listing sources, parameter details, and a clear alternative tool. Every sentence adds value; no fluff despite being detailed.

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, description explains the return format (changes grouped by source, total_changes count, citation URIs). Covers multi-source complexity, fallback behavior, and temporal reasoning, fully meeting the needs of 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%, and description adds examples and usage guidance for `since` (ISO date vs relative shorthand with examples like '30d', '1m') and clarifies `value` accepts ticker or CIK. Provides concrete recommendation for `since`.

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 provides a 'change feed for a company in the last N days/weeks/months' via one parallel call. It lists specific sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes from sibling tool `entity_profile` which is for static profiles.

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?

Description explicitly gives usage context with natural language queries ('What's new with X', 'latest on Y') and tells when NOT to use it: 'Use entity_profile instead when you want the static profile... regardless of window.'

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 idempotentHint=true and destructiveHint=false. Description adds context on scoping by identifier and persistence duration for authenticated vs anonymous sessions, which goes beyond annotations without contradicting them.

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

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

The description is concise but slightly verbose in places (e.g., 'across this conversation or across sessions'). Could be tightened 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?

Given the two required parameters, full schema coverage, no output schema, and sibling tools (recall, forget), the description fully covers purpose, usage, behavior, and related tools.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by giving examples of key values and clarifying that value is any text, improving understanding beyond the schema definitions.

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

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

The description explicitly states the tool saves data for later reuse, provides specific use cases (resolved ticker, target address, etc.), and distinguishes from siblings like recall 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?

Clearly states when to use (when discovering something worth carrying forward) and pairs with recall/forget. Also explains scope and persistence differences.

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 important behaviors: unresolved identifiers are explicitly stated rather than omitted, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple internal endpoints. These additions meaningfully inform the agent about reliability and output expectations.

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

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

The description is dense but well-structured with examples, a usage directive, and a supported-types breakdown. Every sentence contributes useful information, though the wall of parenthetical details could be slightly more scannable. It earns its length given the tool's complexity.

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

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

Despite having no output schema, the description fully covers expected return data (CIK, ticker, LEI, FIGI, RxCUI, etc.), sources, unresolved handling, graceful degradation, and input formats. It provides enough context for an agent to select and invoke the tool correctly across both entity types.

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?

Although schema coverage is 100%, the description enriches parameter semantics significantly. It explains how 'type' controls the entity kind and what 'value' should contain for each type (e.g., ticker, CIK, name, brand/generic). It also details the identifier set returned per type, which helps the agent choose appropriate values.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example queries and distinguishes it from sibling tools by emphasizing identifier resolution rather than profiles or general search.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies the types of entities ('company', 'drug') and accepted input forms. It does not explicitly mention when not to use the tool or name specific alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral detail: it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density. 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?

Three sentences, front-loaded with core purpose, no fluff. 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?

Given 4 params (1 required), no output schema, the description sufficiently explains what the tool does, how it works internally, and what the return structure includes.

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 extra meaning: first entity treated as 'subject' for narrative, models defaults to just workers-ai. This 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 compares AI visibility across multiple entities, using ai_visibility_check internally, and ranks them. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (general 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 explicitly says 'useful for competitive AI-marketing audits' and gives a concrete example question. It implies when to use but does not 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 (readOnlyHint, idempotentHint, destructiveHint) indicate safe behavior. The description adds context: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and sources_failed will list timeouts. 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?

The description is detailed but not overly verbose; each sentence adds information. However, it could be slightly more structured (e.g., summarizing return fields). Front-loading is good.

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

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

Given no output schema, the description thoroughly explains return values (summary block, per-advisory detail, links, alternative versions). It covers ecosystem scope, failure handling, and performance caveats. Exceptional 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 already describes both parameters. The description adds value by stating that version defaults to latest when omitted, and that scoped packages are accepted. This enhances understanding beyond the schema.

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

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

The description clearly states it is a composite check for evaluating npm packages, combining deps.dev and bundlephobia data. It distinguishes from siblings like 'scan_competitor_ai_presence' and mentions ecosystem limitations, making the purpose unambiguous.

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

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

Explicitly says when to use (e.g., 'is X safe / popular / small') and when not to use (alternative tools for other ecosystems). Also describes graceful degradation and timeout behavior, guiding correct invocation.

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, openWorld, idempotent, non-destructive. Description adds technical details (BGE-base-en embeddings, cosine, 500-char windows, 200K char limit, truncation with flag) and explains output features (offsets, similarity scores).

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

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

Four sentences, each with distinct value. First sentence states purpose, second gives usage guidance, third elaborates on benefits and pairing, fourth provides technical specifics. No redundancy.

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

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

Given no output schema, description fully explains what is returned (passages, character offsets, similarity scores), input constraints (200K char limit, truncation), and how it pairs with other tools. Comprehensive for decision-making.

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

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

Schema has 100% coverage with descriptions. Description adds real-world examples for text and query, and explains the return format (top-N passages with offsets and scores), going 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 it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, long tool result). It distinguishes from siblings by indicating when to use this over other tools ('use when the record is too big to cram into the prompt').

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 advises when to use (when record is too large for prompt) and pairs with ask_pipeworx_grounded for a recommended workflow. Provides strong guidance on context saving and passage retrieval.

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

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

The description adds significant behavioral context (delivery limitations, webhook auto-disable, phone verification, secret once) beyond annotations. However, there is a potential contradiction: idempotentHint=true vs. description implying creation of a new subscription each time, which could be confusing 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 fairly long but well-structured, front-loaded with the core purpose. It could be slightly more concise, but the density 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?

The description covers all aspects: purpose, prerequisites, type-specific parameters, delivery options with detailed nuances, limitations, and return value. No output schema is needed as the return is simple. It is complete for an agent to use confidently.

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 description enriches each parameter with concrete examples and constraints (e.g., item codes for sec_8k, topic for polymarket_edge, webhook signing details). This adds 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses specific verbs and resources, and distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

The description explains when to use (requires Pipeworx OAuth, not for anonymous/BYO users) and lists supported types with examples. However, it does not explicitly state when not to use or list alternatives, though context from sibling tools provides some 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false. The description adds valuable behavioral context: it returns example questions with exact tool/argument shapes, drawn from a live catalog, and explains that calling without arguments gives full spread. 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?

The description is somewhat long but well-structured. It front-loads with common user questions, then explains purpose, return format, and usage. Every sentence is informative; minor reduction could improve conciseness, but overall it is efficient 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?

No output schema, but the description fully explains the return value: category-bucketed example questions with tool/argument shapes. It covers when to use, how to call, and what to expect, making it complete for a simple onboarding tool with one optional parameter.

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 description for 'topic' listing possible values. The description enhances semantics by listing example values (finance, pharma, etc.) and explaining the behavior without topic (full spread) and with topic (focus). This adds meaning beyond the schema.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs like 'Returns' and 'Use this FIRST', and distinguishes itself from siblings like ask_pipeworx by positioning it as the initial tool to discover capabilities.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to call with no arguments for full spread or with a topic to focus, providing clear context and 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 indicate idempotentHint=true, destructiveHint=false. The description adds critical context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This explains the non-destructive idempotent behavior beyond what annotations provide.

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, no wasted words. The most critical information (action, ownership, behavioral trait) is front-loaded. 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 single parameter, clear schema, no output schema, and informative annotations, the description fully covers what an agent needs: purpose, usage constraint (ownership), and behavioral impact (deactivation vs deletion).

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 the single 'id' parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The tool description mentions 'by id' but adds no meaningful semantic 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 verb 'Cancel' and resource 'subscription by id'. It distinguishes this tool from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 ownership enforcement ('you can only cancel your own subscriptions'), which guides the agent on when to use this tool. It does not explicitly exclude scenarios but provides clear 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 declare readOnlyOpenWorld/idempotent, but the description adds critical behavioral details: could_not_verify means the check did not happen and must not be shown as evidence, unsupported means no covering source, and it explains the verdict enum, citation format, and error field. This goes far beyond the annotation hints.

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

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

The description is long but information-dense: trigger phrases, routing rules, verdict semantics, error caveats, and efficiency claims all earn their place. It is well-front-loaded with usage context, though slightly verbose for a two-parameter 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 fully enumerates possible verdicts, explains the distinction between could_not_verify and unsupported, describes the routing pipeline, and gives parameter guidance. For a tool with this complexity, the description provides comprehensive operational 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%, but the description enhances understanding by explaining that tolerance_pct overrides the claim-wording-implied tolerance, recommends 1–2% for hallucination detection, and provides concrete claim examples. This adds value beyond the raw schema definitions.

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

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

The description clearly identifies the tool as a fact-checker for natural-language claims against authoritative sources, with explicit trigger phrases and a specific scope (claim verification vs. general lookup). It distinguishes itself from siblings by emphasizing verdict outputs (confirmed/refuted/etc.) and a single-call pipeline that replaces multi-step sequential processing.

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 whenever the agent needs to check whether something a user said is factually correct' and explains routing for financial vs. other claims, plus a performance note about replacing sequential calls. However, it does not explicitly name alternative sibling tools or state when not to use it beyond the general 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 declare readOnly, idempotent, not destructive. The description adds value by specifying the type of data returned (subscriber count, etc.), but does not disclose potential rate limits or API key requirements beyond 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?

Single sentence, 14 words, front-loaded with the essential action. No redundant information.

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 low complexity, full schema coverage, and annotations, the description is mostly complete. However, it lacks clarification on parameter relationships (e.g., when to use channel_id vs username).

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 three parameters fully described. The description adds no additional parameter-specific details beyond listing them in the purpose.

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 'Get' and resource 'YouTube channel information and statistics', listing concrete data points. It clearly distinguishes from sibling tools like yt_channel_videos and yt_search.

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 on when to use this tool versus alternatives. The sibling list includes many YouTube-related tools, but the description provides no selection criteria or 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, idempotentHint, and non-destructive. Description adds value by specifying ordering (by date) and return fields (ID, title, description, publish date). 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 action and return fields. Every word earns its place; 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?

Description covers core functionality, but omits details like pagination, default max_results, or filtering semantics for date ranges. However, with annotations (openWorldHint) and output schema, it is mostly adequate.

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

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

All 5 parameters are described in the input schema with 100% coverage. The description does not add extra 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?

Description clearly states 'List recent videos from a YouTube channel, ordered by date' and lists return fields. This distinguishes it from sibling tools like yt_search (search by query) and yt_video_details (single video details).

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 on when to use this tool vs alternatives. With many sibling tools (yt_search, yt_video_details, yt_channel_details), the description should indicate scenarios like 'Use when you have a known channel ID and want a chronological list of recent videos' and 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context about returned snippet fields, which is sufficient beyond annotations.

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

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

Two sentences, no wasted words. The action and key result are 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?

Given the schema coverage, examples, output schema, and rich annotations, the description is complete enough for an agent to understand the tool's behavior and use 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?

All 7 parameters are fully described in the input schema (100% coverage). The description does not add significant meaning beyond what the schema and examples provide.

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

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

The description clearly states the tool searches YouTube for videos, channels, or playlists, and lists the returned snippet info. It is distinct from sibling tools like yt_channel_details or yt_video_details.

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 search functionality but does not explicitly guide when to use this tool vs sibling tools like yt_channel_details. No when-not-to-use or alternatives are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by specifying the returned fields (author, text, like count, publish date). However, it does not mention pagination behavior or potential rate limits.

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

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

The description is exceptionally concise—two sentences with no unnecessary words. It is front-loaded with the core action and return information.

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, rich annotations, complete schema, and existing output schema, the description covers the essentials. However, it omits the fact that only top-level threads are returned (not replies), which could be useful 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% with full parameter descriptions. The description does not add meaning beyond what the schema already 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 the tool retrieves top-level comment threads on a YouTube video, specifying the return fields. It distinguishes itself from sibling tools like yt_video_details and yt_search, which perform different functions.

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, such as for fetching replies or handling pagination. The context of top-level only is implied but not explicitly stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, providing clear safety and behavior signals. The description adds value by listing the types of fields returned (e.g., title, duration, counts), which supplements the annotations without contradicting them.

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

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

The description is a single, front-loaded sentence of 22 words that efficiently states the tool's purpose and key fields. Every word contributes, with no redundancy or filler.

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

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

Given the tool's low complexity (2 params with 100% schema coverage, rich annotations, and an output schema), the description is complete enough. It summarizes the core functionality, while the schema and annotations handle parameter and behavioral details.

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

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

Schema description coverage is 100%, with each parameter already having a clear description (e.g., video_id: 'Video ID or comma-separated list... max 50'). The tool description does not add additional parameter semantics beyond the schema, so a 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 ('Get') and resource ('detailed information about one or more YouTube videos'), and lists example fields (title, description, channel, etc.). This clearly distinguishes it from sibling tools like yt_search (searching) and yt_channel_details (channel info).

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 use for fetching video metadata but does not explicitly state when to use this tool vs alternatives (e.g., yt_search for finding videos, yt_video_comments for comments). No when-not or exclusionary criteria are provided.

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