Podcastindex

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it probes multiple models, defaults to free Workers AI, requires BYO key for Anthropic, and returns per-model details with combined view. 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 with no fluff: first states core action, second details models and API key, third covers return value and use cases. Front-loaded with essential 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, description explains return format (per-model fields + combined view). Covers use cases, required parameters, and optional behavior. 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?

All parameters have schema descriptions (100% coverage). Description adds context: default model for 'models', purpose of '_apiKey', and how 'context' disambiguates. Enhances understanding 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 uses a specific verb (probe), identifies the resource (LLMs), and clarifies the output (visibility score 0-100). It distinguishes itself from siblings like 'ask_pipeworx' by focusing on AI visibility audits.

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

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

Explicitly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Doesn't explain when not to use, but the use cases are clear. No mention of alternatives.

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness. The description adds meaningful behavioral context beyond that: it routes to a large corpus, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. It also notes speed and tier availability, so the agent knows what to expect from the call.

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: it front-loads the core preference over web search, then lists supported domains, triggering phrases, examples, and escalation paths. Some redundancy exists between the domain list and the examples, but every section serves a distinct routing purpose. It earns a 4 rather than 5 because it could be tightened without losing 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?

For a broad question-answering tool with no output schema, the description covers all essential ground: supported domains, when to use it, alternatives, examples, return format, and citation behavior. It explicitly states the output includes structured answers with stable citation URIs, which compensates for the missing output schema. An agent has enough information to invoke and interpret the result correctly.

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

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

Schema description coverage is 100%, and the description adds no parameter-specific details beyond the schema. The schema already documents 'question' and all aliases clearly, with examples, so the description does not need to compensate. The baseline 3 is appropriate because the tool relies on the schema for parameter semantics.

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

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

The description states a specific function: routing questions to 5,721 tools across 1,497 verified sources and returning structured answers with stable citation URIs. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and positions itself as the default entry point. This leaves no ambiguity about what the tool does.

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

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

The description explicitly tells the agent to prefer this tool over web search for factual questions, and gives concrete query patterns like 'what is', 'look up', 'find', and 'get the latest'. It also names alternatives for specific cases: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is exemplary when-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 cover read-only, idempotent, non-destructive, and open-world hints. The description adds valuable context beyond annotations: it is a beta version, currently matches ask_pipeworx exactly, has no active candidate, and is a live experimental edge. This informs the agent about potential variability and the fact that results are compared for merging. 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 three sentences that are information-dense and front-loaded: it opens with the beta designation, then clarifies the current state (no active candidate, identical to ask_pipeworx), and finally gives usage instructions. It is concise though could be slightly tightened (e.g., 'Falls back to nothing—this IS a full working router' is a bit redundant given the context). Still, 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 tool's complexity (a universal router over 5,721 tools) and absence of an output schema, the description covers the essentials: what it is, current behavior (identical to ask_pipeworx), and how to use it. It mentions 'same response shape' which compensates for the missing output schema. It does not provide a concrete example, but the parameter is a single natural language question, so examples are less critical. Overall, it is complete enough for an agent to call 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%, with each parameter described as an alias for 'question'. The description itself adds minimal parameter-specific information—only 'same arguments' and 'use it exactly like ask_pipeworx', which does not go beyond the schema's own descriptions. Basline 3 is correct when the schema already fully documents parameters.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router that handles natural language questions and routes to 5,721 tools. It explicitly distinguishes itself from the stable ask_pipeworx by being the experimental edge, and clarifies it is a full working router, not a fallback. This gives an agent a precise understanding of what the tool does.

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

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

The description says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. This gives clear context on when to prefer it (for the newest routing/experimental testing). It does not explicitly state when NOT to use it (e.g., when stability is critical), but the 'beta' label and experimental framing imply that. It could be more explicit about exclusions, so a 4 is appropriate.

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

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

Discloses the refusal behavior and exact response shape (both success and error refusals like not_in_source, no_tool_match), which goes well beyond the basic readOnly/idempotent annotations. It also reveals an extra LLM call cost and the grounding constraint 'using ONLY what the tool result contains', informing the agent of operational consequences.

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 carries a distinct piece of information: purpose, mechanics, return contract, usage policy, and cost/alternative. While dense, it remains structured and front-loaded with the most important qualifier first, with no filler.

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

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

No output schema exists, but the description supplies a full contract for both success and refusal paths, covering return fields, reasons, and the single required input. Together with annotations and schema, an agent has everything it needs to invoke correctly.

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

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

All 6 params are aliases for question and the schema already documents each as an 'Alias for question' (100% coverage). Description adds no parameter semantics beyond what input schema provides, so the baseline 3 applies.

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

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

The description opens with a specific value proposition ('Hallucination-resistant answer mode for high-stakes reads') and clearly differentiates from the sibling 'ask_pipeworx' by describing the same routing but a grounded extraction step. It states a concrete action (extract answer using ONLY the tool result) and resource (Pipeworx), so an agent can distinguish it from siblings.

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

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

Explicitly tells the agent when to choose this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains. It also states when not to use it: 'prefer ask_pipeworx for casual lookups,' naming the alternative and the cost tradeoff.

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 and idempotentHint. Description adds extensive behavioral details: low-confidence short-circuit, closed market status, spread warnings, resolution-rule risk, and response shapes. 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?

Description is very long but well-structured with bolded section headers. Front-loaded with purpose and usage. However, it is overly verbose with many details that could be condensed. Loses points for not being concise.

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

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

Given no output schema, description comprehensively explains all return fields: result.market, result.analysis, result.evidence, resolver contract, parent event, news fields, and edge cases. Covers all necessary context for correct 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. Description adds significant extra context: market parameter explains acceptable formats (slug, URL, question text), depth explains quick vs thorough, include_raw explains rationale for default false. Exceeds baseline.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying the verb and resource. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges, implying this is the general bet research tool.

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

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

Explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides classifiers and fan-out examples. Does not explicitly state when not to use, but context is clear enough.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: it discloses data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 compact yet informative, front-loading the core purpose with examples. It contains about 5 sentences, each adding value. Some redundancy (e.g., repeating 'side-by-side comparison' and 'head to head') but overall efficient. Minor room for tightening.

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 moderate complexity (two entity types, multiple data sources, no output schema), the description covers key aspects: what data is returned per type, sorting behavior, and citation URIs. It also explains edge cases like off-calendar fiscal years. The absence of an output schema is mitigated by mentioning 'paired data + citation URIs'. Sufficient for confident invocation.

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

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

Schema coverage is 100% with clear parameter descriptions, so baseline is 3. The description adds significant meaning: for 'type', it specifies what data is pulled for company (revenue, net income, cash, debt) and drug (adverse events, FDA approvals, trials). For 'values', it explains tickers/CIKs vs. drug names. This extra context helps the agent understand the semantics beyond the enum and array constraints.

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 does side-by-side comparison of 2-5 companies or drugs, with specific verb-resource pairs like 'compare entities'. It distinguishes from siblings such as entity_profile by saying it replaces sequential lookups and is preferred over 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?

Explicit guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It gives natural language examples for when to use (e.g., 'which is bigger/better', 'rank these companies') and implies not to use for single entity lookups.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, but the description goes far beyond: requires account (free/paid), latency ranges (15-90s), returns gaps[] for unanswered facets, never invents data, standard/thorough add contradictions[], citations only when resolvable, and semantic excerpting. This is rich behavioral disclosure 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 lengthy but highly information-dense; every sentence adds a distinct fact (auth, latency, gaps, citations, hop field). It is front-loaded with the most critical operational detail (account requirement and alternative). Some minor redundancy across repetitions of gaps[] and contradictions[], but overall efficiently packed.

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

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

For a complex research tool with no output schema, the description covers all essential context: auth prerequisites, alternative routing, return structure, edge cases (current news), latency, and depth behavior. An agent has everything needed to decide when to call and what to expect.

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

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

Schema description coverage is 100% and already documents both parameters. The description reinforces depth semantics (quick=3, standard=3+, thorough=6) and clarifies that question can be broad/multi-part, adding nuance beyond the schema's basic descriptions. Slightly redundant with schema but still valuable.

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+resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources' in ONE call, decomposing into facets and routing to 5,721 tools. It explicitly distinguishes itself from ask_pipeworx and open-web search, making its unique purpose unmistakable.

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

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

Provides explicit when-to-use and when-not-to-use guidance: use for broad/multi-part questions over structured data; use ask_pipeworx for single lookups, breaking/current-news topics, or when not signed in. Also specifies depth tiers and their trade-offs, leaving no ambiguity about alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about the output format (names, descriptions, full schemas with examples) and readiness to call, which goes 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 relatively concise, front-loaded with the core purpose, and efficiently covers domains, output, and usage guidance. Every sentence adds value, though could be slightly more streamlined.

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

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

With no output schema, the description fully accounts for explaining the return value (top-N tools with names, descriptions, schemas, examples). It covers all necessary context for a discovery tool, including the directive to call first.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by providing concrete examples of query values (e.g., 'look up FDA drug approvals') and explaining the aliases, which aids understanding beyond the schema descriptions.

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

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

The description states a specific verb ('Find') and resource ('tools'), lists concrete data domains, and distinguishes from siblings by positioning it as the discovery tool to call first when many tools are available.

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 when to use (browse, search, discover tools) and gives a clear directive to call it first in multi-tool scenarios. It doesn't provide explicit 'when not to use' or alternative names, but the context strongly implies its role.

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

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

Despite annotations already indicating readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds valuable behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), mentions specific return fields, and discloses limitations like the USPTO API sunset soft-failure and GDELT→GNews fallback. No contradictions with annotations.

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

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

The description is somewhat long (multiple sentences) but each sentence adds value: example queries, explicit usage preference, list of data sources and return fields, and constraint notes. It is front-loaded with examples and avoids redundancy. Could be slightly more concise but is well-structured for the complexity.

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

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

Given the tool's complexity (multiple data sources, potential failures, and no output schema), the description is remarkably complete. It covers edge cases (name unsupported, patent API sunset soft-fail, news fallback), lists all return fields with details (e.g., pipeworx:// URIs for filings), and directs to resolve_entity for missing functionality. No gaps for an agent to guess.

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

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

Schema coverage is 100%, with both parameters already described in the JSON schema. The description adds context beyond schema: explains that 'type' currently only supports 'company' (others coming soon), and 'value' must be ticker or zero-padded CIK, not names. It also links usage to resolve_entity for names, adding practical guidance.

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

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

The description clearly states the tool's purpose as 'full cross-source profile of a US public company in ONE parallel call' with concrete example queries (e.g., 'tell me about X', 'research Acme'). It differentiates from sibling tools like resolve_entity for name resolution and compare_entities for comparisons.

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 chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies input constraints: 'Pass ticker "AAPL" or zero-padded CIK... names not supported (use resolve_entity first if you only have a name).' This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds no behavioral traits beyond annotations; it mentions 'recent' but that's data-centric, not behavioral. 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?

Two concise sentences plus a clear example. No wasted words, 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?

For a list tool without an output schema, the description is fairly complete: it explains the function, returned fields, and includes an example. However, it lacks details on pagination, error handling, or whether episodes are strictly recent or all available.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds an example call but does not provide semantic value beyond the schema. 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 'List recent episodes for a podcast by its Podcast Index feed ID.' It specifies the verb (list), resource (episodes), and identifier (feed ID), and lists returned fields, distinguishing it from siblings like 'get_podcast' and 'search_podcasts'.

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 what the tool does but does not explicitly state when to use it versus alternatives or provide exclusions. The example implies typical usage, but no guidance on when not to use or which sibling to prefer.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which reinforces destructive nature but doesn't add significant new behavioral info 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: first for purpose, second for usage guidelines. Front-loaded and efficient with no unnecessary words.

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

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

Given the tool's simplicity (one param, no output schema), the description covers purpose and usage adequately. It could mention behavior when key doesn't exist, but idempotence is hinted.

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 single 'key' parameter described as 'Memory key to delete'. The description does not add extra meaning beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb (delete) and resource (memory). It distinguishes from sibling tools like 'remember' and 'recall' by specifying the action of 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?

The description provides explicit scenarios for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also references pairing with 'remember' and 'recall', though it lacks explicit when-not instructions.

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

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

The description discloses the tool's behavior: fetches the page, extracts title/description/key links, and emits standard markdown format. This adds value beyond the annotations (readOnlyHint, idempotentHint, etc.) by explaining the actual operations and the output nature. No contradictions with annotations.

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

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

The description is three well-structured sentences. The first sentence states the main purpose and target audience, the second explains the process, and the third lists use cases. No redundant or superfluous 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 low complexity (2 parameters, simple fetch+extract), the description covers the purpose, process, output format, and use cases comprehensively. Even without an output schema, the description clearly communicates what the tool returns.

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%, but the description adds extra context such as the default value of 25 and max of 50 for max_links, and explains that the output is a single text blob ready to drop at site-root/llms.txt. This goes beyond the schema's basic type and description.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the action (generate), the output format (standard llms.txt markdown), and distinguishes from siblings like scan_competitor_ai_presence by focusing on AI crawler indexing.

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: getting a client's site indexed, drafting your own llms.txt, and auditing competitor visibility. It provides clear context on when to use, though it does not explicitly mention when not to use or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the core behavioral traits are covered. The description adds value by listing the types of metadata returned and providing an example, but does not disclose additional behaviors like rate limits or authentication 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?

The description is a single concise sentence followed by an illustrative example. Every part earns its place with no redundancy or unnecessary 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 that there is no output schema, the description compensates by listing the returned fields. For a read-only, idempotent tool with good annotations, the description is reasonably complete. It could mention potential error conditions, but overall it provides sufficient context for correct selection and invocation.

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

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

Schema coverage is 100% (both parameters described in the input schema). The description mentions the feed_id example and the output fields, but does not add significant new meaning beyond what the schema already provides. The _apiKey parameter's purpose is described similarly in both places.

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 (Get), resource (full metadata for a single podcast), and method (by Podcast Index feed ID). It lists the returned fields, making the purpose immediately clear. It naturally distinguishes from sibling tools like search_podcasts and episodes.

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

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

The description clearly states when to use the tool (retrieve metadata for a single podcast given a feed ID) and implies that the feed ID comes from search_podcasts or trending. It does not explicitly discuss when not to use it or provide alternative tools, but the context is sufficient for an AI agent.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying return fields and default filtering (active only), which goes 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?

The description is extremely concise, with two short sentences that efficiently convey purpose, output, and usage. Every word 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 the tool's simplicity (single optional parameter, no output schema), the description adequately covers return fields and usage. Could mention if there is pagination or ordering, but not necessary for this case.

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 the single parameter. The description does not add significant meaning beyond the schema's own description, as it merely implies the default behavior without additional insight.

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 action ('List') and resource ('the caller's active subscriptions'), and the return fields are specified. It effectively distinguishes itself from sibling tools 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?

Explicit usage guidance is given: review before adding more subscriptions or find an id to cancel. This provides clear context for when to use the tool, though alternative tools are not named.

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

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

Annotations provide no hints (all false), so the description carries the full burden. It discloses the claim_token workflow (returned when filing without an account, reusable to read resolution), the team's daily digest review, the 5-per-day rate limit, quota exemption, and the scope restriction to this Pipeworx connection. This is rich behavioral disclosure far beyond what annotations offer.

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

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

Though the description is long, every sentence earns its place: purpose, use cases, exclusion scope, formatting instructions, token behavior, and rate limits. It is front-loaded with the core function and then layers details in logical order, making it appropriately sized for the tool's complexity.

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

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

With no output schema, the description must explain return values, and it does: it states that filing without an account returns a claim_token and explains the follow-up call to retrieve resolution. It also covers the four feedback types, scope boundaries, operational limits, and the relationship to the schema's nested context object. This is complete 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% and each parameter already has a description, so the baseline is 3. The description adds meaningful context for the claim_token parameter by explaining how to pass it back to read whether the report was fixed, and hints at the context parameter usage ('describe the issue in terms of Pipeworx tools/packs'). This extra usage context justifies a 4.

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 verb phrase 'Tell the Pipeworx team something is broken, missing, or needs to exist,' and immediately enumerates distinct use cases (bug, feature/data_gap, praise). This distinguishes it sharply from the sibling research/search tools and makes the tool's purpose unambiguous.

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

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

The description explicitly tells when to use the tool for each feedback type and, critically, when NOT to use it: it excludes tools from other MCP servers and directs the user to file with that server instead. It also provides formatting guidance (describe in terms of Pipeworx tools/packs, don't paste the end-user prompt), going well beyond basic usage.

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

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

The description adds valuable behavioral context beyond annotations: it explains the data is self-aggregating from analytics, no PII, and cached 5min-1h. This complements the readOnlyHint, idempotentHint, and openWorldHint annotations without contradiction.

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

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

The description is well-structured with a clear opening statement and bullet-point use cases. It is concise without unnecessary words, though the bullet list could be integrated for even tighter prose.

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

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

Despite lacking an output schema, the description explicitly lists what is returned (top tools, top packs, total call volume) and covers caching and derivation. For a simple tool with one optional parameter, this is fully complete.

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

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

The schema covers 100% of the parameter 'window' with a description. The tool description adds further nuance by explaining that shorter windows surface current trends while longer windows show steady-state demand, going beyond the schema's explanation.

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

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

The description clearly states the tool returns trending data from other AI agents on Pipeworx, including top tools, packs, and call volume. It uses a specific verb ('returns') and resource, distinguishing itself from sibling tools like 'trending' or 'discover_tools' by focusing on Pipeworx-specific trending.

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 enumerates three concrete use cases (discovering hot data sources, confirming canonical tools, assessing alignment) and notes caching behavior. However, it does not explicitly state when NOT to use or mention alternative sibling tools, slightly reducing score.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: monotonicity checks, partition_sum, Jaccard similarity filter, placeholder filtering, and the fill check that queries live CLOB depth before suggesting trades. No contradictions with annotations.

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

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

The description is well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and is front-loaded with the main purpose. However, it is lengthy; some details could be condensed without losing 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?

Despite no output schema, the description thoroughly explains the response format (opportunities[], partition_check fields, fill_check results) and edge cases (skipped_low_similarity, placeholders). It covers all necessary context for an AI agent to invoke the tool correctly.

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

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

Both parameters have schema descriptions (100% coverage). The description adds meaning: event accepts full URLs, topic triggers cross-event scanning with seed questions. It explains how each parameter affects the analysis, 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 the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and specifies what each does, differentiating it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly guides when to use each mode: 'Call with NO args for a trending_scan', pass event for a specific market, or topic for cross-event scanning. It also explains trade-offs (cross-event mode catches patterns single-event misses) and prerequisites like the fill check condition.

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 safe, idempotent read behavior. The description adds rich behavioral context: caching (1h), three model families, edge calculation with slippage and Kelly caps, 24h-move warnings, Fed bet exclusion, and diagnostic output. 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?

Despite its length, every sentence serves a purpose. The description is front-loaded with the core purpose, then structured into clear sections (model families, response segments, diagnostics). No fluff; highly informative 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?

The description completely explains the output structure (by_segment, diagnostics), what each opportunity contains (edge_pp_net, kelly_fraction, liquidity, etc.), why segments might be empty, and how knobs affect results. For a complex tool with no output schema, this provides all necessary 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 detailed parameter descriptions. The tool description explains the role of tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) in the context of the overall algorithm, but does not add significant meaning beyond the existing schema descriptions. 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 scans top Polymarket markets for discrepancies with Pipeworx data, and is built for 'what should I bet on today'. It defines three model families, but does not explicitly contrast with siblings like polymarket_arbitrage or polymarket_edge_tracker, though the purpose is distinct.

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

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

The description explicitly frames the tool for daily bet discovery without browsing hundreds of markets. It explains tradeable-edge knobs and diagnostics for empty segments, but does not specify when to avoid this tool or list alternative tools.

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

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

Annotations already mark it as read-only and idempotent. The description adds rich behavioral details: it reads from daily snapshots, explains response structure (tracked, expired, snapshot_dates), and discloses limits (60-day TTL, decay from closes). 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 and well-structured, starting with purpose, then answering a key question, explaining parameters, and detailing response format. It is somewhat lengthy but every sentence adds value.

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

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

Given 2 optional parameters and no output schema, the description fully explains the response format (tracked[], expired[], snapshot_dates[]) and all fields, plus limits. It is complete and leaves little ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions defaults ('default 14', 'default 1wk') and clamps (days 2-30) but does not add significant new semantics beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' for answering how long an edge has existed and if it's shrinking. It distinguishes from sibling tools like polymarket_edges by focusing on historical trends and decay, not just 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 explicitly answers a specific question ('how long has this edge existed and is it shrinking?'), implying when to use it. It does not explicitly state alternatives or when not to use, but the purpose is clear enough for an agent to infer appropriate contexts.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds essential behavioral context: it's a check tool, explains the risk of partial fills and unhedged positions. 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?

Description is lengthy but well-structured: starts with core purpose, then separates single-market and basket modes with clear bullet-like lists. Every sentence provides necessary detail. Slightly verbose but justifiable given complexity.

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

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

Given there is no output schema, the description fully enumerates return fields for both modes (top_of_book, vwap_fill_price, verdict, capture_ratio, profit_usd, thin_legs, etc.) and explains key risks. No gaps for an experienced trader using 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 has 100% description coverage, but the description adds significant semantic value: explains the dual modes (market vs event), default side selection logic, and interpretation of size_usd for each mode. This goes beyond the basic schema descriptions.

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

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

Description clearly states the tool checks realizable vs theoretical edge against live CLOB order-book depth, and distinguishes between single-market and basket modes with specific verbs and resources. It separates itself from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about partial basket fills converting arb into directional position, providing clear guidance on when not to rely on theoretical overround.

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 non-destructive, so the safety profile is covered. The description goes well beyond that: spreads are gross not net because Kalshi fees are not modeled, compatibility_warning and compatibility_codes can be non-empty even when matched_pairs>0, null temporal_alignment means 'could not compute' rather than 'aligned', and legs with unknown metric_type/match_subtype are never paired. 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; nearly every sentence carries a distinct operational fact, and labels like 'TWO MODES', 'RESPONSE', 'SAFETY FIELDS', and 'Codes' provide internal structure. It could be formatted with bullets or shorter paragraphs for easier scanning, but the complexity of the matching and safety semantics justifies most of the length.

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

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

With no output schema and a nontrivial response, the description covers the response shape, safety codes, per-entry flags, skipped counters, fee caveats, and the exact meaning of null temporal_alignment. An agent has enough context to invoke the tool and interpret ambiguous results 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 schema already covers all three parameters at 100%, so the baseline is 3. The description adds meaningful cross-param semantics: BOTH modes run the identical token-overlap matcher, and explicit kalshi_event_ticker/polymarket_event_slug values override the topic-mapped side. This helps the agent reason about interactions that the schema alone does not convey.

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

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

The description opens with a precise verb–resource pair: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. That scope distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, and the two modes are explicitly named and described.

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 the pre-mapped topic shortcuts versus explicit ticker/slug pairings, and warns that pre-mapped topics are often not tradeable ('pre-mapped ≠ tradeable', 'most pre-mapped topics return compatibility_warning today'). It does not explicitly name alternative tools or state hard when-not-to-use conditions, but the guidance is concrete 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scope detail (scoped to identifier) and pairing behavior, surpassing the annotations. 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?

Three sentences, front-loaded with main purpose. Every sentence adds value: retrieval behavior, use case, scope, and pairing. 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?

For a simple retrieval tool with one optional parameter and strong annotations, the description covers purpose, usage, parameters, scope, and relationship to siblings. No output schema is needed. Complete.

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

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

Schema coverage is 100% with description for 'key'. The description adds critical behavior: 'omit to list all keys', which is not in the schema. This adds practical 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 uses specific verbs ('Retrieve', 'list') and identifies the resource (values saved via remember, saved keys). It clearly distinguishes from sibling tools remember (save) and forget (delete).

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

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

Explicitly states when to use ('look up context... without re-deriving') and implies when not to (omit key for listing). Pairing advice with remember/forget provides clear context, though no explicit exclusion of alternatives.

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

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

The description fully discloses the tool's behavior including the effect of mark_read (flagging events as read so next call shows newer ones), the returned fields, filtering options, and polling suitability. However, note the annotation contradiction: readOnlyHint=true conflicts with the ability to mark events read.

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, front-loaded with the purpose, and every sentence adds value. No redundant or irrelevant 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?

Despite no output schema, the description explains what each returned alert contains (source, citation_uri, raw payload), covers side effects, filtering, and even provides an alternative access method. It is complete for a read tool with good annotations.

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%, providing baseline. The description adds meaning by explaining the effect of mark_read ('so the next call only shows newer ones') and giving an example for type ('sec_8k'). 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 'Pull fired events from your subscription feed' and details what is returned. It is specific about the resource and action, distinguishing it from sibling tools like subscribe or list_subscriptions.

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

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

The description provides clear context for using the tool (e.g., filtering by type and since, polling) but does not explicitly tell when to use it over alternatives or when not to use it. It mentions an alternate HTTP endpoint but no sibling tool comparison.

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 and idempotent behavior. The description adds substantial behavioral context: fans out to multiple sources (SEC, GDELT→GNews, USPTO with soft-fail), accepts ISO or relative dates, returns structured changes with URIs, and notes parallel execution. This goes 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 detailed but front-loaded with example queries that quickly convey purpose. Every sentence adds necessary information, though the length could be slightly trimmed. The structure is logical, starting with purpose, then behavior, then parameter tips, and ending with sibling distinction.

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 has 3 required parameters and no output schema, the description thoroughly explains the return format (changes[] array, total_changes, citation URIs) and the multi-source behavior. It also covers edge cases like fallback and sunset. The agent can fully understand what to expect 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 has 100% description coverage, providing clear definitions for all three parameters. The description adds extra value by including examples for 'since' (e.g., "7d", "3m"), specifying that 'value' can be a ticker or CIK, and noting that 'type' is currently fixed to 'company'. This expands on the schema, though not massively.

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 example queries like "What's new with X" and clearly defines the tool as a change feed for a company over a time window. It explicitly distinguishes itself from the sibling tool 'entity_profile' by stating when to use the alternative.

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

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

Provides explicit guidance on when to use this tool versus 'entity_profile' and gives a recommended default for the 'since' parameter ("30d" or "1m"). It also details fallback behavior and known limitations (PatentsView API sunset), helping the agent decide correctly.

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?

Discloses key behavioral traits: key-value storage scoped by identifier, persistence differences between authenticated and anonymous sessions (24 hours). This adds value beyond annotations, which only indicate idempotence.

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?

Five sentences efficiently cover purpose, usage, technical details, and tool relationships. No extraneous 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?

Missing no critical information for a simple key-value store. No output schema needed as behavior is clear. Could mention error conditions or size limits, but overall complete.

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

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

The input schema has 100% description coverage with examples. The tool description repeats these examples without adding new parameter-level detail, so baseline 3 applies.

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

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

The description clearly states the tool saves data for later reuse, with specific examples (tickers, addresses, preferences). It distinguishes from sibling tools by explicitly mentioning 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?

Provides explicit guidance on when to use: when discovering something worth carrying forward. It also advises pairing with recall and forget, offering clear context for alternatives.

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

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

Annotations already mark the tool read-only and idempotent, and the description adds significant behavioral context: graceful degradation of LEI/FIGI enrichment, explicit `unresolved` output, source labeling, `figi_candidates` for ambiguous matches, and internal cascading through multiple lookup endpoints.

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 and dense, but it is front-loaded with the core usage trigger and supported types. Most sentences add substantive edge-case knowledge that an agent benefits from, especially given the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return behavior. It covers identifier sources, ambiguous matches, unresolved identifiers, graceful degradation, and even example ISIN behavior—thoroughly enough for an agent to call the tool correctly in diverse scenarios.

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

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

Input schema coverage is 100%, so the baseline is 3, and the schema already documents `type` and `value`. The description and schema together add meaning beyond simple types—e.g., bond issuer matching nuances, ISIN-to-LEI resolution, and the distinction between brand and generic drug names—raising the score.

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

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

The description clearly defines the tool's purpose: resolving user-spoken names to canonical/official identifiers needed by other tools. It provides specific verbs and query patterns, explicitly distinguishes itself from tools like entity_profile and compare_entities, and details supported types.

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 an explicit trigger: 'Use FIRST whenever you have a name but need an ID,' plus concrete examples and entity types. However, it does not explicitly name alternatives or state when not to use this tool, leaving some routing ambiguity.

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. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns metrics (score, confidence, signal density), which is useful beyond annotations. 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 concise (5 sentences), front-loaded with the core purpose, and every sentence contributes value 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?

Given no output schema and 4 parameters, the description adequately explains input, process, and output format. It does not cover error handling but is 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 description coverage is 100%. The description adds extra meaning by explaining the first entity is treated as the subject and the context parameter for disambiguation, going 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 specifies a verb ('scan', 'compare') and resource ('competitor AI presence'), and distinguishes from sibling tools like ai_visibility_check by emphasizing multi-entity comparison and ranking.

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

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

The description includes a concrete use case (competitive AI-marketing audits) and implies when to use it, but does not explicitly state when not to use it or name alternatives like compare_entities.

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?

Discloses behavior beyond annotations: composite call to two services, potential 5-30s delay on bundlephobia first measurement, graceful degradation with sources_failed list. No contradiction with annotations (readOnlyHint, idempotentHint all consistent).

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

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

Dense but efficient; front-loaded with core purpose. Could be slightly more concise but every sentence adds value, including performance note and fallback behavior.

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 thoroughly details return structure (summary block, per-advisory detail, links, alternative versions) and partial failure handling. Fully covers what an agent needs to know given tool 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. Description adds context: scoped packages accepted, version defaults to latest, and ecosystem constraint. This adds marginal but meaningful value 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 tool performs a composite check for adding npm packages, covering license, advisories, bundle size, etc. It distinguishes itself by specifying the exact use case ('is X safe / popular / small') and the services used (deps.dev, bundlephobia), and is unique among sibling tools.

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

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

Explicitly states when to use ('whenever an agent asks...') and when not to ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), providing clear alternatives and handling of partial failures.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds context about the database source and return format but does not mention rate limits, cost, or behavior when the optional _apiKey is used. Since annotations carry the safety profile, the description is sufficient.

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

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

The description is extremely concise: two clarifying sentences plus a code example. It front-loads the purpose and includes a helpful example. No redundant or irrelevant 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?

The description covers the database source, search behavior, and return fields. It lacks information on pagination (e.g., offset/cursor) or sorting order, but for a simple search list tool with no output schema, this is adequate. The example provides concrete usage context.

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

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

With 100% schema description coverage, the schema fully explains all three parameters. The description provides an example usage pattern but does not add new semantic meaning beyond the schema. 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 verb 'search' and resource 'podcasts', and specifies the search domain ('open podcast database'). It lists return fields (title, author, description, etc.), making the purpose very specific. However, it does not explicitly differentiate from sibling tools like 'get_podcast' or 'episodes', which slightly reduces clarity.

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 via the example and mentions searching by term, but does not provide guidance on when to use this tool versus alternatives (e.g., 'get_podcast' for a single result or 'episodes' for specific episodes). No exclusions or prerequisites are 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?

Discloses retrieval method (BGE-base-en embeddings, cosine similarity, 500-char windows), output structure (passages with offsets and scores), and truncation behavior (200K char cap with flagging). This goes well beyond the annotations (readOnlyHint, idempotentHint) and fully informs 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 a single, well-structured paragraph that front-loads the core action and packs all essential information without redundancy. 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 having no output schema, the description details return values (passages with offsets and scores), truncation behavior, and embedding model. This makes the tool fully self-contained and actionable.

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 description adds value by explaining text as a fetched record, query as natural language with examples, and limit as max passages. This semantic enrichment helps the agent craft correct invocations.

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

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

The description clearly states the tool performs semantic search inside a single fetched record, using verbs like 'search INSIDE' and examples (SEC filing, article). It distinguishes itself from sibling tools by focusing on document-level retrieval rather than cross-document search, and even suggests a pairing with ask_pipeworx_grounded.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt.' Also describes how it pairs with ask_pipeworx_grounded for grounded answers. Provides clear context and alternatives, making it easy 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?

The description discloses behavioral details such as the requirement for an OAuth account, the persistent feed, optional delivery channels with specific constraints (e.g., phone verification, 10/day SMS cap, webhook auto-disabling). Annotations (idempotentHint=true) are complemented by the description's detail on subscription creation, with no contradiction.

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

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

The description is front-loaded with the core purpose, followed by structured details on requirements, types, and delivery. Every sentence adds necessary information without redundancy, maintaining conciseness 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?

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers purpose, return value, prerequisites, all subscription types and their parameters, delivery options, and even references related tools. It is fully actionable 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?

The schema has 100% coverage, but the description adds significant value by explaining type-specific parameters with examples (e.g., sec_8k items codes, polymarket_edge topics) and detailing the delivery object fields 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 starts with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly states the verb (create) and resource (subscription), distinguishing it from sibling tools like list_subscriptions (list) and unsubscribe (remove).

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 requires a Pipeworx OAuth account, lists supported types and delivery channels, and differentiates from recent_alerts for pulling alerts. It provides clear context on when to use the tool and mentions alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context: it is the onboarding entry point, returns categorized examples, and shows exact tool+argument shapes. 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 slightly long but well-structured with a front-loaded list of synonyms and clear explanations. Every sentence provides value, though minor tightening is possible.

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 optional parameter, no output schema, and annotations covering safety and idempotency, the description is complete: it explains what the output looks like, when to use it, how to use it, and provides examples.

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 optional parameter (topic), listing allowed values. The description adds further context by showing examples of topic values and explaining that omitting gives a full spread.

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

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

The description clearly defines the tool as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by specifying 'use this FIRST' and listing alternative meta-tools.

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

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

Explicitly states when to use the tool ('when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'), how to use it (no args or topic argument), and provides references to alternative tools.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds concrete behavioral details: it returns specific fields (title, author, categories, artwork, trend score) and provides an example call. This adds meaningful context beyond annotations. 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 two concise sentences plus a clear example. Every sentence adds value: first states purpose and filters, second lists return fields, third shows usage. No redundancy, perfectly front-loaded.

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

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

Given there is no output schema, the description sufficiently explains what is returned. The tool is simple and the description covers key aspects: source, ranking, filters, and return fields. It could mention pagination or default limit, but the schema's max property description covers the limit. Overall complete enough for this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions optional filters and the example shows parameter usage, but it does not explain semantics beyond what the schema already provides (e.g., default values or format constraints). This is adequate but not exceptional.

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 action ('Get trending podcasts'), the resource ('across the open podcast database'), and the ranking basis ('ranked by recent activity'). It also mentions optional filters. However, it does not differentiate from the sibling tool 'pipeworx_trending', so it loses a point for not helping the agent distinguish between similar tools.

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

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

The description provides a clear use case (getting trending podcasts) and includes an example invocation. However, it does not specify when not to use this tool or mention alternatives, leaving the agent to infer usage boundaries. This is adequate but lacks explicit 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?

Description adds context beyond annotations: it clarifies that the mutation is not destructive ('row is deactivated (not deleted)') and that historical events persist. Annotations indicate idempotentHint=true and destructiveHint=false, which align with the description, but the description provides valuable detail about the 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?

Two sentences, no wasted words. The description is front-loaded with the main action ('Cancel a subscription by id') and then provides essential behavioral details. 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 tool's simplicity (1 param, no output schema, no enums), the description is complete. It covers the action, ownership enforcement, and the soft-deletion behavior. No additional information is needed for correct usage.

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

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

Schema coverage is 100% (1 parameter with description). The description adds that the id is 'returned by subscribe', which provides source context beyond the schema's type/description. This is helpful but not critical given the schema already describes the 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?

Description clearly states the action ('Cancel a subscription by id') and the resource ('subscription identified by id'). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and soft-deactivation behavior.

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 the tool can be used: 'Ownership is enforced — you can only cancel your own subscriptions.' Also explains the effect (deactivation not deletion). However, it does not mention when not to use it or provide 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description richly discloses behavioral nuances: the distinction between could_not_verify and unsupported, the presence of verification_error{stage,detail}, and the instruction that could_not_verify must not be treated as evidence. It also reveals the underlying pipeline architecture (structured fast path vs. grounded fallback) and output citation format, providing substantial value beyond structured fields.

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

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

The description is longer than typical, but every sentence contributes meaningful information: example triggers, routing logic, output types, and critical caller guidance. It is structured with semicolons and a clear 'IMPORTANT for callers' note, making it dense but scannable. The length is justified by the complexity, so it earns a 4 rather than a 3.

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

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

With no output schema, the description fully covers the return contract: verdict enum values, actual value with pipeworx: citation, reasoning, and error semantics. It also explains the pipeline alternative to 4-6 sequential calls, addresses edge cases (could_not_verify vs unsupported), and provides enough about inputs and behavior to be independently actionable. The tool's complexity is high, and the description addresses all key dimensions.

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 schema already fully documents `claim` and `tolerance_pct` with examples and semantics. The description adds no parameter-level meaning beyond what the schema provides, though it does mention tolerance implication and hallucination detection in the schema itself. It appropriately doesn't repeat schema details but also adds nothing extra for the parameters.

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

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

The description states a specific verb and resource: 'natural-language claim verification against authoritative sources'. It clearly distinguishes the tool from siblings by defining its exact function (claim verification) and listing concrete example phrasings. It also separates financial claims (SEC EDGAR/XBRL) from other grounded claims, making the purpose unmistakable and unique among the sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two routing paths (financial vs. other claims). It doesn't explicitly name alternatives or when-not-to-use for open-ended research, so it stops short of a full 5, but the 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.