Listen Notes

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds value by explaining that the default model is free, that Anthropic requires a user-provided key, and that results include per-model fields like score, confidence, signals, and raw_response. This goes beyond the annotations to give a fuller picture of behavior.

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

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

The description is a single, well-structured paragraph. It starts with the core function and then provides additional details about models and use cases. There is no fluff; every sentence adds value.

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

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

The tool has 4 parameters and no output schema, but the description gives a solid summary of the return structure (per-model fields + combined view). It covers usage scenarios and key behaviors. Missing details like error handling or pagination, but given the tool's simplicity and annotations, it is mostly complete.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds meaning by explaining that _apiKey is needed only for Anthropic, that context helps disambiguate, and that the default model is Workers AI Llama-3.3-70b. This contextualizes the parameters 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 clearly states the tool probes LLMs for knowledge about an entity and provides a visibility score (0-100). It specifies the default model and the optional Anthropic model with BYO key. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' which is more specific.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to pass the _apiKey for Anthropic. However, it does not explicitly state when not to use this tool or compare it directly to siblings, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds context about routing to many tools and returning structured answers with URIs, which is useful 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 front-loaded with the key preference instruction and is detailed without being overly verbose. However, it could be slightly more structured with bullet points.

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 adequately describes the return format (structured answer with citation URIs). It covers all necessary context for a query tool.

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

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

Schema coverage is 100% but description enriches by specifying natural language input and providing multiple examples. It clarifies that the question can be in various forms.

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

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

The description explicitly states 'PREFER OVER WEB SEARCH' and lists many specific use cases like SEC filings, FDA data, etc., making the purpose very clear. It distinguishes from web search and sibling tools like 'search'.

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

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

Provides explicit guidance on when to use this tool over web search, with a list of query types and example queries. It also suggests use for factual questions with phrases like 'what is', 'look up', etc.

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 key behaviors beyond annotations, including explicit refusal reasons (not_in_source, no_tool_match, etc.), extraction method limited to tool results, and extra LLM call cost. Annotations already indicate read-only and idempotent, so this adds valuable context without contradiction.

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

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

The description is well-structured with the key purpose front-loaded. While comprehensive, it is slightly lengthy but every sentence adds value. Could be tightened by integrating the refusal reasons list more concisely.

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

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

Despite no output schema, the description fully explains the return format (success and refusal cases) and covers edge cases with detailed refusal reasons. It also mentions the extra cost and routing logic, making it complete for the tool's complexity.

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

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

With 100% schema description coverage, the schema already documents all parameters (question and aliases). The description adds no further parameter meaning; it focuses on behavior. 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the routing and extraction process. It explicitly distinguishes from sibling 'ask_pipeworx' by noting the extra cost and casual use case.

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

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

The description provides explicit when-to-use scenarios (high-stakes reads, quoted/cited answers) and when-not (casual lookups prefer ask_pipeworx). It also mentions the alternative tool 'ask_pipeworx' and the cost trade-off.

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. The description adds no behavioral context (e.g., rate limits, data freshness, or result structure) 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?

Extremely short but under-specified. The description is one sentence that says almost nothing. Conciseness at the expense of completeness is not beneficial.

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 4 undocumented parameters and an output schema not described, the description is entirely inadequate. It does not help an agent understand what to expect or how 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?

Schema description coverage is 0%, and the description fails to explain any of the 4 parameters (page, sort, region, genre_id). No value added beyond the schema's type definitions.

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

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

The description 'Top podcasts.' is vague; it doesn't state a verb or specify what the tool does (e.g., list, retrieve, or recommend). It barely differentiates from sibling tools like 'podcast' or 'search'.

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

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

No guidance on when to use this tool versus alternatives such as 'podcast' or 'search'. The description provides no context for selection.

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

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

The description extensively discloses behavioral details beyond annotations, including market resolution, classifiers, fan-out logic, response shapes, resolver contract, parent event extraction, news fields with fallback handling, safety mechanisms for low-confidence matches and closed markets, and tradeability warnings. No contradiction with annotations.

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

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

The description is very long and contains extensive detail, which is valuable but could be more concise. It is well-structured with clear sections and front-loaded purpose, but some information (e.g., full classifier list) may be excessive.

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

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

For a tool with 3 parameters, no output schema, and complex behavior, the description is exceptionally thorough, covering all observable behaviors, edge cases, and safety mechanisms. No gaps identified.

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

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

Schema coverage is 100%, and the description adds value by explaining the behavior of parameters like 'depth' and 'include_raw' with examples, and provides input format examples for 'market'. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and outputs, and while it doesn't explicitly differentiate from sibling tools, the core function is distinct and well-articulated.

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 scenarios are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives detailed fan-out examples for different bet types, but does not explicitly state when to avoid this tool or mention 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?

Description discloses key behaviors: parallel execution, data freshness, fiscal year handling, sorting by primary metric. Annotations (readOnly, idempotent) are consistent; no contradictions. Adds context beyond annotations.

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

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

Description is dense with valuable information and front-loaded with query examples. Slightly verbose but every sentence adds meaning. Efficient for the depth provided.

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

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

Covers data sources, handling of off-calendar fiscal years, sorting, and return format (paired data + URIs). With no output schema, description fully informs agent of what to expect. Completeness high 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?

Enriches schema by detailing what each type retrieves: 'company' pulls revenue, net income, cash, debt from SEC; 'drug' pulls FAERS counts, FDA approvals, trial counts. Values parameter explained with examples (tickers vs. names). Schema coverage is 100%, but description adds significant context.

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

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

The description clearly defines the tool's purpose: side-by-side comparison of 2–5 companies or drugs. It provides natural language examples and specifies data sources (SEC EDGAR, FAERS) and output (paired data, URIs). Distinguishes from sequential 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. Context and examples further clarify usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly.' No 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 concise and well-structured: first sentence states purpose, second lists use cases, third details output, fourth gives usage advice. 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?

The description fully explains the output (top-N tools with names, descriptions, schemas, examples) and how to use the tool. No output schema exists, so this is sufficient for an agent to understand the return value and execution behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the alias names (task, q, description, search) which are already in schema descriptions, but it reinforces the natural language usage with examples. Slight additional value over schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes from sibling tools (like 'search' and 'entity_profile') by being a meta-discovery 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?

Explicit guidance given: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set.' This clearly indicates when to use and implies when not to use (e.g., if you already know the tool).

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral details: patent API soft-fails until May 2025, uses fallback (GDELT→GNews), returns specific fields. Does not contradict annotations.

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

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

Front-loaded with example queries. Every sentence adds value, but the description is lengthy. Could be slightly more concise without losing key information. Structure is good overall.

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

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

No output schema, but description thoroughly explains return fields: cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents (with sunset note), news fallback, LEI. Covers input constraints and data source behavior comprehensively.

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. Description reinforces that value expects ticker or CIK, not names, and type is only 'company'. Adds practical guidance beyond schema enum and type 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 it provides a 'full cross-source profile of a US public company in ONE parallel call' with specific example queries. It lists data sources and outputs, making purpose unambiguous and distinct from sibling tools like resolve_entity or search.

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

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

Explicitly directs to prefer this tool over chaining individual lookups for holistic views. Also specifies that names are not accepted, advising use of resolve_entity first. Provides clear context for when to use and when not.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds no further behavioral context, but given the annotations, it is adequate.

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?

Extremely short but at the cost of clarity. It omits critical details, making it insufficient rather than 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 a single parameter with zero description coverage and an output schema present, the description should at least state that this is a retrieval tool. It fails to provide even minimal context.

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

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

The parameter 'id' has no description in the schema (0% coverage), and the tool description adds no meaning. The agent gets no information about what kind of ID is expected or how to format it.

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 'Single episode.' only identifies the resource type but fails to specify the action (e.g., retrieve, get). It does not clarify what the tool does with that single episode.

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

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

No guidance on when to use this tool versus its siblings (e.g., 'podcast', 'recommendations_for_episode'). An agent would have no context for selection.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds no extra behavioral details beyond stating deletion, such as idempotency or what happens if key doesn't exist. Adequate but no added value.

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: first states action, second provides usage context. No waste, information is front-loaded.

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

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

Tool is simple with 1 param and no output schema. Description covers purpose, usage context, and pairing with siblings. Annotations provide behavioral completeness. 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?

Single parameter 'key' is described in schema as 'Memory key to delete'. Schema coverage is 100%, so description adds no extra meaning. Baseline 3.

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

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

Description clearly states it deletes a memory by key, using specific verb 'delete' and resource 'memory'. Distinguished from siblings 'remember' and 'recall' which are create/read operations.

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

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

Explicitly says when to use: when context is stale, task done, or clearing sensitive data. Also mentions pairing with 'remember' and 'recall', providing clear guidance on 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?

Description discloses that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, and description adds context about output format 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?

Two sentences plus a use-case list, all front-loaded with purpose. No wasted words.

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

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

Description covers output format and use cases. With annotations and full schema coverage, it is mostly complete, though lacks error/limitation notes (e.g., invalid URL handling).

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

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

Schema coverage is 100% and description adds no additional meaning beyond schema. It reiterates default/max for max_links, but baseline 3 is appropriate as schema already 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?

Description clearly states 'Generate a production-ready llms.txt file for any URL' with specific verb and resource. Sibling tools list includes diverse tools but none similar, so differentiation is implicit.

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

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

Description explicitly lists use cases (getting client site indexed, drafting own project, auditing competitor) but does not specify when not to use or mention alternatives.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description does not add extra behavioral info but also does not contradict annotations. Baseline score is appropriate.

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

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

Extremely concise (two words) but lacks descriptive value. It is not verbose, but could include more context (e.g., what genres are).

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 output schema exists and no parameters, the description is minimally sufficient. However, it does not explain the concept of genres in this domain, making it less complete for an agent unfamiliar with the 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?

No parameters exist, so per guidelines baseline is 4. Description adds no parameter info, but none is needed.

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

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

Description clearly states 'List genres' with a specific verb and resource. However, it does not distinguish from sibling tools, but none of the listed siblings seem directly related to genres.

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

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

No guidance on when to use this tool vs alternatives. The description lacks any contextual hints about appropriate usage scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds specific return fields and confirms it lists active subscriptions, complementing 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?

Two front-loaded sentences: first states purpose and return fields, second provides usage context. No wasted words, highly efficient.

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

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

No output schema, but description lists return fields. Only one optional parameter covered by schema. Information is sufficient for a simple list operation.

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 description for 'include_inactive'. Description does not add details beyond schema, 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?

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and enumerates return fields. Distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly mention when not to use, but provides clear 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?

Discloses rate limit (5 per identifier per day), that it's free and doesn't count against quota. Annotations don't cover these behavioral aspects. Description adds context about team review and roadmap impact, which annotations lack.

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?

Concise paragraph, front-loaded with purpose, then usage, then constraints. Every sentence adds information; no redundancy. Efficiently covers purpose, when to use, how to describe, and limitations.

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 three parameters (one nested), description fully explains input parameters, usage constraints, and expected outcome. Covers what to provide, how to structure feedback, and behavioral notes (rate limit, quota).

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining enum values beyond schema (e.g., 'bug = something broke or returned wrong data'). For 'context' and 'message', it provides usage guidance (e.g., 'Be specific'). This adds semantic richness.

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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the action (telling) and resource (Pipeworx team), and differentiates from siblings by focusing on feedback rather than queries or actions.

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

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

Provides explicit guidance on when to use each feedback type (bug, feature/data_gap, praise). Offers usage tips: 'describe in terms of Pipeworx tools/packs' and 'don't paste end-user prompt'. Also notes rate limits and that it's free, helping the agent decide when to invoke.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), aggregation structure (pack, tool, count), and caching behavior (5min-1h). No contradictions detected.

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 paragraphs, front-loaded with purpose and use cases, followed by technical details. Every sentence adds value with no redundancy. Structure aids quick comprehension.

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

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

For a simple tool with one optional parameter and no output schema, the description covers return types (top tools, top packs, total volume), window options, caching, and data source. Complete and sufficient for 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 a detailed enum description. The tool description reinforces the window meaning but adds no new semantic details beyond the schema. Baseline of 3 is appropriate as the schema carries the load.

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 'top tools, top packs, and total call volume' over a window, specifying the verb 'Returns' and resource 'trending data on Pipeworx'. It distinguishes from siblings by offering unique trending analytics.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case) and explains window selection guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). No exclusions mentioned, but context is clear.

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

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

Annotations declare readOnlyHint, etc., but the description adds no behavioral context (e.g., return format, side effects). It relies entirely on structured fields, adding minimal value.

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?

Extremely brief (3 words), but under-specification reduces usefulness. Conciseness should not sacrifice clarity; front-loading a meaningful verb or noun is missing.

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 simple schema and output schema existence, the description fails to state the tool's action or return value. It is incomplete for an agent to correctly understand the tool's purpose.

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 0% description coverage for the single required 'id' parameter. The description does not explain what 'id' represents or how to obtain it, leaving the parameter entirely undocumented.

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 'Single podcast.' is vague; it does not state the verb (e.g., retrieve, fetch, get). It fails to differentiate from siblings like 'episode' or 'recommendations_for_podcast'.

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

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

No guidance on when to use this tool versus alternatives. Sibling tools exist (e.g., 'episode', 'best_podcasts'), but no criteria or exclusions are provided.

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 and idempotentHint. The description adds substantial behavioral context: the requirement that exactly one of event or topic must be provided (otherwise call fails), the underlying algorithms (monotonicity checks, partition-sum, Jaccard similarity, placeholder filtering), and the response structure. This goes well beyond the annotations.

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

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

The description is relatively long but well-structured with clear sections. It front-loads the essential requirement and then details each mode. Every sentence contributes necessary information; however, slight trimming could improve concise readability, but remains efficient.

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

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

Despite having no output schema, the description explains the response structure (opportunities array with fields). The tool is complex but the description covers all key aspects: input requirements, two modes, algorithmic details, response format. It is complete given the tool's complexity and the presence of sibling tools.

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

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

Schema coverage is 100%, so both parameters have descriptions. The description adds significant value by explaining that the event parameter accepts both slugs and full URLs, and that the topic parameter triggers cross-event scanning. It also clarifies the relationship between the two parameters (mutually exclusive). This enhances the schema's 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 specifies exactly what the tool does (find arbitrage opportunities via monotonicity violations and partition-sum checks) and distinguishes two modes: single-event mode using a slug and cross-event mode using a topic. This is specific and differentiates from siblings like 'polymarket_edges' and 'polymarket_kalshi_spread'.

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 each mode: single-event for a specific market, cross-event for scanning related events. It gives concrete examples. However, it does not mention when not to use or name alternative tools, though the context is clear enough.

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

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

The description discloses beyond annotations: caching at KV level keyed on knobs, a warning about edge already in price, and detailed diagnostics. No contradictions with readOnlyHint, idempotentHint, and destructiveHint annotations.

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

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

The description is long but well-structured: starts with purpose, then details model families, response structure, and knobs. Every sentence provides value, though some sections could be tightened.

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

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

For a complex tool with 9 optional parameters and no output schema, the description thoroughly explains the output format (by_segment, diagnostics, fed_candidates) and the meaning of returned fields. It also covers cache behavior and tradeable-edge filters.

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

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

With 100% schema coverage, baseline is 3. The description adds significant context for each parameter, e.g., for min_liquidity it explains 'dropping thin-book opportunities where executing the edge would walk the book past breakeven', and explains tradeable-edge knobs.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and gives a use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on edge detection from disagreement.

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

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

The description implies usage for discovering betting opportunities without paging hundreds of markets, and mentions built-in knobs for tradeability. However, it does not explicitly state when to use this versus siblings like polymarket_arbitrage or polymarket_kalshi_spread.

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 extensive behavioral context beyond annotations, including safety fields like compatibility_warning, temporal_alignment, and skipped counters. It explains edge cases such as non-equivalent bet shapes and temporal misalignment, which are not covered by the annotations.

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

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

The description is well-structured with clear sections and front-loaded purpose, but it is verbose in places, with detailed explanations of compatibility warnings and counters that could be more 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 the tool's complexity and lack of output schema, the description is thorough, covering modes, response fields, safety checks, and limitations. It leaves no major gaps for an agent to understand invocation and expected results.

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

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

Schema coverage is 100%, and the description adds value by explaining the two modes and how parameters interact (e.g., topic vs. explicit tickers). It clarifies overrides and provides examples, though the schema already documents parameters adequately.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on spread across venues. The two modes are explicitly defined.

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

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

The description explains when to use each mode and provides context on limitations, such as mentioning that most pre-mapped topics return a compatibility warning. However, it does not explicitly compare to alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds scoping detail (anonymous IP, BYO key hash, account ID) and listing behavior, enhancing transparency beyond annotations.

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

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

Three well-structured sentences, front-loaded with the primary action, no redundancy, 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers retrieval, listing, scoping, and links to sibling tools. Completely adequate.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description reiterates the optional nature and behavior when omitted but adds no new syntactic details. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a stored value or lists all keys, with specific verb+resource and distinct behavior for omitting the key. It distinguishes from sibling tools (remember, forget) by name and function.

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

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

Explicitly describes when to use (look up stored context) and implies when not (use remember to save, forget to delete). Provides concrete examples of use cases (ticker, address, notes) and mentions scoping to identifier.

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 that mark_read:true modifies state (flags events read), which is a side-effect beyond annotations. Adds value by explaining polling behavior and alternative access. Annotations indicate readOnlyHint and idempotentHint, but description's mention of state mutation is only a minor inconsistency, not a 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?

Four sentences, each with distinct purpose: purpose, return format, filtering/mark_read, and polling/alternative access. No redundancy, front-loaded with core action.

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 specifies what it returns. Covers all 5 parameters implicitly via examples. Mentions alternative access method. Sufficient for agent to understand tool fully.

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 practical examples (e.g., 'sec_8k' for type, ISO timestamp for since) and clarifies mark_read behavior. This goes beyond raw schema definitions and helps agent understand usage.

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

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

Clearly states the verb 'Pull' and resource 'fired events from your subscription feed'. Describes return format (source, citation_uri, raw event payload) and distinguishes from siblings like 'list_subscriptions' by focusing on alerts. No ambiguity.

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 filtering by type and since, using mark_read to update read state, and notes that polling works. Also offers an alternative HTTP endpoint. Lacks explicit when-not-to-use or comparison with siblings, but context is clear.

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

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

The description discloses behavioral traits beyond annotations, such as fanning out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO) with fallback logic (GDELT preferred, GNews on rate limit/5xx) and soft-fail for USPTO due to API sunset. It also describes the return structure (changes[] grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is well-structured and front-loaded with example queries, followed by technical details. It is concise yet thorough, with no redundant sentences. Each sentence contributes to understanding the tool's behavior and usage.

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

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

Given the complexity of fanning out to multiple sources with fallback and return structure, the description is complete. It covers all necessary aspects: purpose, parameters, behavior, return format, and alternative tool. The absence of an output schema is compensated by describing the return structure.

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 tool description adds value by integrating parameter usage into context, e.g., explaining that 'since' accepts relative shorthand like '7d' or '30d' and suggesting '30d' for typical monitoring. It also clarifies that 'value' can be ticker or zero-padded CIK. While schema already defines these, the description reinforces their application.

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 provides a change feed for a company over a recent window, with specific verb 'get change feed' and resource 'company'. It distinguishes from the sibling 'entity_profile' by indicating when to use the static profile instead. Example queries like 'What's new with X' reinforce its purpose.

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

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

The description explicitly provides usage context with example natural language queries and offers a clear alternative: 'Use entity_profile instead when you want the static profile'. This helps the agent decide when to invoke this tool versus the sibling.

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, providing a safety profile. The description contributes nothing beyond stating the purpose, lacking details on output format, pagination, or any potential side effects.

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

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

The description is extremely concise at two words, but this brevity sacrifices important context. It is not structured to provide useful guidance and feels incomplete.

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 the tool has an output schema (not shown), the description should explain what the tool returns (e.g., list of episode objects). It does not, leaving the agent without critical information about the response format.

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

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

With 0% schema description coverage and no parameter descriptions, the agent must infer the 'id' parameter's meaning solely from the schema example and tool name. The description does not explain what 'id' refers to (e.g., episode ID) or its format.

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 "Similar episodes" clearly conveys that the tool returns recommendations for episodes, distinguishing it from the sibling 'recommendations_for_podcast'. However, it lacks specificity about what similarity means.

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

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

No guidance is provided on when to use this tool versus alternatives like 'recommendations_for_podcast' or other related tools. The description does not include any context for selection.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond these annotations. It does not disclose anything about how recommendations are generated or any potential limitations.

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

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

The description is extremely concise at two words, which is efficient but omits necessary details. It is front-loaded but lacks structure. While brevity is valued, it sacrifices clarity on usage and parameters.

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 output schema exists (though not shown) and annotations cover safety and idempotency, the description provides minimal but sufficient context for a simple tool. However, it does not clarify the nature of 'similarity' or how results relate to the input.

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 one parameter 'id' with 0% description coverage. The description does not explain what 'id' refers to (e.g., a podcast ID, format, or source). The example shows a string but no further semantics are provided.

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 'Similar podcasts.' clearly indicates the tool returns recommendations related to a given podcast. The title reinforces that it is for podcasts. However, it does not specify the criterion for similarity (e.g., genre, audience) and does not differentiate from sibling tools like 'best_podcasts' or 'recommendations_for_episode'.

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

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

No guidance on when to use this tool versus alternatives such as 'best_podcasts' or 'podcast'. There is no mention of prerequisites, excluded uses, or context where this tool is preferred.

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

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

Adds important context beyond annotations: authenticated users get persistent memory, anonymous sessions retain memory for 24 hours, and storage is key-value scoped by identifier. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose and usage, no wasted words. Ideal structure for quick agent comprehension.

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

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

No output schema; description could hint at return value (e.g., success confirmation), but for a simple write tool it is sufficiently complete when paired with recall/forget guidance.

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

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

Schema has 100% coverage with descriptions and examples. Description mentions key-value pair but doesn't add meaning beyond schema, which is acceptable given full schema coverage.

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

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

Description clearly states the tool saves data for reuse across sessions, specifies concrete use cases (resolved ticker, target address, user preference, research subject), and distinguishes itself from siblings 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?

Explicitly says when to use (discover something worth carrying forward) and mentions companion tools (recall, forget). Does not explicitly state when not to use, but the context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: cascading through several lookup endpoints, auto-disambiguation for company input, and replacing 2-3 manual lookups. 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: opening with example queries, then usage recommendation, then detailed breakdown per type. Every sentence adds value without redundancy. It is concise given the amount of information conveyed.

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

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

Despite no output schema, the description fully explains return values for both entity types, including citation URIs. It covers internal behavior (cascade, auto-disambiguation) and notes it replaces manual lookups. Complete for a lookup tool with 2 parameters.

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

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

Schema coverage is 100%, but the description adds significant meaning: examples for parameter values, clarification that company can accept ticker/CIK/name and auto-disambiguates, and detailed return fields per type (e.g., ticker + CIK + company_name + citation URI).

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

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

The description clearly states the tool resolves names to official identifiers with specific examples and lists two supported entity types (company, drug), each with detailed return format. It distinguishes from sibling tools by emphasizing it's the first tool to use when a name is known but an ID is needed.

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 advises 'Use FIRST whenever you have a name but need an ID.' It provides context for when to use the tool, but does not include explicit when-not-to-use or alternatives. However, the guidance is clear and sufficient for most cases.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds behavioral context by explaining the internal probe mechanism (calling ai_visibility_check) and the ranking/surfacing of results. No contradictions are present, and the disclosure is consistent with the annotations.

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

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

The description is four sentences, front-loaded with the core purpose, then mechanism, use case example, and output summary. Every sentence contributes value without redundancy or waste.

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 (multi-entity comparison, use of child tool, ranking), the description fully explains what it does, how it works, when to use it, and what output to expect (ranked list with score, confidence, signal density). No output schema exists, but the description compensates adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add substantive meaning beyond the schema; the note about the first entity being the subject is already in the schema's description for the 'entities' parameter. No additional parameter semantics are provided.

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 compares AI visibility across multiple entities, specifically 'probes each entity... with ai_visibility_check' and ranks them, distinguishing it from the single-entity sibling tool ai_visibility_check. The verb 'compare' and resource 'AI presence' are specific.

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

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

The description provides a clear use case: competitive AI-marketing audits, with an example question. While it doesn't explicitly say when not to use it, the context implies using ai_visibility_check for single entities. No explicit alternatives are listed, but the sibling tool name is evident.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description details partial failures, timing issues (bundlephobia first measurement 5-30s), and graceful degradation behavior with sources_failed list. No contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the core purpose. While slightly verbose, every sentence serves a purpose, covering usage, limitations, return format, and error handling.

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

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

Given no output schema, the description lists return fields (summary block, per-advisory details, links, alternative versions) and explains partial failures. Covers complexity of multi-source tool with timing and fallback details.

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

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

Schema already has 100% coverage. The description adds context: scoped packages accepted, version defaults to latest, and provides examples ('@types/node', '18.3.1'), enhancing 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 explicitly states the tool's purpose as a composite check for adding npm packages, listing specific sources (deps.dev, bundlephobia) and return fields. It distinguishes from sibling tools by noting ecosystem scope limitations.

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 clear usage triggers ('is X safe / popular / small', 'what does adding lodash cost me') and explicitly states limitations: NPM ecosystem only in v1, with alternative tools for other ecosystems.

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 as false, so the safety profile is clear. The description adds no further behavioral context, but does not contradict 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 a single sentence, which is concise and front-loaded with the tool's purpose. However, it omits essential details, making it less effective despite its brevity.

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

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

Given 8 parameters, low schema coverage, and many siblings, the description is insufficient. It does not explain parameter usage or filtering options, leaving the agent without enough context for correct invocation.

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

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

Schema description coverage is only 38%, and the description provides no additional meaning for parameters like 'offset', 'len_max', 'len_min', 'language', 'genre_ids', or 'sort_by_date'. It fails to compensate for the low schema coverage.

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

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

The description clearly states the tool searches across podcasts, episodes, curated content, and people. It uses a specific verb and enumerates the resource types, which distinguishes it from siblings like 'search_within' or 'best_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?

No guidance is provided on when to use this tool instead of alternatives. With 30+ sibling tools, the description should give context on when to choose 'search' over, e.g., 'search_within' or 'best_podcasts'.

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 embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars with truncation and flag), and return details (passages with offsets and similarity scores). These go well beyond the annotations which only indicate read-only, idempotent behavior.

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

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

Every sentence provides valuable information. The description is front-loaded with the purpose, then usage guidance, technical details, and pairing. 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 has 3 parameters and no output schema, the description fully explains what the tool does, when to use it, technical mechanics, and return format. It also contextualizes it with a sibling tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for the query parameter and notes the default for limit, but does not significantly enhance 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 clearly states that the tool performs semantic search inside a fetched record, using a natural-language query. It provides concrete examples like SEC 10-K body and distinguishes itself from sibling tools by 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 says 'Use when the record is too big to cram into the prompt' and explains that it saves context. Also mentions pairing with ask_pipeworx_grounded for grounding over passages rather than whole documents.

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 contradicts the annotations: annotations include idempotentHint=true, but the description says 'Returns the new subscription id' implying each call creates a new subscription, which is not idempotent. This is a serious inconsistency.

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

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

The description is relatively long but well-structured with examples and clear sections. It conveys necessary information without fluff, though it could be slightly more 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 the tool's complexity (3 parameters, nested objects, no output schema), the description covers types, delivery channels, and limitations well. However, it does not describe the full return value or potential errors, which would be helpful.

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

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

The description adds significant meaning beyond the input schema by providing detailed examples and explanations for each parameter, especially the 'params' object and 'delivery' options. Since schema coverage is 100%, the baseline is 3, but the description adds rich context.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream. It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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 tool (to set up monitoring subscriptions) and notes that a Pipeworx OAuth account is required, implying anonymous/BYO users cannot use it. It does not explicitly mention alternatives or when not to use it, but the context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by specifying the output format (category-bucketed questions with tool+argument shapes) and that it draws from the live catalog. 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 slightly long but well-structured with front-loaded key info. It uses slashes to compactly list alternatives. Every sentence adds value, and the structure is clear.

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

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

Given the low parameter count (1 optional), no output schema, and rich sibling set, the description is complete. It covers purpose, usage, parameter details, and behavioral aspects adequately.

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

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

The single parameter 'topic' has 100% schema coverage with a good description. The tool description adds examples ('finance', 'pharma') and clarifies behavior when omitted (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 states the tool's purpose: it's an onboarding entry point that returns category-bucketed example questions with tool call shapes. It distinguishes from siblings by explaining it's for 'getting started' and learning what Pipeworx can do, using specific user intents like 'what can you do?'

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 this FIRST when you do not yet know what Pipeworx can do for you' and 'or to learn how to call the meta-tools'. It also explains optional topic filtering. No explicit when-not-to-use, but the context is clear for a discovery tool.

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

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

Beyond annotations (which indicate mutation, non-destructive, idempotent), the description adds critical details: ownership enforcement and that the row is deactivated (not deleted) so history remains. This enriches the agent's understanding.

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

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

Two concise sentences with front-loaded purpose. Every word adds value, 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 one-parameter mutation with no output schema, the description fully covers behavior, constraints, and side effects. No gaps left.

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

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

Schema coverage is 100%, and the description of the 'id' parameter matches the schema's description. The tool name and description do not add new meaning beyond what the schema provides.

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

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

Clearly states 'Cancel a subscription by id', which is a specific verb+resource. Distinguishes from siblings like subscribe and list_subscriptions, and adds nuance about ownership and deactivation.

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?

Implicitly tells when to use (cancel subscriptions) and mentions ownership constraint. Does not explicitly list alternatives or when-not, but context from sibling names makes it clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value beyond this by detailing the data sources (SEC EDGAR + XBRL), the return format (verdict types, structured form, actual value with citation, percent delta), and the scope (company-financial claims for public US companies). No contradictions.

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

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

The description is somewhat long but every sentence adds value. It front-loads the purpose and example queries, then provides details on scope and return type. No wasted words given 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 moderate complexity (a single string input, no output schema, but rich behavioral detail), the description is complete. It explains the domain, sources, verdict types, and what replaces, making it fully actionable for an agent.

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

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

Only one parameter 'claim' with full schema description coverage (100%), so baseline is 3. The description adds natural-language examples (e.g., 'Apple's FY2024 revenue was $400 billion'), which adds meaning beyond the schema's generic 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 uses specific verbs like 'verify', 'confirm', 'refute', and explicitly states the resource: natural-language claim verification against authoritative sources. It distinguishes from siblings by describing its unique domain and replacing sequential calls.

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 it replaces 4-6 sequential calls, giving clear usage context. It does not explicitly state when not to use it, but the domain restriction is clear.

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