Trakt

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

Beyond annotations (readOnly, idempotent, nondestructive), description reveals return structure (per-model score, confidence, signals, raw_response + combined), API key pass-through, and that Anthropic calls are paid directly by user. 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?

Four efficient sentences with no redundancy. Front-loaded with action, immediately useful for an agent. Every sentence adds value.

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

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

Given 4 parameters, full schema coverage, clear return structure (though no output schema), and no contradiction, the description fully equips an agent to invoke this tool correctly. Sufficient for the complexity.

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

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

While schema coverage is 100%, the description adds significant context: explains default model for 'models' parameter, purpose of '_apiKey' (BYO key for Anthropic), and helps disambiguate 'context' parameter. Adds meaning beyond the raw 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?

Specific verb+resource: 'Probe one or more LLMs' and 'score visibility (0-100)'. The description clearly distinguishes from siblings like 'ask_pipeworx' or 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring.

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 default model, optional Anthropic probe with user-provided API key, and use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Lacks explicit when-not-to-use but context is clear enough.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context about routing to 3,436 tools and returning structured answers with citation URIs, which is useful 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 comprehensive but slightly verbose; however, it is front-loaded with the key directive and logically organized with 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?

For a query tool with no output schema, the description covers inputs well and mentions output format (structured answer with URIs). It lacks details on error handling or empty results, but is adequate.

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

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

Schema coverage is 100% with descriptions for each alias. The description adds value by explaining the main parameter 'question' in natural language and providing examples of good questions, complementing 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 routes factual questions to appropriate sources and returns structured answers with citations. It distinguishes itself from web search by specifying domains like SEC filings, FDA data, and stocks, and provides a concrete verb-resource combination.

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

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

Explicitly instructs to prefer this tool over web search for structured data queries, lists trigger phrases like 'what is' and 'look up', and gives concrete examples such as 'current US unemployment rate' and 'Apple's latest 10-K'.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds extensive behavioral details: fan-out to category-specific data packs, resolver contract with match confidence, parent event extraction, news fallback mechanisms, safety for low-confidence matches, and handling of closed markets. 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 very long (multiple paragraphs) and includes many details and examples. While it is structured and informative, it could be more concise. The main purpose is front-loaded, but the volume of detail may overwhelm quick comprehension.

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

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

Given the complexity (multiple data sources, classifiers, resolver, parent event extraction) and lack of output schema, the description thoroughly covers all aspects: response shapes, resolver contract, parent event details, news fields, safety mechanisms, and edge cases. It is complete for effective use.

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

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

Schema description coverage is 100% (all three parameters described). The description reiterates the market input can be slug, URL, or question text, which is already in the schema. It adds minimal new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and provides example use cases. It distinguishes from sibling tools by focusing on comprehensive research (fans out to data packs) vs arbitrage/edges/spread tools.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It also implies when not to use (e.g., for closed markets) but does not directly compare with sibling tools like polymarket_edges. The context is clear and helpful.

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

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

Annotations already indicate safe, read-only, non-destructive operation. Description adds details like single parallel call, sorted results, citation URIs, and handling of off-calendar fiscal years, enriching 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 dense but every sentence adds value. Front-loaded with query patterns and key usage instruction. Efficiently conveys all necessary 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 two entity types, no output schema, and complex data sources, the description fully explains inputs, data pulled, sorting, and output format. No gaps for correct tool usage.

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

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

Schema coverage is 100%. Description adds meaning by explaining how to fill values for company (tickers/CIKs) vs drug (names) with examples, and clarifies type enum.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, listing query patterns and differentiating from sequential lookups. It distinguishes from sibling tools like entity_profile.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and explains when to use by entity type. Provides clear context for usage.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns top-N tools with full schemas and examples, ready to call directly, which goes beyond annotations.

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

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

The description is a single paragraph but efficiently covers purpose, examples, and usage guidance. It is front-loaded with the core purpose, making it easy to scan.

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 (6 parameters, no output schema), the description adequately explains what it returns and when to call it. However, it could briefly mention that the results are purely informational and not the final answer.

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 briefly mentions the query parameter accepts natural language, but the schema already provides detailed descriptions and examples. The description adds minimal extra value for 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 explicitly states the tool's purpose: 'Find tools by describing the data or task.' It also lists specific domains and explains the output format, distinguishing it from siblings like 'search' or 'trending'.

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

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

The description advises: 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear, actionable guidance, though it lacks explicit when-not-to-use instructions.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds key behavioral details: fans out across multiple sources, soft-fails on patents, uses GDELT→GNews fallback, returns specific fields with URIs, and is a single parallel call. 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?

Every sentence is informative and earns its place. Description is front-loaded with example queries, then details behavior and return fields. 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?

Despite no output schema, description fully explains return values (cik, company_name, filings with URIs, fundamentals, patents, news, LEI), input constraints, fallback behavior, and parallelism. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description largely repeats schema info (e.g., type only company, value as ticker/CIK) but adds context about name unsupported. Minimal additional value 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 starts with concrete examples ('Tell me about X', 'research Acme') and explicitly states it returns a 'full cross-source profile of a US public company in ONE parallel call'. It clearly distinguishes from alternatives like chaining single-pack lookups and refers to sibling tools `resolve_entity` for names.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and clarifies when not to use ('names not supported — use resolve_entity first'). Also specifies input forms (ticker or CIK).

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about 'sensitive data' but does not go beyond what annotations convey. 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: first defines purpose, second provides usage guidance. No wasted words, 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?

For a simple tool with one parameter, full annotation coverage, and no output schema, the description is complete and sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. The description adds no further semantic detail beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb (delete), resource (memory), and method (by key). It distinguishes itself from sibling tools '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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember and recall', providing clear context for usage vs alternatives.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safety. The description adds that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt format. It does not disclose error handling or rate limits, but given annotations, this is adequate.

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

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

The description is three sentences, front-loaded with the core purpose, and includes all necessary information without wasted words. Each sentence adds value.

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

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

With no output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt') and mentions extracted fields. It covers the tool's behavior adequately, though missing details on error scenarios is a minor gap.

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

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

Schema description coverage is 100%, and the description repeats the parameter descriptions verbatim. No new meaning is added beyond what the input schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying the action (generate, fetch, extract, emit) and the resource. It distinguishes itself from siblings by focusing on a unique output format and use cases for AI crawlers.

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 use cases (e.g., 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It does not explicitly state when not to use it or mention alternatives, 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 declare read-only, idempotent, and non-destructive. Description adds return field details but no additional behavioral context beyond schema.

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

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

Concise with usage patterns and return fields front-loaded. One efficient sentence with examples, though slightly unstructured.

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?

Output schema exists, so return values need no explanation. Covers purpose, parameters, and usage adequately for a simple lookup tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds no new meaning to parameters beyond the schema; the 'extended' parameter is not elaborated.

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 specifies it retrieves a single episode by show+season+episode, listing return fields. Distinguishes from sibling tools like get_movie and get_show.

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?

Implied usage for episode lookups, but does not explicitly state when not to use or mention alternatives. The examples guide usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by listing what extended='full' includes (plot, runtime, genres, cast, rating, year, certification), enhancing transparency without contradicting 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 concise (one sentence with examples) and well-structured, front-loading the core action and then providing usage patterns. No wasted words.

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

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

Given the simple nature of the tool, low complexity, and presence of an output schema, the description adequately covers what the tool does without needing to explain return values. It is complete for the task.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds meaningful usage examples and explicitly lists the fields returned with extended='full', providing context 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 gets movie info by ID (Trakt, slug, IMDb) and distinguishes from sibling tools like get_episode and get_show. The examples of natural language queries add clarity.

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

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

The description provides usage examples and explains when to use extended='full' for additional details. It does not explicitly mention 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 indicate read-only, idempotent, and non-destructive behavior. The description adds behavioral context by explaining that extended='full' returns runtime, genres, cast, rating, and other details, which goes 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 concise, using slash-separated example queries to convey purpose efficiently, followed by a clear statement of what the tool returns. It front-loads common usage patterns without 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?

For a simple two-parameter lookup tool, the description covers identification methods and the extended parameter's effect. The presence of an output schema compensates for any missing details on return structure. Minor gaps like default extended behavior are not critical.

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 covers both parameters with descriptions (id: trakt ID/slug/IMDB/TMDB ID, extended: full/metadata/images). The description adds specific fields for the 'full' option, but this is marginal additional value given 100% schema coverage.

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

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

The description clearly states the tool returns a full TV show record and provides example queries like 'TV show info for [title]' and 'details on [series]'. It distinguishes itself from siblings like get_episode and get_movie by explicitly specifying TV shows and using identifiers like Trakt ID, slug, or IMDb ID.

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 the tool is for TV show queries through examples, but it does not explicitly instruct when to use this tool over siblings like get_episode or get_movie. No when-not or alternative 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds behavioral detail about the extended parameter to include episodes, which is beyond the 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 sentences with no wasted words. Front-loaded with example queries. Information is 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?

Given the presence of an output schema, the description does not need to explain return values. It fully covers the tool's purpose, usage, and optional parameter extension. Complete for a simple list tool.

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

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

Schema coverage is 100%, so the description adds little beyond the schema. It does provide example usage and clarifies that show_id is a trakt ID or slug (already in schema). The added value is minimal.

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 lists all seasons of a show with episode counts, using specific verb+resource. Example queries in quotes reinforce its purpose. It distinguishes from sibling tools like get_episode and get_show by focusing on seasons.

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

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

The description gives explicit usage examples and explains how to include episodes via extended parameter. It does not explicitly mention when not to use this tool or contrast with alternatives, but the context of sibling tools makes its use case 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 are all false, providing no safety profile hints. The description compensates by disclosing rate limits (5 per identifier per day), that it's free, and doesn't count against tool-call quota. It also mentions how the feedback is used (digests affect roadmap). 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 four sentences, each earning its place. It front-loads the purpose, then provides usage guidance, and ends with behavioral notes. No unnecessary words 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?

Given there is no output schema, the description adequately covers all needed aspects: purpose, when to use, how to format feedback, and behavioral constraints. The tool is straightforward, and the 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 coverage is 100%, so baseline is 3. The description adds meaning by explaining the 'type' enum values and providing guidance on what to write in 'message'. It also clarifies the optional 'context' object's purpose, adding value beyond the schema.

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

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

The description clearly states the verb ('tell') and resource ('Pipeworx team'), and specifies the types of feedback (broken, missing, needs to exist). It distinguishes itself from sibling tools by being a feedback mechanism, while others like 'discover_tools' or 'search' 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?

The description explicitly lists when to use: for bugs, features/data_gaps, or praise, and advises describing issues in terms of tools/packs. It does not provide explicit when-not situations, but the context is clear enough for an AI agent to decide.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: self-aggregating signal from CF analytics-engine, no PII, just (pack, tool, count) data, and caching window (5min-1h). No contradictions.

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

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

Description is moderately concise (three sentences plus bullet use cases). Every sentence adds value: first defines output, second lists use cases, third explains data provenance. Could be slightly shorter but well-structured for 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 no output schema, description adequately covers what is returned (top tools, top packs, total call volume) and the single parameter. It explains the caching and data source. It is complete for a read-only trending tool with one optional parameter.

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

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

Schema provides enum description for 'window' parameter. Description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches understanding beyond schema's description. Schema coverage is 100%, so baseline 3, but extra semantic value raises it to 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?

Description clearly states it returns top tools, top packs, and total call volume over a recent window (24h, 7d, 30d). It identifies the resource (trending calls on Pipeworx) and specific verb (returns). This distinguishes it from sibling tools like 'trending' or 'popular' which may have different scopes.

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 provides three explicit use cases: discovering hot data sources, confirming canonical choice, and seeing alignment with common use. It implies when to use this tool (for trending signals) but does not explicitly state when not to use or mention alternatives. Still offers clear contextual guidance.

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

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

Annotations already declare safe, idempotent, read-only behavior. The description adds substantial behavioral context: monotonicity checks, partition-sum verification, Jaccard similarity threshold (>=0.30), placeholder filtering, and response structure. 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 quite long and dense, containing many technical details. It is front-loaded with the requirement, but could be more concise by trimming redundant explanations. However, it is well-structured and informative.

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 (two modes, no output schema), the description covers purpose, parameter usage, filtering criteria, and response fields. It provides examples and explains edge cases (e.g., placeholder slugs, low similarity). It feels complete for an arbitrage detection tool.

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

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

Schema coverage is 100% so baseline is 3. Description adds meaning beyond schema by explaining mode semantics, giving examples of event slugs and topic seed questions, detailing the semantic anchor and partition filter, and describing how parameters map to 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's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the two modes (event and topic) and distinguishes from sibling tools like polymarket_edges by focusing on monotonicity and partition sums.

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 requires one of 'event' or 'topic', warns that no args fails. Provides guidance on when to use each mode (single-event vs cross-event) and notes cross-event catches patterns missed by single-event. Lacks direct comparison to sibling tools but usage 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 indicate readOnly, openWorld, idempotent, non-destructive traits. The description adds substantial behavioral context: caching (1h at KV level), diagnostic output for empty segments, detailed edge calculation logic, and filter knobs. No contradiction with annotations.

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

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

The description is long but well-structured with bold headings and segmentation. Every sentence adds value, though some technical details (e.g., per-sport alpha values) could be simplified. It earns its length by being thorough.

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

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

Despite no output schema, the description fully explains the response structure (by_segment, diagnostics, Fed notes) and how filters affect output. It covers why segments might be empty and details on edge calculation. Comprehensive 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?

Schema coverage is 100% with descriptions for all 9 parameters. The description further clarifies each parameter's practical effect, e.g., min_kelly 'skips opportunities that are too small', max_spread_pp 'to require tight books'. This adds value beyond the schema.

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

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

The description clearly states the tool 'scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price'. It is built for a specific use case ('what should I bet on today') and differentiates from siblings by focusing on Pipeworx data disagreement.

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

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

The description explains the intended use case ('what should I bet on today') and provides context about Fed bets being unreliable without paid data. However, it does not explicitly mention when not to use this tool or compare it to alternatives like polymarket_arbitrage.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description details complex behavioral traits: two modes, response structure with leg-by-leg prices and spread, safety fields (compatibility_warning, temporal_alignment), and conditions for non-meaningful spreads. This fully qualifies the tool's behavior.

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

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

The description is well-structured with a clear lead sentence, modes enumerated, and safety fields explained. It is somewhat verbose but front-loaded with key information. Every sentence adds value, but 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?

In the absence of an output schema, the description thoroughly explains the response fields including probabilities, spreads, and safety warnings. It covers edge cases like non-equivalent bet shapes and temporal misalignment. Minor omission: no explicit JSON structure, but sufficient for 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?

The description adds significant meaning beyond the schema: it explains the topic list of 10 macros, shows examples, and clarifies that explicit tickers override topic mappings. The schema is fully covered, but the description enriches understanding of parameter interaction.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by being cross-venue.

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

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

The description explains when to use each mode (topic for quick macros, explicit for custom pairs) and warns that pre-mapped topics often return compatibility warnings, advising that real spreads are rarer. It lacks explicit comparison to alternative tools but provides sufficient context for proper use.

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. Description adds context about lifetime vs current trending, which is useful but not essential. 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 compact sentences. Front-loaded with alternative natural language queries, immediately followed by clarifying definition. No redundant information.

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

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

Given simple parameters, comprehensive annotations, and an output schema, the description fully covers the tool's behavior. No missing information 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?

All 3 parameters have schema descriptions (100% coverage), so the description adds no additional semantics beyond clarifying the date range. Baseline score deemed appropriate.

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

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

Description clearly states the tool retrieves all-time popular movies/shows by lifetime watch counts, distinguishes from trending, and provides alternative phrasings. Matches tool name 'popular'.

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 for best of all time lists' and contrasts with 'not current trending'. Implicitly guides against using for trending content, though does not name sibling tools directly.

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, and the description adds value by explaining scoping (anonymous IP, key hash, account ID) and pairing with remember/forget. No contradictions.

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

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

Three sentences, front-loaded with the core action, and no wasted words. Structure is ideal.

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 explains the behavior, scoping, and pairing with siblings. Missing explicit mention of return values (e.g., 'returns the saved value or a list of keys'), but given the simplicity and annotations, it is still quite 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% and the schema property description already says 'omit to list all keys'. The tool description repeats this and adds broader context (e.g., use cases), but does not add new semantic details beyond the schema for the parameter itself.

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 'retrieve' or 'list' and the resource 'saved memory', explicitly differentiating from sibling tools 'remember' and 'forget' by mentioning them. It also gives concrete examples like 'user's target ticker', making the purpose highly specific.

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

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

The description says to use it for looking up context the agent stored earlier, with concrete examples (ticker, address, notes). It also notes scoping to an identifier. However, it does not explicitly say when not to use or provide alternatives beyond the sibling pairing, which prevents a 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?

The description discloses key behaviors beyond annotations: it fans out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), explains fallback logic, and notes USPTO soft-fails until reactivated. This adds significant value beyond the readOnlyHint and openWorldHint 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 usage examples. It is slightly verbose but each sentence adds value, covering purpose, sources, parameters, and alternatives. Minor redundancy could be trimmed but overall 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?

Given no output schema, the description adequately explains the return structure: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It also clarifies what the tool does not do (static profile), providing complete context for agent decision-making.

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

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

While the input schema already covers all parameters, the description adds valuable context: 'since' accepts ISO or relative shorthand with examples, suggests '30d' for monitoring, and explains that 'value' can be ticker or CIK. This enhances understanding beyond the schema.

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

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

The description clearly defines the tool as a change feed for a company over a time window, using multiple example queries like 'What's new with X' and 'updates on Acme'. It explicitly distinguishes from the sibling tool 'entity_profile' by stating when to use that instead.

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 this tool (change feed queries) and when to use the alternative 'entity_profile' for static profiles. It does not explicitly list negative cases 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?

The description adds value beyond annotations by explaining persistence behavior ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping. Annotations already indicate idempotentHint=true, which aligns with storing a key-value pair.

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

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

Three sentences with front-loaded purpose. Every sentence adds value: purpose and examples, when to use, persistence details, and pairing with siblings. No waste.

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

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

Given the tool's simplicity (2 required params, full schema coverage, annotations present), the description thoroughly covers purpose, usage, persistence, and integration with siblings. 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% with descriptive parameter names and examples. The description adds context about key-value storage, scoping, and persistence, going beyond what the schema provides.

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

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

The description uses a specific verb ('Save data') and resource ('data the agent will need to reuse later') with clear scope ('across this conversation or across sessions'). It provides concrete examples 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?

The description clearly states when to use ('when you discover something worth carrying forward') and explicitly pairs with siblings ('Pair with recall to retrieve later, forget to delete'). However, it does not explicitly state when not to use or provide alternative tools beyond the mentioned ones.

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 behavioral context by noting that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. 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 well-structured with examples first, then purpose, then details. It is slightly verbose but every sentence adds value. 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?

With no output schema, the description fully explains the return values and includes auto-disambiguation details. It covers the complexity of the tool 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%, but the description adds significant meaning beyond the schema: it explains the return values (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug) and provides examples. This greatly aids parameter understanding.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides specific examples like ticker, CIK, RxCUI, and distinguishes itself from siblings by being the first tool to use when you have a name but need an ID.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving clear context for usage. However, it does not explicitly state when NOT to use it or compare to alternatives like search or entity_profile.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds value by detailing the internal probe mechanism (ai_visibility_check), ranking, and output fields (score, confidence, signal density). No contradictions.

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

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

The description is concise (3 sentences) and front-loaded with the core purpose and mechanism. Every sentence adds value: what it does, how it works, example use case, and output summary.

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 partially describes the return format (ranked list with score, confidence, signal density). It covers the required parameters and usage context. Lacks explicit field names but sufficient for an agent to understand what to expect.

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

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

Schema description coverage is 100%, providing baseline clarity. The tool description adds semantic value by explaining that the first entity is treated as the 'subject' for narrative and that models default to 'workers-ai'. This extra context aids correct invocation.

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 'Compare AI visibility across multiple entities side-by-side' and explains the process of probing with ai_visibility_check and ranking. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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 a clear use case ('competitive AI-marketing audits') with an example question. It implies the tool is for multi-entity comparisons but does not explicitly state when not to use it or contrast with every sibling.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds critical behavioral details: composite fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. No contradiction with annotations.

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

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

Description is relatively long but well-structured: starts with composite nature, then usage, return fields, ecosystem scope, and failure behavior. Every sentence adds value; minor redundancy in listing fields again after mentioning them in context.

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 (composite of two services, no output schema), the description fully covers inputs, outputs, failure modes, ecosystem limits, and timing. It lists all return fields, making up for missing 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?

Input schema has 100% coverage with descriptions. Description adds extra meaning: 'version' defaults to latest when omitted, 'package' accepts scoped packages like '@types/node'.

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

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

The description clearly states the tool is a composite check for adding an npm package, combining deps.dev and bundlephobia. It lists specific return fields and distinguishes from siblings by noting NPM-only scope in v1, with fallback to deps.dev for other ecosystems.

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 an agent asks about safety, popularity, size, or cost of adding a package. Mentions alternate approach for non-NPM ecosystems. Lacks explicit '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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true or false. The description adds context about full-text search and ranked results but does not contradict annotations. It provides minimal extra behavioral disclosure beyond what annotations cover.

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 most important information using examples, and every sentence adds value. It is concise, well-structured, and avoids redundancy with the schema.

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

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

Given that an output schema exists, the description appropriately notes that the tool returns ranked matches with Trakt IDs, which is sufficient. The tool has many optional parameters, but the description covers the core usage and integration with sibling tools, making it 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 100%, so the baseline is 3. The description adds value by mentioning key parameters like type and query in a usage context (e.g., 'Pass type="movie" or "show" to narrow'), which helps the agent understand how to use them 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's purpose: full-text search across movie, TV, episode, person, and list catalogs. It includes user-friendly examples like 'Search for movie / show [title]' and distinguishes itself from siblings by indicating that the returned IDs can be passed to get_movie/get_show.

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 patterns and suggests narrowing by type ('Pass type="movie" or "show"'). It lacks explicit when-not-to-use guidance, but the context implies it's for search, not retrieval of specific items (which siblings handle).

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, openWorld, non-destructive. The description adds valuable behavioral context: results are ranked by active watchers and are real-time trending. 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 extremely concise: two sentences plus parenthetical. It is front-loaded with example queries and contains no wasted words.

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

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

Given readOnly annotations, complete schema, and existence of an output schema, the description fully covers what the tool does and its behavioral context without 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 covers 100% of parameters with descriptions and examples. The description reinforces the 'type' parameter use and default limit, but does not add substantial new meaning beyond the schema baseline.

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

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

The description clearly states the tool's purpose: retrieving currently-trending movies or shows on Trakt, ranked by active watchers. It uses specific verbs ('trending', 'popular') and explicitly distinguishes from the 'popular' sibling tool by mentioning active watchers ranking.

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

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

The description provides concrete example queries ('What's trending on TV / movies right now') and instructs to pass 'type=movies' or 'type=shows'. It also suggests use for recommendations, but does not explicitly mention when not to use or compare to alternatives like 'popular'.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses behavior: returns a structured verdict (five possible values), extracted structured form, actual value with pipeworx:// citation, and percent delta. It also reveals efficiency gains by replacing multiple calls. No contradictions with annotations; actually adds valuable detail.

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 long but well-structured, front-loading with trigger phrases and purpose. Every sentence adds value: domain, return format, efficiency. It could be slightly tightened (e.g., removing the 'v1 supports...' inline detail), but overall it is 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?

Given the tool has no output schema, the description fully compensates by detailing the return value (verdict, structured form, actual value with citation, delta). It also specifies the supported domain (company-financial, US public companies) and data source (SEC EDGAR + XBRL). This is complete for an agent to understand both input and output.

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

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

Schema coverage is 100% with a clear description of 'claim' and examples. The description reinforces this by explaining the parameter's purpose and providing concrete examples ('Apple's FY2024 revenue...'). Since schema already documents it fully, a score of 4 is appropriate for adding clarifying context.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It lists specific trigger phrases ('fact check', 'verify the claim', etc.) and explicitly restricts the domain to company-financial claims for public US companies. This distinguishes it well from siblings like 'search' or 'entity_profile'.

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

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

The description explicitly says to use 'whenever the agent needs to check whether something a user said is factually correct' and notes it replaces 4-6 sequential calls, which provides clear usage context. However, it does not explicitly state when not to use it (e.g., for non-financial claims), so it loses a point for missing exclusions.

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