Tmdb

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so safeness is clear. Description adds value by detailing return format (per-model + combined), default model (Workers AI Llama), and key requirement for Anthropic. No contradictions with annotations.

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

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

Two sentences, no wasted words. Front-loaded with purpose, then parameter behavior, then return format. 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?

For a tool without output schema, description fully explains return structure (per-model fields + combined view). All parameters are documented in schema, description adds use-case context. No gaps.

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

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

Schema coverage is 100% so description adds beyond schema: explains default model, that apiKey is for Anthropic, and context helps disambiguate. Adds meaningful context not in 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 probes LLMs for knowledge about entities and scores visibility 0-100 per model. It specifies the resource (LLMs), action (probe and score), and context (business/brand/etc.). Distinguishes itself from sibling tools by its unique functionality.

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 usage contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. Explains when to use optional apiKey for Anthropic probing. Lacks explicit 'when not to use' or alternatives, but context is clear enough.

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

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

Annotations already provide safety hints (readOnlyHint, idempotentHint). The description adds that the tool routes to many sources, returns structured answers with stable citation URIs, works on all tiers, and is fast. This enriches the behavioral understanding beyond annotations.

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

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

The description is thorough but lengthy, repeating some concepts (e.g., multiple data domain lists and examples). While all content is relevant, it could be more concise and structured for quicker agent parsing.

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 broad scope, the description covers purpose, usage, parameters, return type (structured answer with citation URIs), and alternatives. No output schema exists, but the description adequately explains the result.

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

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

Schema coverage is 100% with all parameters described. The description provides example questions and guidance on phrasing, adding value by showing how to use the 'question' parameter effectively.

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

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

The description clearly states the tool routes questions to 4,819 tools across 1259 sources, returning structured answers with citation URIs. It distinguishes itself from siblings by being the default entry point and explicitly contrasts with ask_pipeworx_grounded and deep_research.

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

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

Explicit guidance to prefer over web search for factual questions, start here for most queries, and step up to ask_pipeworx_grounded for single answers or deep_research for broad questions. Includes example queries and data domains.

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 details return structure (answer, evidence, refusal_reason, etc.) and refusal categories, disclosing behavioral traits beyond annotations (readOnlyHint, idempotentHint). No contradiction.

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

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

Description is dense but front-loaded with key purpose. Every sentence adds value, though slightly verbose. Could be more concise without losing information.

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

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

Given rich annotations, full schema, and detailed description of return format and refusal logic, the description is complete. No output schema needed as description covers it.

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

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

Schema has 100% coverage of parameter descriptions. Description adds context about routing and grounding but does not elaborate on the question parameter beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results, distinguishing it from the sibling 'ask_pipeworx' for casual lookups. Purpose is explicit and 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when to avoid: 'prefer ask_pipeworx for casual lookups', including cost trade-off ('Costs one extra LLM call'). Full 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?

The description adds extensive behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It details resolver contract, market-match confidence, parent-event extraction, news fallback mechanisms, safety short-circuits (low_confidence_match, market_closed_or_inactive), spread warnings, and resolution-rule risk. No contradiction with annotations is present.

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 (exceeding 1000 words) and highly detailed, which may overwhelm agents. However, it is well-structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loads the main purpose. It could be more concise without losing critical detail.

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

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

Given the tool's complexity (multiple classifiers, fan-out examples, response shapes, safety mechanisms) and no output schema, the description is remarkably complete. It covers all relevant aspects: input types, classifiers, fan-out patterns, response structure, resolver contract, parent-event extraction, news fields, safety short-circuits, spread warnings, and resolution-rule risk. No gaps in context.

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

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

With 100% schema description coverage, baseline is 3. The description adds meaning beyond schema by explaining the market parameter accepts slug, URL, or question text, and provides examples. It also clarifies the 'depth' enum (quick vs thorough) and 'include_raw' boolean with practical guidance on usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and output components (evidence packet, market-vs-model comparison). This distinguishes it from sibling tools like ask_pipeworx, which is a general Q&A 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?

The description explicitly lists when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides rich context with examples, but does not contain explicit when-not-to-use or direct comparisons to siblings, leaving some ambiguity.

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

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

Annotations already indicate read-only and non-destructive. Description adds behavioral details: results sorted by primary metric, handles off-calendar fiscal years, and includes citation URIs.

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

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

Front-loaded with user-like queries, then details data sources and behavior. Slightly verbose but justified by complexity. No unnecessary fluff.

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

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

Covers purpose, usage, data sources, and return structure. Sibling tools include entity_profile, making distinction clear. No output schema, but description mentions paired data and citation URIs.

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 enhances parameter understanding: explains what data each type pulls (SEC XBRL vs FAERS) and value format (tickers vs names).

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

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

Description uses specific verbs like 'side-by-side comparison' and lists example queries. It clearly distinguishes itself from single-entity lookups like entity_profile by emphasizing parallel calls for 2-5 entities.

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' and gives example phrases. Does not provide when-not scenarios, but context is clear.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds value by listing specific return content (image URL, sizes, change keys), which is consistent with annotations. No contradiction.

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

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

Two sentences, front-loaded with purpose, then usage. Zero wasted words. Efficient and clear.

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

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

Tool has no parameters, output schema exists. Description covers the key return elements and usage context. Fully complete for a simple configuration fetch 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?

No parameters; schema coverage is 100%. Description adds meaning by explaining what the output contains, which is sufficient for zero-parameter tools (baseline 4).

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

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

Clear verb+resource: 'Fetch TMDB API configuration'. Specific items listed (image URL, sizes, change keys). Distinguishes from siblings by being a general config tool, though no explicit sibling differentiation.

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 to construct full poster/backdrop image URLs from relative paths returned by other tools.' Provides clear when-to-use guidance, though no direct alternatives or when-not-to-use mentioned.

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

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

The description discloses key behavioral traits beyond annotations: it is not open-web search, it decomposes the question into focused facets, routes each to one of 4,819 tools in parallel, returns a findings packet with verbatim evidence, confidence, source, fetched_at, and stable citations, and includes explicit gaps for unanswered facets. It also mentions expected latency (15-60s) and that 'thorough' depth requires a paid plan. These details align with the readOnlyHint, openWorldHint, and idempotentHint annotations without contradiction.

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

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

The description is information-rich but fairly long. It is well-structured: it starts with the critical account requirement, then explains the core mechanism, output format, and usage tips. Every sentence serves a purpose, though some could be slightly more concise. The front-loading of the most important caveat (account requirement) is effective.

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

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

Given the tool's complexity (1259 sources, 4819 tools, parallel decomposition, no output schema), the description is remarkably complete. It covers the account requirement, input parameters, expected output format, use cases, limitations (e.g., not for breaking news), and latency. The absence of an output schema is compensated by a detailed description of the findings packet and gaps array.

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

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

The input schema already has full coverage (100%) with descriptions for both parameters. The description adds value by noting that the 'depth' parameter's 'thorough' option requires a paid plan, which is not in the schema. This extra context aids proper parameter selection. No additional meaning is needed for 'question' beyond the schema's natural language hint.

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 'Grounded multi-source research across Pipeworx's 1259 STRUCTURED data sources' and distinguishes itself from sibling tools like ask_pipeworx by specifying it decomposes questions into facets and runs them in parallel. It also contrasts with open-web search and breaking news use cases, leaving no ambiguity about 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?

Explicit usage guidance is provided: an account is required, and if not signed in, users should use ask_pipeworx instead. It also states that for breaking or current news topics, ask_pipeworx is preferred because deep_research returns empty gaps. Additionally, it gives a best-use scenario ('broad/multi-part questions over structured data') and a direct alternative for single lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds little beyond that, only mentioning it uses query params. No contradiction 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?

The description is only two sentences, front-loading the main action and then providing a critical preparatory step. 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?

The description covers the basic purpose and a prerequisite, but given the tool's complexity and lack of schema properties, it omits details like output structure, pagination, or error handling. An output schema exists but the description doesn't mention what it returns.

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

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

The input schema has no defined properties, so the description's list of filter types (genre, year, certification, etc.) adds essential meaning. The examples in the schema also help, but the description could be more detailed about parameter formats.

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

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

The description clearly states the verb 'Discover' and the resource 'TMDB movies', and mentions advanced filters. It also references the prerequisite tool 'genres_movie', distinguishing this from similar tools like discover_tv.

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 advises using 'genres_movie' first to get valid genre IDs, which is a helpful prerequisite. However, it does not explicitly compare this tool to siblings like discover_tv or search_movie, nor does it provide when-not-to-use 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 and idempotentHint. The description adds that results include full input schemas with curated examples and are ready to call directly. Missing details on how relevance is computed, but overall adds 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?

The description is a single dense paragraph with all critical information: purpose, use cases, return content, and call order. It is front-loaded and every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains exactly what is returned (names, descriptions, schemas, examples). It fully covers the tool's behavior and parameters, making it complete for agent use.

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

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

The input schema is fully described (100% coverage). The description adds that the query parameter accepts multiple aliases (task, q, description, search) and specifies limit defaults and max, enhancing schema documentation.

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: finding tools by describing a data or task. It lists many specific domains and indicates it returns top-N relevant tools with full schemas, distinguishing it from sibling tools that are specific 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 says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear context for when to use versus alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds minimal behavioral context beyond listing some filter types. It is consistent with annotations but does not significantly enhance transparency.

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

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

Two direct, front-loaded sentences with no extraneous words. Every sentence serves a purpose: first explains the tool's capability, second provides a prerequisite 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?

Given the tool has an output schema, return values are not required. However, the description omits important context like pagination behavior, whether filters are mandatory or optional, and the fact that the schema is open-world. It is adequate for basic use but has gaps for comprehensive usage.

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

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

The input schema has no defined properties (only examples), so schema coverage is effectively 100% but empty. The description compensates by listing available filter categories (genre, first_air_date, vote average, network, sort order) and referencing the open-world nature with 'etc.', adding meaning beyond the minimal 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 discovers TMDB TV shows with advanced filters, specifying the resource and action. It distinguishes from siblings like discover_movie (movies vs TV) but does not explicitly differentiate from search_tv or other filtering tools, so it's clear but lacks explicit sibling differentiation.

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 one specific guideline: use `genres_tv` to get valid genre IDs. However, it does not explicitly state when to use this tool versus alternatives like search_tv or discover_movie, leaving usage context partly implied.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds valuable context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), soft-fails for patents, and details return fields. No contradiction.

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

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

Description is comprehensive but slightly long; however, it is well-structured with examples first and details following. Every sentence earns its place.

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

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

No output schema, but description thoroughly explains what is returned (cik, company_name, recent_filings, fundamentals, patents, news, LEI) without needing further documentation.

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

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

Schema coverage is 100%. Description adds meaning: type is only 'company' today, value must be ticker or CIK, names not supported—important guidance beyond enum/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 provides a 'full cross-source profile of a US public company' and lists numerous example queries. It clearly distinguishes from siblings like resolve_entity by specifying that names are not supported.

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

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

Explicitly advises to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives clear when-not-to-use: if only have a name, use resolve_entity first.

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

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

Annotations already declare destructiveHint=true; description adds context about clearing data but doesn't exceed annotation 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 sentences, front-loaded with action, no fluff.

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

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

Simple tool with one param, clear annotations, description covers purpose and usage sufficiently.

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

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

Schema covers 100% of param with description; description doesn't add extra semantics beyond what 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?

Description specifies 'Delete a previously stored memory by key' – clear verb and noun, distinct from siblings like remember and recall.

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 when-to-use: 'stale context, task done, clear sensitive data', and suggests pairing with remember/recall.

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, so the description's addition of 'fetches the page, extracts title/description/key links' adds process context but no behavioral cautions beyond what annotations provide.

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

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

The description is concise (four sentences) and front-loaded with core purpose, then details and use cases. No redundant or unnecessary information.

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

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

Given no output schema, the description explains the output format ('standard llms.txt markdown format', 'single text blob'), and covers use cases. Tool is simple with two parameters, so completeness is achieved.

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 does not add meaningful detail beyond the schema's parameter descriptions. The schema already explains 'url' and 'max_links' 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 generates a production-ready llms.txt file for a given URL, explaining the extraction process and output format. It distinguishes itself from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on creating the specific file.

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 concrete use cases (client indexing, personal project drafting, competitor auditing), providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or offer alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns genre IDs, which provides some behavioral context beyond the schema, but does not elaborate on output format, data freshness, or any potential side effects. Given the rich annotations, a 3 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?

The description is a single, front-loaded sentence that conveys purpose and usage without any fluff. Every word is justified.

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 an output schema, the description covers the core functionality and usage. However, the lack of parameter documentation and the absence of information about default behavior or output structure (even though output schema exists) make it incomplete.

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 'language' with no description (0% schema coverage). The description does not mention the parameter at all, leaving its purpose and format unexplained. This is a significant gap.

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 it is a movie genre directory with examples and IDs, and specifies that it is used to filter discover_movie by genre. It clearly distinguishes from the sibling tool 'genres_tv' by focusing on movies.

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

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

The description explicitly states when to use the tool: 'Use to filter discover_movie by genre.' This gives clear context and implies that for TV genres, one should use the sibling tool 'genres_tv'.

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 destructiveHint=false, so the agent knows it's a safe read operation. The description adds that it returns genre IDs, which is useful but not extensive. No contradictions.

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

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

Two sentences that are front-loaded with the core purpose. Every word serves a purpose. Could be slightly improved by including parameter mention, but overall concise and well-structured.

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

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

For a simple list tool with an output schema, the description covers the main intent and usage. However, the lack of parameter documentation is a notable gap, making it less complete. The output schema likely covers return values, so that's 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?

The schema has one parameter 'language' with no description and 0% schema description coverage. The tool description does not mention this parameter at all, failing to add any semantic meaning beyond the bare schema.

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

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

The description clearly states this is a TMDb TV genre directory, lists examples of genres, and explicitly says it provides genre IDs for filtering discover_tv. It effectively distinguishes from the sibling tool genres_movie by specifying 'TV'.

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 this tool: 'Use to filter discover_tv by genre.' This provides clear context. However, it does not mention when not to use it or explicitly compare with genres_movie, but given the sibling list, it's implied.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the specific fields returned and the include_inactive parameter behavior, providing additional behavioral context.

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

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

The description is two sentences: first states purpose and output, second gives usage guidance. Every sentence is necessary and 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?

The tool is simple with one optional parameter. The description covers purpose, return fields, and usage context, making it fully informative 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?

Schema coverage is 100% and the parameter is well-described in the schema. The description does not add further semantics beyond 'active subscriptions', so baseline score 3.

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

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

The description clearly states 'List the caller's active subscriptions', specifying the verb and resource, and lists returned fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

The description provides specific usage scenarios: 'review what you're monitoring before adding more or to find an id to cancel', giving clear context for when to use 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it returns specific fields and supports optional appendix, but doesn't add significant behavioral context beyond the annotations.

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

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

Two sentences, no fluff, front-loaded with purpose. Every sentence earns its place.

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

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

For a simple data retrieval tool with good annotations and an output schema, the description covers the return fields and parameter usage adequately. It is complete and actionable.

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

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

Schema coverage is 0%, so the description must compensate. It explains movie_id and append_to_response with examples, but does not cover the language parameter. This adds value but leaves a gap.

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 fetches full TMDB movie details by movie_id, listing specific fields returned. This distinguishes it from siblings like discover_movie, search_movie, and movie_credits.

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 mentions when to use the tool (to fetch movie details) and the optional append_to_response parameter for additional data. It could be improved by stating when not to use it, but it's 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, destructiveHint, idempotentHint, and openWorldHint. The description adds behavioral context about the type of data returned (cast and crew), which is consistent with annotations. No contradictions.

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

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

The description is a single concise sentence plus a usage hint. Every part adds value, and it is front-loaded with the core purpose.

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

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

Given an output schema exists, the description doesn't need to detail return values. It covers the main use case well but omits the language parameter. Overall, it's fairly complete for a simple lookup tool with good annotations.

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

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

Schema description coverage is 0% (no parameter descriptions in schema). The description mentions movie_id implicitly ('by ID') but does not explain the language parameter. The example helps but a 0% coverage requires more compensation; missing parameter semantics for language reduces score.

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

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

The description clearly states it provides 'full cast + crew for a movie by ID' and lists return fields (actor names, characters, order, department, job). It also gives example queries, making the purpose specific and distinct from siblings like movie_recommendations or movie_videos.

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

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

The description provides explicit usage contexts: 'use for "who played X in Y", "who directed Y", "behind-the-scenes credits"'. It doesn't explicitly state when not to use, but the presence of sibling tools implies 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 indicate read-only, idempotent, and non-destructive behavior. The description adds the return fields (title, overview, etc.) but does not disclose additional traits like pagination, rate limits, or API-specific constraints. Bar is lower due to annotations.

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

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

Single sentence, front-loaded with the core action, no wasted words. Efficient and clear.

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

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

Describes the core functionality and return fields, but omits optional parameters. Given moderate complexity and the presence of an output schema, the description is adequate but not fully comprehensive.

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

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

With 0% schema description coverage, the description should compensate but only mentions 'movie_id' while ignoring 'page' and 'language' parameters. No details on format, defaults, or optionality 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 action ('Fetch TMDB-recommended movies similar to a given movie') and specifies the resource and output fields. It differentiates from siblings like 'search_movie' (keyword search) and 'movie' (single movie details).

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

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

The description implies usage for getting recommendations based on a movie ID, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'search_movie', 'trending'). No when-not-to-use or prerequisite info.

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 the tool is read-only, non-destructive, idempotent, and open-world. Description adds value by specifying the returned fields (name, site, key, type, official flag), providing behavioral context beyond the annotations.

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

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

Single sentence, front-loaded with the action and resource, no redundant information. Highly concise and clear.

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

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

For a simple fetch tool with an output schema, the description combined with annotations fully covers the tool's usage and behavior. No missing elements.

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 0% with no parameter descriptions. Description explains movie_id's role but omits the optional language parameter, leaving it partially underspecified.

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 fetches trailers, teasers, clips, and featurettes for a TMDB movie by movie_id. It is distinct from sibling tools like movie_credits or movie_recommendations, which serve different purposes.

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 implies usage for retrieving movie videos but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds value by specifying the data returned, but does not disclose additional behavioral traits beyond those implied by 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, front-loaded with the action, and contains no redundant words. It is concise and structured effectively.

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 presence of an output schema, the description adequately summarizes return values. However, it fails to compensate for the low parameter schema coverage and lacks usage guidance relative to 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 description coverage is 0%, but the description only implicitly mentions person_id and does not explain 'language' or 'append_to_response' parameters. No additional meaning is added 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 explicitly states 'Fetch TMDB person details by person_id' and lists the returned fields (full name, biography, etc.), clearly distinguishing it from sibling tools like 'person_combined_credits' and 'search_person'.

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 no guidance on when to use this tool versus alternatives such as 'person_combined_credits' or 'search_person'. No when-not or context for selection is given.

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

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

Annotations already mark readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds return fields (title, character/job, media type, etc.) and that it fetches both cast and crew, providing useful behavioral context beyond annotations.

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

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

Two sentences: first states purpose, second lists returned fields. No fluff, but could be more structured (e.g., bullet points for fields). Efficient but not maximally organized.

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

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

Has output schema so return values need not be fully described, but description lists key fields. Missing mention of language parameter and any pagination or limits. For a simple fetch tool with annotations, it is fairly 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 description coverage is 0%; description only explains 'person_id' as the identifier. The 'language' parameter is not mentioned, leaving its purpose and valid values unclear. Description adds minimal value for parameter semantics.

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

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

Description clearly states the tool fetches all movie and TV credits for a TMDB person, using a specific verb ('fetch'), resource ('credits'), and identifier ('person_id'). It differentiates from sibling tools like 'person' (basic info) and 'movie_credits' (movie-specific) by specifying combined credits.

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

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

No explicit guidance on when to use vs alternatives. While the purpose is clear, it lacks when-not-to-use or comparison with siblings like 'person' or 'search_person'.

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 (all false), the description discloses rate limits (5 per identifier per day), free usage, no quota deduction, and that feedback is read daily and affects roadmap.

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

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

Single paragraph front-loads purpose, then usage, then constraints. Every sentence adds unique value; no fluff or redundancy.

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

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

For a feedback tool with 3 parameters and no output schema, the description covers what, when, how, and limits. No missing information given the tool's simplicity.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the 'type' enum options, suggesting concise messages, and encouraging structured context, going beyond schema descriptions.

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

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

The description specifies the action ('tell the Pipeworx team something is broken, missing, or needs to exist') and the resource (feedback to Pipeworx). It clearly distinguishes from sibling tools by framing feedback, not data retrieval.

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

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

Explicitly states when to use for bugs, features, data gaps, or praise. Provides exclusions ('don't paste the end-user's prompt') and mentions rate limits and quota impact.

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

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

Annotations already indicate read-only, idempotent, open world, non-destructive. The description adds significant transparency: data source (CF analytics-engine), no PII, cached 5min-1h, and the data shape. No contradiction.

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

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

Two compact sentences with a parenthetical list. Front-loaded with the main action, every sentence adds value. No fluff.

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

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

Given a single optional parameter and no output schema, the description covers the return shape (top tools, top packs, call volume) and caching. Adequate for usage, though output format is not fully specified.

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 one parameter. The description adds practical semantics beyond the schema's enum description, explaining how shorter vs longer windows affect results. Could provide more detail on default behavior.

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 recent window, using specific verbs and resource. It distinguishes from sibling tools by specifying 'Pipeworx' context and focusing on aggregated trending data.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) but does not include explicit when-not-to-use or alternatives. 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 read-only, idempotent behavior, and the description confirms it does not execute trades ('do not trade it') and explains the fill check for realizable edge. This adds context beyond annotations, ensuring the agent understands the tool's analytical nature.

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

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

The description is thorough and well-structured, starting with the main purpose and detailing modes and sub-checks. While slightly verbose, it earns its length given the tool's complexity; minor redundancy exists.

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

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

Despite lacking an output schema, the description explains the response structure (opportunities array, partition_check) and fill check logic, covering inputs, outputs, and edge cases 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 for both parameters. The description adds examples and clarifications (e.g., 'event slug like "fed-decision-may-2026"', full URLs accepted), enhancing the schema definitions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with specific use cases, which differentiates it from sibling tools like polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also refers to polymarket_fill_risk for custom sizing, offering clear 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 declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description adds rich behavioral context: caching (1h), response structure (by_segment, _diagnostics), model family details (crypto_price, news_momentum, partition_overround, concentrated_longshot), and edge computation methodology. It goes far beyond annotations to explain underlying mechanisms and safety (no destructive actions).

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

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

The description is front-loaded with the core purpose in the first sentence, then organizes details into segments (model families, response, knobs). However, it is quite long (over 300 words) and includes some implementation details (e.g., specific numbers like 'Run 8 from prior 85%/5%/50:1') that may not be essential for tool selection. Still, the structure is logical and well-paragraphed.

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 9 parameters (none required), no output schema, and high complexity (multiple model families, segments, diagnostics), the description is remarkably complete. It explains the full response structure (by_segment, fed_candidates, _diagnostics), the content of each opportunity (edge_pp_net, kelly_fraction, etc.), caching behavior, and even tradeable-edge filters. No critical gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of knobs (tradeable-edge filters) in context, e.g., min_liquidity and max_spread_pp, and how they relate to realizing edges. It also explains the min_partition_leg_kelly parameter's special role for partition arbs. This exceeds simple 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 it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically targeting 'what should I bet on today'. It distinguishes from sibling tools by focusing on edge computation from Pipeworx data, and explicitly contrasts with similar tools like polymarket_arbitrage and bet_research through context.

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 extensive usage guidance, including tradeable-edge knobs (min_liquidity, max_spread_pp) and filtering options (min_kelly, min_edge_pp). It explains when to use the tool (discovery) but does not explicitly state when NOT to use it or compare directly with siblings like polymarket_arbitrage. However, the detailed parameter descriptions compensate.

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

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

Annotations indicate read-only, idempotent, non-destructive operations. The description adds substantial behavioral detail: data sources, response structure (tracked, expired, snapshot_dates), trend computation, limitations (60-day TTL, daily closes, not intraday), and decay/trend mechanics. 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 detailed but well-structured: purpose, usage example, parameter overview, response format (with bullet-like enumeration), and limitations. It is not overly verbose for the complexity, though some sentences could be tightened. Earns its length through high information density.

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

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

With no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and details within each. It also covers limits (60-day TTL, data gaps, decay calculation). All essential information for correct use is present, making it contextually 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% (both parameters described). The description adds value by explaining 'window' as 'snapshot family' and providing defaults and bounds for 'days' (default 14, max 30). While schema already covers basics, the description enriches understanding with contextual usage.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge duration and shrinkage, distinguishing it from related tools like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description implicitly guides usage by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives but the context is clear. A more explicit 'when to use versus other tools' would raise this to 5.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description aligns and adds significant behavioral detail: it walks the order book, returns verdicts (clean|degraded|cannot_fill), and explains risks of partial basket fills causing unhedged positions. No contradiction.

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

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

The description is longer than necessary (~200 words), but front-loads the purpose and requirement. It includes detailed return field lists which would be better in an output schema, but since none exists, it is acceptable. Some redundancy in explaining modes and defaults.

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 high complexity (two modes, multiple return fields, edge cases), the description covers all necessary aspects: both modes, parameter defaults, return values, and critical warnings about thin books and partial fills. Without an output schema, this description is complete enough for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The tool description reinforces parameter meaning and adds context (e.g., side defaults, size interpretation for basket mode). It adds value beyond the schema by explaining return fields that depend on parameters.

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

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

The description clearly states the tool's purpose: a realizable-vs-theoretical edge check against CLOB order-book depth. It distinguishes between single-market and basket modes and explicitly differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges, stating when it should be used before those.

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

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

The description explicitly states when to use this tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above $500. It explains the rationale (theoretical overround not capturable, partial fills cause directional risk). It does not explicitly state 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 mark the tool as read-only and idempotent. The description adds significant behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped counters) and conditions when spreads are meaningless. No contradictions with annotations.

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

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

The description is well-structured with clear sections (modes, response, safety fields) and front-loaded purpose. It is slightly verbose due to detailed safety explanations, but every sentence adds necessary context for this complex tool.

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

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

Given the tool's complexity (cross-venue matching, compatibility checks) and lack of output schema, the description thoroughly explains the response fields (leg prices, spreads, compatibility_warning, temporal_alignment, skipped counters). It leaves minimal ambiguity for an AI agent.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the topic enum values and overriding behavior, going beyond the schema's brief descriptions. This helps the agent understand parameter relationships.

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 spread between Kalshi and Polymarket for the same resolving question, specifying verb, resources, and scope. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison.

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

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

The description provides explicit usage guidance, including two modes (topic shortcuts and explicit tickers) and warnings about compatibility and temporal alignment. It warns that pre-mapped topics often return warnings, advising caution. However, it does not explicitly compare to sibling tools for when to use this instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds further value by noting scoping (anonymous IP, BYO key hash, account ID) and the effect of omitting the key argument (lists all keys). No contradictions.

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

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

Two sentences, front-loaded with the primary action, no unnecessary words. All information is pertinent and efficiently presented.

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 single-parameter retrieval tool, the description covers purpose, usage, behavioral traits, and parameter semantics fully. Even without an output schema, the behavior is well explained.

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 adds context about the parameter's role (omit to list all keys) and its relationship to the 'remember' tool, going beyond the schema.

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

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

The description clearly states the tool retrieves values saved via 'remember' or lists all keys, with specific verb-resource pairs (retrieve/list, value/keys). It distinguishes from sibling tools like 'remember' and 'forget' by naming them explicitly.

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

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

The description provides clear context for when to use: to look up previously stored context without re-deriving. It mentions pairing with 'remember' and 'forget', but does not explicitly state when to avoid this tool (e.g., when data is not memory-based).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds useful behavioral details: returns most recent alerts with source, citation_uri, raw payload; explains mark_read:true flags events as read so next call shows only newer ones. 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 moderately sized and front-loaded with the main purpose. Every sentence adds value: purpose, return fields, filter options, mark_read behavior, poll compatibility, and alternative access. 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?

For a tool with 5 parameters, no required, 100% schema coverage, and no output schema, the description is thorough. It explains return fields, filtering, mark_read, poll suitability, and alternative API. The annotations cover safety and idempotency, making the description sufficient for an AI agent.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds context beyond schema: e.g., type filter example 'sec_8k', mark_read behavior detail, limit range 1-200. This adds meaningful value, so score above baseline of 3.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the verb 'Pull' and the resource 'fired events from your subscription feed'. It distinguishes from sibling tools like list_subscriptions by focusing on retrieving alerts, not managing subscriptions.

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

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

The description mentions 'Polls work fine' and provides an alternative access method (GET registry.pipeworx.io/alerts.json), implying when to use this tool vs. scripts/dashboards. It also explains the mark_read parameter's effect on subsequent calls. However, it does not explicitly state when not to use this tool.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds: specific sources and their status (USPTO soft-fail), fallback logic (GDELT→GNews), output structure (grouped changes, citations). 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?

Every sentence adds value, but the description is dense and could benefit from better structuring (e.g., bullet points). It is front-loaded with natural language examples.

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

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

Given the complexity (3 parameters, no output schema), the description is thorough: covers sources, fallback, output structure, and usage. No missing critical information for an agent to use the tool correctly.

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

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

All parameters are described in schema (100% coverage). Description enriches: example values for `since`, recommendation for typical monitoring, and explanation that `value` accepts ticker or CIK. Only 'company' supported for type.

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

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

The description clearly explains the tool returns a change feed for a company from multiple sources, with natural language examples. It distinguishes from sibling 'entity_profile' by specifying that this is for dynamic changes.

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 use cases and example queries. Directly contrasts with entity_profile for static profiles, and explains fallback behavior for news sources. Advises on `since` parameter values.

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 scoping by identifier, persistence differences for authenticated vs anonymous sessions (24 hours), and idempotent nature. Annotations confirm non-destructive and idempotent; no contradiction.

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

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

Four sentences, each earning its place: core purpose, when to use, scoping/persistence, and related tools. Front-loaded with action verb 'Save'.

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?

Fully explains behavior for a simple key-value store: scoping, persistence, pairing with recall/forget. No output schema needed as return value is implicit. Given parameters and annotations, description is 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 provides full descriptions for 'key' and 'value' (100% coverage). Description adds value with concrete examples and context for key naming conventions, but does not add entirely new semantic information 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?

Description clearly states the tool saves data for reuse across conversations/sessions, gives specific examples (resolved ticker, target address, user preference, research subject), and distinguishes 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 tells when to use ('when you discover something worth carrying forward'), why ('so you don't have to look it up again'), and how to pair with 'recall' and 'forget'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: it reveals that each call cascades through multiple lookup endpoints, replaces 2-3 manual lookups, and details the exact return structure for each entity type (ticker, CIK, URI for companies; RxCUI, ingredient, brand for drugs). 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: beginning with example queries, then a usage directive, followed by detailed type breakdowns. Every sentence adds value, though it is slightly lengthy. It front-loads the purpose and usage, making it easy for an agent to parse quickly.

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

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

Given the tool's moderate complexity (two entity types, multiple input formats, rich returns) and no output schema, the description is remarkably complete. It covers all parameter semantics, return values, and behavioral nuances (cascading lookups). The 100% schema coverage and detailed description leave no significant gaps.

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

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

Schema coverage is 100% with both parameters described. The description enriches the schema by explaining that for company, the value can be a ticker, CIK, or company name with auto-disambiguation, and for drug, it accepts brand or generic name. It also clarifies what each type returns, adding meaning beyond the enum and string 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 explicitly states that the tool resolves user-spoken names to canonical identifiers, with concrete examples like 'What's the ticker for…'. It distinguishes itself from sibling tools by specifying it is used when an ID is needed from a name, and details supported types (company and drug) and their returns.

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 advises 'Use FIRST whenever you have a name but need an ID', providing clear usage context. While it does not explicitly list alternative tools, the sibling set includes entity_profile and compare_entities, implying the scope. The instruction is clear enough for an AI to 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?

The description discloses internal behavior: probes each entity with 'ai_visibility_check', ranks by score, and treats the first entity as the subject. This adds context beyond annotations (readOnlyHint, etc.), which are already non-destructive and idempotent.

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

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

Three sentences, front-loaded with core purpose, followed by mechanism and use case. No redundant words; every sentence contributes uniquely.

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 return fields: 'ranked list with score, confidence, signal density per entity'. Combined with internal mechanism, this fully informs the agent of expected output. No missing elements.

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, the description still adds significant meaning: 'entities' specifies 2-8 range and first-as-subject; 'models' distinguishes free vs. paid; '_apiKey' conditional on model; 'context' adds disambiguation purpose. These details are absent from 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 starts with 'Compare AI visibility across multiple entities side-by-side,' clearly stating the verb and resource. It contrasts with sibling 'ai_visibility_check' by explaining it batch-probes multiple entities and ranks them, making the tool's purpose unique and unambiguous.

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

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

The description provides a concrete use case: 'competitive AI-marketing audits' with an example query. It implicitly excludes single-entity checks by referencing 'ai_visibility_check' for individual probes, but lacks an explicit 'when not to use' statement.

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 important behavioral traits beyond annotations: bundlephobia's first measurement can take 5-30 seconds, partial failures degrade gracefully with sources_failed reporting. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds timing and error-handling 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 front-loaded with the core purpose in the first sentence. While relatively long, every sentence adds value (ecosystem scope, return fields, timing caveat). Minor redundancy could be trimmed, but overall structure is effective.

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

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

Despite lacking an output schema, the description thoroughly explains return values: summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and recent versions. Covers edge cases like partial failures and timeout handling, making it complete 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?

Schema coverage is 100% with both parameters described. The description adds extra meaning: notes that scoped packages (e.g., '@types/node') are accepted for 'package', and explains that 'version' defaults to the latest published version when omitted, enhancing understanding beyond the schema.

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

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

The description clearly states it performs a composite check for npm packages across deps.dev and bundlephobia, answering safety, popularity, and size questions. It uniquely identifies itself among siblings, which include unrelated tools like movies and AI visibility checks.

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 provides usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies NPM-only scope in v1 and directs to deps.dev:version for other ecosystems, effectively guiding when to use alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about required downstream use and the set of returned fields. No contradictions, but could mention pagination or rate limits.

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

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

Two sentences that front-load the purpose and key details. Every word earns its place; no redundancy.

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

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

Given the tool's complexity (7 parameters) and presence of an output schema, the description covers the primary purpose and key output fields. It could mention pagination or optional parameters but is adequate overall.

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, the description adds meaning for the required parameter 'query' and optional 'year' and 'primary_release_year', but does not explain 'page', 'region', 'language', or 'include_adult'. It provides partial compensation.

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 searches TMDB for movies by title keyword, with optional filters. It lists returned fields and highlights that the movie_id is required by sibling tools `movie` and `movie_credits`, distinguishing it from other search tools like search_tv or search_multi.

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 this tool should be used when searching for movies by title, and mentions how the result is used by downstream tools. However, it does not explicitly state when not to use it or given alternatives among the many sibling tools.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds value by explaining that results are tagged with media_type, which is not in annotations. No contradictions.

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

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

Two concise sentences with no unnecessary words. The description is efficient and front-loaded with the key purpose.

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

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

The tool has an output schema, so return values are covered elsewhere. However, there are four parameters, and only one is described. For a multi-search tool, more details on result sorting, limits, or pagination would be helpful but not strictly required given the output schema.

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%, meaning the schema provides no parameter descriptions. The description only hints at the 'query' parameter as a 'single keyword query' but does not explain 'page', 'language', or 'include_adult'. The description adds minimal semantics beyond the schema types.

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

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

The description clearly states the verb 'search' and the resource 'TMDB across movies, TV shows, and people simultaneously,' distinguishing it from single-type siblings like search_movie, search_person, and search_tv. It specifies returning mixed results tagged with media_type.

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 indicates it is 'useful when the content type is unknown,' providing implicit guidance on when to use this tool. However, it does not explicitly mention when not to use it or list alternatives like the sibling search tools.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds the specific output fields and linkage to other tools, but does not provide additional behavioral context such as rate limits or what happens with no results.

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 at two sentences, front-loading the purpose and then listing output fields. It is efficient but could be slightly improved by adding parameter tips without becoming verbose.

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

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

The description covers the core purpose and output, and the existence of an output schema reduces the need to explain return format. However, it lacks details on pagination and language filtering, which are relevant for search tools. Annotations compensate for safety, so overall adequate but not complete.

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

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

The input schema has 4 parameters with 0% description coverage, so the description must compensate. It only implicitly describes the query parameter as 'by name' and omits any explanation for page, language, and include_adult. This is insufficient for effective use.

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 TMDB for actors, directors, or crew members by name. It lists the output fields and explicitly mentions the returned person_id is needed by person and person_combined_credits tools, differentiating it from sibling search tools for movies, TV, and multi.

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 this tool should be used when you need to find a person by name and get their ID for subsequent person detail or combined credits calls. However, it does not explicitly state when not to use it or compare it to alternatives like search_multi.

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 a safe, idempotent read operation (readOnlyHint=true, destructiveHint=false). The description adds value by detailing the return fields (show name, first-air date, popularity, overview, poster path, tv_id) and connecting it to TMDb, exceeding what annotations alone provide.

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

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

The description is two sentences, each serving a distinct purpose: first explains the tool and its outputs, second gives usage guidance. No fluff, well-structured, and front-loaded with essential information.

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

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

The description adequately covers the tool's high-level purpose and return values, aided by an existing output schema. However, the lack of parameter documentation beyond 'query' leaves the agent underinformed about optional inputs, making it less complete for a 6-parameter 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?

With 0% schema description coverage, the description heavily relies on itself to explain parameters. It only mentions 'by title', mapping to the required 'query' parameter, but fails to describe 'page', 'year', 'language', 'include_adult', or 'first_air_date_year'. This leaves significant ambiguity for the agent.

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 searches TV shows by title, lists return fields, and explains its purpose as resolving a TV title into tv_id for use with tv, tv_season, and tv_episode tools. It effectively distinguishes from sibling tools like search_movie or search_person.

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

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

The description explicitly states when to use this tool: to resolve a TV title into tv_id needed by specific sibling tools. It does not provide explicit when-not or alternative guidance, but the context is clear enough for an agent to decide.

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

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

Discloses technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation and flagging. Annotations only indicate read-only and idempotent, so description adds significant behavioral context.

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

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

Single paragraph is dense but well-structured: purpose first, then usage, then technical details. Every sentence adds value. Front-loaded with key information.

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

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

Given no output schema, description explains returns: top-N passages with offsets and scores. Also covers limitations (200K cap), pairing with another tool, and underlying algorithm. Complete for intended use case.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description adds minimal extra meaning: examples for query and states default for limit. Baseline 3 is appropriate as description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying the inputs and outputs. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and explicitly stating its use case when the record is too large for the prompt.

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

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

Provides explicit guidance on when to use: when the record is too big to cram into the prompt. Also explains how it pairs with ask_pipeworx_grounded for a complete workflow. No need to list exclusions as the purpose is narrow.

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 rich behavioral traits beyond the annotations: it returns a new subscription id, specifies authentication requirements, lists subscription types with examples, details delivery channels with constraints (SMS cap, webhook auto-disable), and notes that the signing secret is returned once. It does not contradict 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 and front-loaded with the core purpose. However, it is somewhat lengthy, including detailed technical explanations (e.g., webhook signing) that could be succinct. Still, every sentence adds necessary context, and the structure supports readability.

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 absence of an output schema, the description adequately explains that it returns a subscription id. It covers key aspects like required auth, type constraints, and delivery details. However, it does not explicitly mention the structure of the created subscription or error handling, leaving minor gaps for a complex tool.

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

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

With 100% schema coverage, the baseline is 3. The description adds significant value by providing concrete examples for the 'params' parameter (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}') and detailing the 'delivery' parameter's behavior (webhook HMAC signing, SMS verification). This clarifies usage beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb 'create' and identifies the resource 'subscription', distinguishing it from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides clear context on when to use the tool, including the requirement for a Pipeworx OAuth account and the inability for anonymous users. It implicitly differentiates from siblings like 'recent_alerts' for pulling events, but does not explicitly state alternatives or when not to use it.

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

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

Annotations already indicate readOnly, openWorld, and idempotent. The description adds beyond: explains the output structure (category-bucketed examples), that it draws from a live catalog of tools, and that it teaches how to call meta-tools. Good added context.

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

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

Front-loaded with common user queries, then states purpose and details. Every sentence adds value. Slightly lengthy but well-organized, earning a 4.

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

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

Given no output schema, the description explains the return type sufficiently. It covers use case, parameters, and expected output. Minor lack of exact JSON structure but adequate for agent understanding.

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

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

Schema covers the topic parameter with a description listing values. The description adds meaning by explaining the effect: omission gives full spread, passing a topic focuses the response. This enriches the agent's understanding beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx and discover_tools by being for initial exploration when the agent doesn't know Pipeworx's capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with or without a topic. Lacks explicit when-not-to-use, but the strong recommendation to use first provides clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds data source (TMDb) and return fields (ranked list with name, popularity, etc.), providing useful behavioral context beyond annotations.

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

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

Two sentences, no filler. The first sentence states purpose and scope, the second gives concrete use cases. Every word earns its place.

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

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

Covers core functionality and return data, but fails to mention the pagination parameter (page) or language filtering. With an output schema present, the lack of return structure details is acceptable, but missing optional parameter context makes it incomplete.

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 50% with only media_type and time_window described. The description reiterates these but adds no detail about page or language parameters. Usage examples show valid values but do not compensate for the missing documentation on optional 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 returns trending movies, TV shows, or people for a time window, and lists returned fields. However, it does not explicitly differentiate from the sibling tool 'pipeworx_trending', which might require additional context.

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 usage scenarios like 'what is popular this week' and 'trending celebrities', giving clear context. Does not include when-not-to-use or alternatives, but the provided use cases are sufficient for most agents.

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, so the safety profile is clear. The description adds that it returns specific fields, but does not discuss rate limits, authentication requirements, or how changes to API might affect behavior. With annotations covering the core traits, the description adds modest 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?

The description is a single, well-structured sentence that front-loads the primary action and uniquely identifies the resource. It lists key return fields efficiently without extraneous information.

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

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

The description is adequate given the presence of an output schema and strong annotations. However, it omits details about optional parameters and does not provide usage notes (e.g., that tv_id is a numeric TMDB ID). The tool has three parameters but only one is explained in text. This leaves gaps in completeness.

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

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

Schema description coverage is 0%, meaning the description provides no explanation for the two optional parameters (language, append_to_response). While the description mentions tv_id in the text, it does not clarify the purpose or acceptable values of the other parameters. With no enums and no param descriptions, the agent lacks guidance on how to use these parameters effectively.

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

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

The description clearly states it fetches full TMDB TV show details by tv_id and lists specific return fields like name, overview, air dates, seasons, episodes, genres, networks, status, vote average. This distinguishes it from sibling tools like search_tv, discover_tv, tv_episode, and tv_season.

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

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

No explicit guidance on when to use this tool versus alternatives like search_tv or discover_tv. The description only states what it does, without providing context for selection criteria or exclusions.

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, and idempotentHint=true, so the description's main addition is listing return fields. It does not add extra behavioral context such as authentication needs or rate limits, 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 two sentences: the first specifies the action and required inputs, the second lists the outputs. No redundant information, perfectly front-loaded and 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?

The description covers the core functionality and return fields for a read-only episode fetch. The missing 'language' parameter is a minor gap, but overall the description, combined with good annotations and an output schema, provides sufficient context for this simple 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?

The description explicitly mentions the three required parameters (tv_id, season_number, episode_number) and their roles, but omits the optional 'language' parameter. Given 0% schema coverage, this partial compensation is adequate but not complete.

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 fetches details for a specific TV episode using tv_id, season_number, and episode_number, and lists the returned fields (name, overview, air date, etc.). This distinguishes it from sibling tools like 'tv' and 'tv_season', which operate at series and season levels.

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 episode-level details but does not explicitly state when to use this tool over alternatives like 'tv_season' or 'tv'. No exclusions or prerequisites are mentioned.

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

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

Annotations declare `readOnlyHint` and `idempotentHint`, which the description aligns with by describing a fetch operation. The description adds value by specifying the exact return fields (e.g., 'season name, overview, air date, episode count'), going beyond the annotation's safety profile.

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

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

The description is two sentences, front-loaded with the action ('Fetch details...'), and contains no superfluous information. Every sentence adds value, making it 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?

The tool has an output schema, so return values are already defined. The description adds context about what the tool does and the key parameters, but fails to mention the optional `language` parameter. Overall, it covers the essential functionality 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 0%, so no property descriptions. The description explains `tv_id` and `season_number` but omits `language`. This partially compensates for the coverage gap, but leaves the `language` parameter undocumented in both schema and description.

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

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

The description clearly states the tool fetches details for a specific TV season by `tv_id` and `season_number`, and lists the returned fields (season name, overview, air date, episode count, episode list). This distinguishes it from siblings like `tv` (series-level) and `tv_episode` (episode-level), providing unambiguous 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 implicitly conveys usage through the parameters (`tv_id`, `season_number`), but does not explicitly state when to use this tool vs siblings or mention any prerequisites. No 'when to use' or 'when not to use' guidance is 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?

Adds value beyond annotations: ownership enforcement, soft-delete behavior, and historical event preservation. Annotations indicate non-destructive, idempotent, and non-read-only, which is consistent.

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

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

Three concise sentences, each providing essential information: action, constraint, and side effects. 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?

Covers all necessary aspects for a simple one-parameter tool: what it does, who can use it, what happens to the data, and where to find historical events.

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

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

Schema covers 100% of parameter description; description adds context that 'id' comes from 'subscribe', linking tools.

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.' Distinguishes from sibling tools 'subscribe' and 'list_subscriptions' by specifying the action and ownership constraints.

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 ownership enforcement ('only cancel your own subscriptions') and explains deactivation vs deletion, linking to 'recent_alerts' for historical data. Does not explicitly list when not to use, but provides sufficient context.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral context: returns verdict type, structured form, actual value with citation and percent delta, and replaces multiple calls. 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?

Description is informative but slightly lengthy; front-loaded with example queries. Every sentence adds value, though 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?

Fully explains what claims are supported, sources (SEC EDGAR+XBRL), return structure (verdict, structured form, actual value with citation, percent delta). No output schema exists, so description adequately covers completeness.

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

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

Only one parameter 'claim' with schema coverage 100%. Description adds value by providing example inputs and clarifying supported claim types (company-financial), beyond the schema 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?

Description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims via SEC EDGAR+XBRL) and distinguishes from siblings by noting it replaces multiple 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Provides context for when to use, but no explicit when-not or exclusion criteria, though domain limitation is implied.

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