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?

The annotations already say readOnly, idempotent, non-destructive, and the description adds beyond that by explaining the routing behavior, that it fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, is one-shot and quick, and favors concise direct answers. This is valuable behavioral context not present in the annotations.

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

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

The description is longer than average and includes some slightly awkward phrasing in the 'START HERE' section, but it is front-loaded with the most important routing instruction and every section contributes useful selection or invocation guidance. The examples are dense and purposeful rather than filler.

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

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

For a tool with one meaningful required parameter and no output schema, the description is remarkably complete: it explains the input style, the domains covered, the output shape (structured answer with citation URIs), and when to choose sibling tools instead. Nothing essential for an agent to select and call this tool correctly is missing.

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

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

Schema coverage is 100%, and all parameters are aliases for the question field, so the schema already carries most of the semantic load. The description adds real value by giving example questions and trigger phras like 'look up', 'get the latest', and 'how much', which help the agent decide what content belongs in the single question parameter.

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

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

The description clearly states a specific verb and resource: it routes a natural-language question to the right tool among 5,767 tools and returns a structured, cited answer. It also distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, so an agent knows exactly what this tool is for.

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

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

The description is explicit about when to prefer this tool: it says 'PREFER OVER WEB SEARCH', lists trigger phrases and example questions, says 'START HERE for most questions', and names the alternatives for grounded hard questions and broad multi-part research. This gives an agent clear routing logic with no reliance on inference.

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 readOnly, openWorld, idempotent, and destructive annotations, the description adds valuable behavioral context: it may have candidate routing improvements live during evaluation, currently has no active candidate, matches ask_pipeworx exactly right now, and is a full working router rather than a fallback stub. This gives an agent an accurate mental model of the beta behavior.

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

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

Every sentence earns its place: the first establishes identity and capabilities, the second gives current status, the third gives usage guidance, and the fourth clarifies that this is a real router despite being experimental. The description is front-loaded and contains 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?

The description covers identity, current behavior, how to use it, and how it relates to the stable router. Since the output schema is absent, noting that it has the same response shape as ask_pipeworx is sufficient. Combined with schema and annotation coverage, nothing essential is missing for an agent to decide whether and how to call it.

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

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

Schema description coverage is 100%, and the input schema already documents the 'question' parameter and its aliases. The description only says 'same arguments' without adding new semantic detail, so the baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx with the same universal routing capabilities, same tools, same arguments, and same response shape. It explains the one functional difference — experimental candidate routing improvements — and implicitly distinguishes it from the stable ask_pipeworx sibling.

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 to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It does not give an explicit 'when not to use' or name a specific alternative for stable needs, though ask_pipeworx is clearly 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?

Beyond the readOnly/openWorld/idempotent annotations, the description reveals important behavioral details: it costs an extra LLM call, it returns an evidence quote, and it has an explicit refusal contract with enumerated refusal_reason values. This goes well beyond what annotations already convey.

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

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

The description is dense but well-organized: mode definition, routing and extraction mechanism, success/refusal return contract, usage guidance, and cost tradeoff. Every sentence earns its place, and the most important differentiator is front-loaded. No filler or redundancy.

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

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

For a tool with no output schema and a single natural-language question parameter, the description is complete: it explains the return shape, refusal cases, evidence format, cost tradeoff, and when to use alternatives. An agent has enough to invoke it correctly and interpret its response.

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 does not add parameter-level detail, but the schema already fully documents the question parameter and all six aliases. The tool effectively has a single semantic input, and the description's mention of 'fills arguments' reinforces the routing behavior without repeating schema content.

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

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

The description opens with a clear, specific label — 'Hallucination-resistant answer mode for high-stakes reads' — and explains the exact mechanism: route to a source tool, fetch data, extract only from the tool result. It also distinguishes itself from ask_pipeworx by the grounded/refusal behavior and the extra LLM call, so an agent can tell them apart.

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

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

Usage is explicit: use for answers that will be quoted, cited, or acted on, especially in domains where invention is dangerous (financial, legal, medical, public statements). It also gives the when-not-to-use instruction: prefer ask_pipeworx for casual lookups. This is actionable routing guidance.

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

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

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?

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description goes well beyond them: auth/gating (free tier, thorough needs paid plan), latency (15-60s, thorough ~90s), the gaps[] honesty guarantee ("never invented"), citation resolvability semantics (citation_uri only present when fetchable), contradictions[] behavior, and semantic excerpting of large records. No contradiction with annotations — the openWorldHint aligns with the candid note that gaps[] appear when a topic is not in the structured catalog.

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 (~280 words) but the tool is genuinely complex, and each sentence carries distinct information: auth gate, sibling routing, core mechanism, output packet, use-cases, exclusions, depth behaviors, citation semantics, latency. It is front-loaded with the most act_ion-relevant gate (auth requirement) before the core function. Minor deduction for re-explaining the depth enum semantics that the schema already covers in detail.

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

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

With no output schema, the description carries the full burden of explaining return values — and it does: findings packet fields (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, and citation_uri semantics. Combined with auth, latency, and 34-sibling routing guidance, everything an agent needs to invoke this tool correctly is present.

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

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

Schema description coverage is 100% and the depth enum is already well-documented (quick=3, standard=3 with gap recovery, thorough=6 paid). The description adds genuine value on top: concrete example questions for the question param, per-depth latency implications, and operat_ional notes on what depth changes in behavior. It does not fully re-explain the schema but complements it — solidly above the baseline 3.

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

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

The description states a specific verb and resource — "Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources" — and sharply distinguishes itself from open-web search ("this is NOT open-web search") and from the sibling ask_pipeworx. Concrete example queries ("compare X and Y's regulatory + financial exposure") anchor what the tool is for, so an agent can tell it apart from the 34 siblings without opening schemas.

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 and when-not-to-use guidance: best for broad/multi-part structured-data questions; for a single lookup, for breaking current-news topics, or when not signed in, use ask_pipeworx instead. It even names the fallback condition (not signed in) and the alternative tool by name, leaving nothing to inference.

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 readOnly/idempotent/openWorld hints, and the description adds substantial behavior beyond that: source fan-out, USPTO PatentsView sunset soft-fail, expected empty FDA sections for non-biologics, GDELT→GNews fallback, resolved:false for private companies, and explicit 'empty section is a real no-data, not a bug' messaging. No contradiction with annotations.

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

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

The description is long but dense, with useful front-loading of trigger phrases and the ALWAYS PREFER directive before the source/output details. It earns most of its length, though a single unbroken paragraph makes it harder to scan than a structured bulleted format would.

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 fully covers invocation shapes, resolution behavior, successful and failing source semantics, expected data sections, and error/edge-case behavior. An agent has everything needed to select and call the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents type and value. The description adds real value by clarifying that type='company' and type='ticker' behave identically, that value accepts ticker/CIK/name interchangeably, that names resolve via SEC EDGAR, and that private companies yield resolved:false. This goes beyond the bare 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 concrete trigger phrases and defines the tool as a 'full cross-source profile of a US public company in ONE parallel call'. It clearly names the resource (US public company), the verb (profile/brief/research), and distinguishes itself from single-pack lookups.

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 instruction 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' gives explicit when-to-use guidance, and 'when the user asks for a holistic view' sets the condition. It also excludes non-supported cases via 'person/place coming soon' and details the private-company fallback, so an agent knows when not to expect success.

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 already mark the tool read-only and idempotent, and the description adds substantial behavioral context: it does not model Kalshi fees, spread values are gross not net, pairs are matched by keyword/word overlap and not a shared resolution source, and unknown metric types are never paired. This goes well beyond what the annotations convey and does not contradict 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 long but well-structured with clear section markers like TWO MODES, RESPONSE, and SAFETY FIELDS, and it front-loads the core purpose. Some phrases are slightly redundant, but the density is justified because the tool has no output schema and the interpretation of safety codes is critical.

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 the response shape, safety fields, compatibility codes, per-entry flags, skipped-leg behavior, temporal alignment semantics, and fee caveats. An agent has enough context to invoke the tool and interpret its result correctly 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?

The input schema already documents all three parameters with 100% coverage, including the topic enum, Kalshi ticker, and Polymarket slug, along with override behavior. The description reinforces that both modes run the same matcher but adds little semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The opening line states the function precisely: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly names the resource, the operation, and the cross-venue scope, which distinguishes it from venue-specific siblings like polymarket_edges and polymarket_arbitrage.

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

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

The description explains two invocation modes, when to use the pre-mapped topic shortcuts versus explicit tickers, and warns that most pre-mapped topics currently return compatibility warnings. It does not explicitly name alternative sibling tools or state when to prefer them, but the usage context is 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 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, the description discloses meaningful runtime behavior: graceful degradation when GLEIF or OpenFIGI are unavailable, internal cascading of lookup endpoints, ambiguous-match behavior returning figi_candidates, and explicit unresolved fields for failed identifications. It also states that identifiers are source-labelled, adding decision-relevant context. No statement contradicts the readOnly, idempotent, openWorld, or non-destructive annotations.

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

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

The description is dense and front-loaded, opening with the core purpose and example triggers before the detailed behavior. It is long, with heavy parentheticals and some redundancy with the schema, but the detail is almost entirely relevant and earns its place for such a complex dual-type resolution 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?

With no output schema, the description carries the burden of explaining return behavior and does so for the key cases: source-labelled identifiers, figi_candidates for ambiguous instruments, and unresolved for failures. It also covers edge cases like non-US issuers via the ISIN path. A full JSON response shape is still not described, which keeps it at 4 rather than 5.

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

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

The input schema already describes both parameters at 100% coverage, so the baseline is 3. The description adds real value beyond the schema by explaining how type selects different output contracts (company identity spine vs drug RxCUI), how an ISIN maps to the issuing legal entity, and why full issuer noun phrases should not be passed as value. These nuances are not inferable from 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 clearly identifies a specific action — resolving a user-spoken name into canonical identifiers like CIK, LEI, ticker, and RxCUI — and supports it with concrete example queries. It does not explicitly contrast itself with sibling tools such as entity_profile or compare_entities, so it falls just short of the 'distinguishes from siblings' bar.

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

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

The description gives explicit triggering context ('Use FIRST whenever you have a name but need an ID') and enumerates supported entity types and input forms, including edge cases like ISINs and non-equity instruments. It does not say when not to use it or name a preferred alternative for a different need, stopping at clear context without full exclusion guidance.

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

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

Annotations already 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.