Watchmode

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context: default model, cost implications for Anthropic (BYO key), and return format details, which go 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, well-organized paragraph with front-loaded purpose, clear parameter hints, and no fluff. Every sentence adds value.

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

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

The description explains the return structure (per-model score, confidence, signals, raw_response + combined view) despite no output schema. It covers the entity input and optional parameters 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?

All parameters have schema descriptions, so the baseline is 3. The description adds practical details like the free default model and the BYO key requirement for Anthropic, enhancing semantics.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility. It specifies the resource and action (probe, score), but does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence' which may overlap.

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

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

The description includes use cases (AI-marketing audits, pre-launch brand checks) and mentions default model and optional API key. However, it lacks direct comparison with siblings and does not specify 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context by revealing the routing mechanism (3,668 tools, 860 sources) and stable citation URIs, going beyond what annotations convey. No contradictions.

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

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

The description is front-loaded with key guidance ('PREFER OVER WEB SEARCH'), then provides a comprehensive usage context. While lengthy, every sentence contributes value. Could be slightly trimmed but remains 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 complex tool without output schema, the description covers input semantics, routing, and citation format. It lacks details on error handling or fallback behavior, but given the rich annotations and examples, it is sufficiently complete for an AI agent to use effectively.

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

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

Schema has 100% coverage with descriptions for all parameters (including aliases). The description enhances this by explaining that the 'question' parameter accepts natural language and providing three concrete examples. This adds meaningful context 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 it answers factual questions using authoritative structured data, lists specific domains (SEC filings, FDA drugs, etc.), and explicitly positions it as preferable over web search. It distinguishes itself from generic search by citing the 3,668 tools and 860 sources.

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 clear when-to-use guidance with example queries and instructions to prefer over web search for factual questions. However, it does not differentiate from the sibling tool 'ask_pipeworx_grounded' or explicitly state when not to use it, missing an opportunity to exclude ambiguous or subjective queries.

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, openWorld, idempotent), the description details the tool's extraction process ('ONLY what the tool result contains'), the exact return fields including 'refusal_reason' and its possible values, and the additional LLM call cost. This fully discloses behavioral traits 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 key differentiator, then explains the mechanism, return format, and usage guidelines in a logical flow. Every sentence provides essential information without redundancy, achieving both conciseness and completeness.

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 lack of an output schema, the description compensates by fully specifying the return structure and error conditions. It covers purpose, behavior, usage context, and trade-offs relative to siblings, making it complete for an agent to decide when and how to invoke this tool.

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

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

Schema coverage is 100%, with all 6 parameters (5 aliases and 'question') documented in the schema. The description adds no additional semantics for parameters beyond what the schema already provides, meeting the baseline for high 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 defines the tool as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from sibling 'ask_pipeworx' by emphasizing extraction only from tool results. It specifies the exact return structure and refusal modes, leaving no ambiguity about what the tool does.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative 'ask_pipeworx' (for casual lookups). Also notes the cost trade-off of one extra LLM call, providing clear guidance for agent decision-making.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are supplemented by extensive behavioral details in the description: response shapes, resolver contract with confidence levels, parent event extraction, news fallback fields, safety short-circuits for low-confidence matches and closed markets, and illiquid spread handling. No contradictions found.

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 very long and dense, spanning multiple paragraphs with numerous examples and edge cases. While well-organized with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), it could be more concise for quick parsing by an agent.

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 covers virtually all behavioral aspects: resolver contract, parent event extraction, news fallback, safety mechanisms, and tradeability notes. The complexity is high, and the description provides sufficient context for correct tool invocation.

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

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

Schema description coverage is 100% for all three parameters. The description adds significant context beyond the schema, such as the format of the 'market' parameter, the effect of 'depth' (quick vs thorough), and the rationale for 'include_raw' (false recommended for size, true for full payloads). Examples in the schema further clarify 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 the overall function (resolves market, classifies, fans out, returns evidence packet and comparison). This distinguishes it from sibling tools like polymarket_edges or 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 explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides examples of fan-out for different bet types. However, it does not explicitly state when not to use this tool or mention alternatives, which would improve the score.

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

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

Adds substantial context beyond annotations: describes parallel call, sorted results by primary metric, returns paired data with citation URIs, and handles off-calendar fiscal years. Annotations already indicate safe, idempotent operation, and the description enriches this with behavioral details.

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 front-loaded with natural language examples and clearly structured. While somewhat verbose, each part serves a purpose: examples, preference note, data per type, sorting, output. Could be slightly tighter but remains 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 complexity and lack of output schema, the description covers key aspects: entity types, data sources, sorting, citation URIs. It does not mention limits on response size or pagination, but overall sufficient for an agent to understand the tool's function and output.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining value formats (tickers/CIKs for company, names for drug) and the data pulled per type, going beyond the schema's brief descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). It distinguishes itself from siblings like entity_profile by emphasizing multi-entity comparison and efficiency.

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

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

Explicitly advises ALWAYS PREFER over sequential single-pack lookups when comparing entities, and provides natural language triggers. It does not explicitly mention alternatives like entity_profile for single entities, but the sibling list is available for reference.

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 valuable context: returns top-N relevant tools with full schemas and examples, ready to call without second lookup. 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 well-structured: purpose first, then use cases, then return value, then usage advice. It is slightly verbose but every sentence adds value. Could be slightly shorter.

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

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

Despite no output schema, the description fully explains the return format (top-N tools with names, descriptions, and schemas with examples). The tool is simple (one required param), and the description covers what the agent needs to know.

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 6 parameters have descriptions). The description adds meaning by explaining that 'query' accepts aliases like task, q, description, search, and provides examples in the schema.

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

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

Description clearly states the verb 'find tools' and the resource 'by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.) and distinguishes from sibling tools by instructing to call this FIRST to see the option set.

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

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

Explicitly tells when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST...' It implies when not to use (when you already know the tool), but could be more explicit about 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining the fan-out across multiple sources, the USPTO soft-fail due to sunset, and the specific return fields. No contradiction with annotations.

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

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

The description is well-structured with examples at the start, followed by usage preference, sources, and return details. It is slightly verbose but every sentence adds value. The bullet-like list of returns could be more concise but is 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 (multiple data sources, no output schema), the description is highly complete. It covers input types, data sources, return fields, limitations (USPTO sunset), fallback behavior, and references sibling tools. No output schema exists, so the description carries full burden and meets 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 coverage is 100% with descriptions for both parameters. The description adds meaning by explaining that 'value' accepts ticker or zero-padded CIK but not names, and that 'type' only supports 'company'. This provides sufficient 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 it provides a full cross-source profile of a US public company, listing data sources and return fields. It distinguishes from the sibling 'resolve_entity' by specifying that names are not supported. The verb 'profile' and resource 'entity' are specific 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 explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and provides instructions for when only a name is available (use resolve_entity first). It also indicates that person/place types are not yet supported.

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 no new behavioral details (e.g., what happens if key doesn't exist, whether deletion is permanent). It focuses on usage rather than side effects.

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

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

Two sentences, front-loaded with the core action. Second sentence adds usage guidance. No wasted words, highly efficient.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and pairing. No additional information is necessary.

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 covers the one parameter 'key' with a description. Schema coverage is 100%, so the description adds no further semantic value beyond what the schema already provides.

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

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

The description clearly states the action: delete a memory by key. It specifies the resource (memory) and the method (by key). This distinguishes it from sibling tools like 'remember' (store) and 'recall' (retrieve).

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 when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with siblings 'remember' and 'recall', offering clear usage 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 provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. The description adds behavioral details: fetches the page, extracts specific elements, outputs a text blob ready for deployment. 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 plus a list of use cases, all essential. Front-loaded with the core action. No extraneous 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 explains the output format ('single text blob ready to drop at site-root/llms.txt') and covers the tool's purpose and usage. No output schema, but the description adequately completes the picture.

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

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

Schema description coverage is 100% for both parameters. The description does not add significant meaning beyond what the schema provides, but it hints at the extraction process. 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 generates a production-ready llms.txt file for any URL, detailing the process of fetching, extracting title/description/key links, and emitting standard markdown format. It distinguishes itself from potential siblings like scan_competitor_ai_presence by explicitly mentioning auditing a competitor's site.

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

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

The description lists three explicit use cases (indexing a client's site, drafting for own project, auditing a competitor), providing clear context. It does not include exclusions or when not to use, but the use cases effectively guide the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and behavior. The description adds minimal behavioral context (e.g., source: Watchmode, return fields), which is adequate but not extensive.

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 consists of two concise sentences that front-load the purpose and usage. 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?

The tool has no parameters and an output schema exists, so the description need not explain return values fully. However, it still mentions key return fields and provides a clear usage example, making it complete 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?

There are zero parameters, and schema description coverage is 100%. The description does not need to elaborate on parameters, and it provides no parameter-specific info, which is acceptable given the baseline for zero-parameter tools is 4.

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

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

The description clearly states it is a genre directory for movies and TV, listing examples like Action and Comedy, and specifies the return fields (genre ID, name, TMDb ID). It effectively distinguishes itself from siblings like list_titles by stating its use as a filter.

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 to filter list_titles by genre,' providing a clear use case. While it does not mention when to avoid alternatives, this guideline is sufficient for the tool's simple purpose.

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. Description adds no behavioral detail beyond stating return fields. For a simple read-only tool, this is adequate but not exceeding annotation coverage.

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

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

Two concise sentences: first states what it is and what it returns, second states its usage. No extraneous text. 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 zero parameters and an output schema present, the description fully covers tool behavior: returns language metadata to filter titles. No missing information needed for invocation.

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

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

Input schema has no parameters (100% coverage). Description adds value by explaining what the tool returns (language ID, name, ISO code) and its purpose, fulfilling the baseline for a param-free tool.

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 a language directory with ID, name, ISO code for filtering title catalog. Distinguishes purpose from sibling tools by specifying its role in filtering, but doesn't explicitly differentiate from other directory tools like 'genres' or 'regions'.

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 indicates when to use: to filter title catalog by language. Does not provide when-not-to-use or alternatives, but the context of sibling tools and the tool's specificity make usage clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. Description adds context on return fields and default active-only behavior, which is valuable 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 defines purpose, second gives usage guidance. Zero waste, 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?

No output schema, but description lists all returned fields. Single optional parameter fully covered. Agent can use tool correctly without additional 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?

Only parameter 'include_inactive' is fully described in schema. Description reinforces meaning by mentioning 'active subscriptions' as default. Adds 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?

Clearly states verb 'List', resource 'subscriptions', scope 'caller's active', and enumerates return fields. Distinct from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Implicitly excludes scenarios needing cancellation 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already provide safety and behavioral clues. The description adds no extra behavioral context, but does not contradict annotations.

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

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

The description is extremely short but at the expense of informativeness. It is under-specified rather than concise, with no structure or key details.

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 11 parameters, no schema descriptions, and no output schema details in the description, it is completely inadequate 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?

Schema description coverage is 0% and the description provides no information about any of the 11 parameters. It fails to explain parameter meanings, defaults, or valid values, leaving the agent without guidance.

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

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

The description 'Title catalog.' is vague and essentially restates the tool name without specifying the action (listing) or the scope. It does not distinguish this tool from siblings like title_search or title_detail.

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

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

No guidance on when to use this tool versus alternatives. The description lacks context on appropriate use cases, which is critical given many sibling tools such as title_search, title_detail, and genres.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds return fields (ID, name, origin country) beyond annotations, but no additional behavioral traits needed.

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 information-dense sentences with no wasted words. Purpose and usage are front-loaded.

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

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

Given no parameters and existence of output schema, description fully covers purpose, usage, and return fields. 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?

No parameters, schema coverage 100%. Description adds meaning by explaining the tool's directory purpose, which compensates for the lack of params.

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's a TV network directory, lists examples (HBO, FX, etc.), and specifies return fields (ID, name, origin country). This distinguishes it from siblings like list_titles.

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 recommends using before filtering list_titles by network, providing clear guidance on when to use this tool 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 are all false (no readOnly, destructive, etc.), and the description adds key behavioral details: rate limit of 5 per identifier per day, free usage, no quota impact, and that team reads digests daily. 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 concise (5 sentences) and well-structured, front-loading the core purpose. Every sentence adds value: usage scenarios, behavioral constraints, output expectations.

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 (3 params, no output schema), the description is complete. It covers all essential aspects: purpose, usage triggers, behavioral traits (rate limit, quota), and content guidelines (avoid end-user prompts). No gaps remain.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by explaining the meaning of the 'type' enum values and suggesting how to structure the 'message' (be specific, 1-2 sentences). While baseline is 3 due to high coverage, the extra guidance pushes 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?

The description clearly states the tool's purpose: reporting broken/missing functionality to the Pipeworx team. It explicitly lists feedback types (bug, feature, data_gap, praise), making it distinct from any sibling 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 provides explicit when-to-use scenarios for each feedback type (bug, feature, data_gap, praise). It also instructs the agent to describe issues in terms of Pipeworx tools/packs rather than end-user prompts, which is a critical usage rule.

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 valuable behavioral context: data source ('CF analytics-engine'), privacy ('no PII'), data structure ('pack, tool, count'), and caching ('5min-1h depending on window'). 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 paragraphs: first sentence states core purpose, then bullet-list of use cases, then technical details. 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 one optional parameter and no output schema, the description fully explains what the tool returns (top tools, packs, volume) and the data structure. Ideal for a simple query tool.

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

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

Only one parameter with enum, schema description is already detailed (100% coverage). Description reinforces the default (24h) and provides usage hint for window selection, adding 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?

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, using specific verb 'returns' and resource 'trending'. It distinguishes from siblings by focusing on what other AI agents are calling, which is unique among the listed sibling tools.

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

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

Description provides three explicit use cases and explains when to use different windows (shorter for current hotness, longer for steady-state). It lacks an explicit when-not-to-use or alternatives, but the context is clear enough to guide selection.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the tool is safe and non-destructive. The description adds extensive behavioral details: it uses Jaccard similarity (≥0.30) for cross-event pairs, applies a partition filter that drops placeholder slugs, and describes the response structure with gap_pp, suggested_trade, etc. 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 relatively long but well-structured, using bold for key terms, separate paragraphs for modes, and a clear list of response fields. It is front-loaded with the requirement and each section adds essential information. Minor redundancy could be trimmed, but overall it is effective and not overly 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?

Given the complexity of the tool and no output schema, the description thoroughly covers the response structure (opportunities[], partition_check), edge cases (no args fails), and important filters (Jaccard similarity, placeholder filtering). It provides a complete understanding of what the tool does, its inputs, and its outputs.

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

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

Schema description coverage is 100% with both parameters having descriptions. The tool description adds further context about the modes (single-event vs cross-event) and what happens with each parameter, including examples and details like accepting full URLs. 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 it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between single-event (event) and cross-event (topic) modes, each with specific use cases, and explains the methodology. The verb 'find arbitrage opportunities' combined with the specific resource (Polymarket) and the technical details (monotonicity, partition checks) makes purpose very clear.

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 that exactly one of 'event' or 'topic' is required, and calling with no args fails. It recommends 'event' for specific markets and 'topic' for cross-event scanning, explaining what each mode does. It does not explicitly state when not to use, but the context is clear enough for correct selection.

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

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

Annotations indicate readOnlyHint, idempotentHint, openWorldHint, and no destructive actions. The description adds extensive behavioral context: it describes caching (1h at KV level), response structure with diagnostics, 24h move warnings, and details of model families and filters. 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 and detailed, covering model families, response structure, and filter knobs. While every sentence adds value, it is quite long and could be more concise. The structure is organized but heavy.

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 fully explains the response top-level fields (by_segment with three categories, fed_candidates, _diagnostics) and their contents (e.g., edge_pp_net, kelly_fraction, market info). It also covers caching and filter skip diagnostics, making the tool's behavior completely understandable.

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 covers all 9 parameters with descriptions (100% coverage). The description adds significant value by explaining the purpose of tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) and detailing special cases like min_partition_leg_kelly applying to per-leg Kelly. This goes beyond the schema's basic 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 scans Polymarket markets for discrepancies with Pipeworx data, targeting 'what should I bet on today'. It explicitly details three opportunity segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge opportunities from Pipeworx 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 explains the tool is built for daily opportunity discovery without paging through hundreds of markets. It provides tradeable-edge knobs (min_liquidity, max_spread_pp) to filter unrealizable edges. However, it does not explicitly state when not to use it or compare to alternatives beyond the sibling list.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: two modes, response structure (leg-by-leg prices, matched spreads, top_spreads_pp), safety fields (compatibility_warning with two cases), temporal_alignment, and skipped_cross_type/subtype counters. 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 (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. However, it is somewhat verbose and could be slightly more concise, e.g., some details in SAFETY FIELDS could be streamlined. Still, 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 the tool's complexity (two venues, multiple parameters, safety warnings, no output schema), the description is exceptionally complete. It explains response structure, how to interpret temporal alignment and compatibility warnings, and the meaning of skipped counters. It sets proper expectations about rarity of real spreads.

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 3 parameters. The description goes beyond by explaining the topic's pre-mapped macros (list of 10), the override behavior of kalshi_event_ticker and polymarket_event_slug over topics, and providing examples in the schema. The description also clarifies the purpose of each parameter in the context of the tool's two modes.

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 computes 'Cross-venue spread between Kalshi and Polymarket', specifying the resource (cross-venue spread) and the action (computes). It distinguishes from sibling polymarket_arbitrage by focusing on spread rather than arbitrage opportunities.

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 two modes (topic vs explicit kalshi_event_ticker+polymarket_event_slug), details when to use each, and includes extensive warnings about compatibility and when spreads are meaningless (e.g., temporal alignment false, mismatched bet shapes). Also notes that pre-mapped topics often yield warnings.

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

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

Annotations declare readOnly=true, idempotent=true, destructive=false. Description adds critical scoping detail: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)'. Also explains behavior when key is omitted. 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 efficiently cover purpose, usage, and scoping. Examples slightly verbose but overall compact 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?

No output schema, but description implies returns a value or list. For 1-param read-only tool, covers key behavioral aspects (scoping, key omission). Could mention return format explicitly but acceptable.

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 100% with parameter 'key' described. Description adds usage nuance: 'omit the key argument' for listing all keys, which is not in schema. Provides examples of typical keys.

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 states 'Retrieve a value previously saved via remember, or list all saved keys' with specific verb (retrieve, list) and resource (saved keys). Distinguishes from sibling 'forget' and pairs with 'remember'.

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: 'look up context the agent stored earlier... without re-deriving it from scratch'. Clear that omitting key lists all keys. No explicit when-not or alternatives, but context is sufficient.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context beyond that: it reveals the mark_read parameter mutates state by flagging returned events read, affecting subsequent calls. It also explains the return payload fields, which is useful for the agent.

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

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

Three sentences covering purpose, details, and usage. No redundancy. The most important information (what the tool returns) is front-loaded. Every sentence earns its place.

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

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

The description explains the return fields, filtering, mark_read effect, and even an alternative REST endpoint. Given no output schema, this is good coverage. Minor gaps: no mention of pagination or ordering beyond 'most recent', but the limit parameter is in schema. Overall 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%, so baseline is 3. The description reinforces parameter usage with examples (e.g., type='sec_8k') and explains the effect of mark_read, but does not add new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'pull'/'returns' and the resource 'fired events from your subscription feed'. It specifies what each alert carries (source, citation_uri, raw payload). This distinguishes it from sibling tools like 'list_subscriptions' which manage subscriptions rather than retrieving events.

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 examples for filtering by type and since, explains the mark_read flag effect, and mentions that the same feed is available as a REST endpoint for scripts. However, it does not explicitly say when not to use this tool or suggest alternatives for specific needs like historical searches (which might be covered by other 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 description extensively discloses behavior beyond annotations: it explains the fan-out to multiple sources, fallback mechanism (GDELT→GNews), USPTO soft-fail, `since` parameter semantics, and output structure. 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 and front-loaded with examples, but it could be slightly more structured. Every sentence adds value, and it efficiently covers the tool's purpose, behavior, and parameters.

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

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

For a tool with 3 parameters and no output schema, the description fully explains inputs, behavior, return format (changes grouped by source, total_changes, citation URIs), edge cases (USPTO soft-fail), and alternative tool. Very 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 description adds significant value by explaining `since` formats (ISO vs relative), default usage ('30d'), and that `value` can be ticker or CIK. However, the schema already covers basics.

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

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

The description uses specific verbs and examples ('What's new with X', 'latest on Y') to clearly state it provides a change feed for a company. It explicitly distinguishes from the sibling tool 'entity_profile' which offers static profiles.

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

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

The description gives explicit query examples and explains when to use this tool versus 'entity_profile'. It also details the `since` parameter format. However, it does not contrast with many other siblings, but the single contrast is sufficient.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds non-obvious behavioral details: output format (2-letter codes) and its role in constraining other tools. This complements the annotations well.

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, immediately stating the purpose and output, then the usage. No unnecessary words, highly efficient.

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

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

Given no parameters, extensive annotations, and an output schema, the description is fully complete. It explains what the tool returns and how to use it, meeting all contextual needs.

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 no parameters and 100% schema coverage (empty schema), the description adds meaning by explaining the output format and usage context. Baseline is 4 for zero-param tools, and the description meets this.

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 indicates the tool returns supported regions/countries for streaming availability, lists example codes, and mentions its output format (2-letter codes). It also relates to sibling tools like title_sources and list_titles, distinguishing its purpose.

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

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

The description explicitly states the primary use case: to constrain title_sources or list_titles to a region. It provides clear context on when to use the tool, though it does not mention when not to use it or alternatives, which is acceptable given its specific role.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds no additional behavioral context (e.g., pagination, date range interpretation, or what 'recent/upcoming' means operationally). Minimal added value.

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

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

Extremely concise (3 words) but at the expense of informativeness. No structure, no actionable details. Conciseness without substance scores low.

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 8 parameters and an output schema, the description is woefully incomplete. Agent cannot determine how to filter, what data is returned, or how to formulate a valid request. Requires significant additional context.

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

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

Schema description coverage is 0%, so description must compensate. It does not mention any of the 8 parameters or their semantics. Examples in schema provide some clues but description itself offers zero parameter guidance.

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

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

Description is 'Recent/upcoming releases.' which is a noun phrase, not a verb+resource. It vaguely indicates the tool deals with releases but doesn't state what action (list, search, etc.). Lacks specificity to distinguish from sibling tools like 'list_titles' or 'title_search'.

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

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

No guidance on when to use this tool versus alternatives. No context on prerequisites, filters, or exclusions. The agent is left to infer usage from the name alone.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context about key-value scope, persistence differences between authenticated and anonymous sessions, and 24-hour retention. 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, no filler, front-loaded with the core 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?

Given the simple tool (2 required params, no output schema, good annotations), the description covers purpose, usage, behavior, and pairing 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 descriptions for key and value. The description adds context beyond the schema by explaining the key-value pair scoping and giving examples, which helps the agent understand usage.

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

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

The description uses a specific verb ('Save') and resource ('data'), clearly defines the scope ('across this conversation or across sessions'), and distinguishes from siblings like 'recall' and 'forget' by mentioning them.

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

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

It explicitly states when to use ('when you discover something worth carrying forward') and references 'pair with recall to retrieve later, forget to delete' for alternatives. It could improve by noting 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 readOnly, idempotent, non-destructive. Description adds that each call cascades through several internal endpoints, explaining potential latency or rate-limit implications. Also specifies exact return fields and citation URIs per type.

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 fairly lengthy but well-structured with clear sections (examples, usage, supported types, return details). Every sentence adds value, though could be slightly tightened without losing clarity.

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

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

Given the tool's complexity (multiple entity types, multiple input formats, no output schema), the description is fully complete: covers input, behavior, output details, and context. Annotations cover safety. 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%, but description adds significant context: for 'type' it lists allowed values and their meanings; for 'value' it provides input format examples (ticker, CIK, name for company; brand or generic for drug) and mentions auto-disambiguation, greatly aiding parameter 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 resolves a name to a canonical identifier, with specific examples like ticker, CIK, RxCUI. It differentiates from siblings by focusing on resolution, and mentions it replaces 2-3 manual 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 FIRST whenever you have a name but need an ID', providing strong guidance on when to use. Also details supported types and what each returns, guiding the agent on input selection.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, destructiveHint false, so it's safe. Description adds behavioral context: it probes each entity with ai_visibility_check, treats first entity as subject for narrative, and returns ranked list with score, confidence, signal density. No contradictions.

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

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

Two sentences plus a parenthetical example and result description. Front-loaded with main purpose, each sentence adds value. Very efficient and 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 4 parameters, no output schema, and rich annotations, the description adequately covers what the tool does, how it works (probes via ai_visibility_check), and what it returns (ranked list with metrics). Could mention the entity count limit (2-8 from schema) but does not hinder completeness significantly.

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

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

Schema coverage is 100%, but description adds value beyond schema: clarifies first entity is treated as subject for narrative, and context disambiguates common names. It also reinforces the models parameter defaults, though that is in schema. Provides useful narrative context for the entities parameter.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity probe) by specifying it is a batch comparison 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?

Description explicitly says when to use: competitive AI-marketing audits, including a concrete example ('does Claude know about us as well as our competitors?'). It implies use for multiple entities but does not explicitly state not to use for single-entity queries (use ai_visibility_check 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, idempotentHint, and non-destructive. The description adds valuable behavioral context: fans out to external services, returns a specific summary block, handles partial failures gracefully, and notes that bundlephobia's first measurement can take 5-30 seconds. 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 information-dense but front-loads the core composite nature. Every sentence contributes (ecosystem limitation, partial failures, return structure). Slightly verbose but well-structured; a minor reduction from 5 due to length.

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

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

No output schema exists, so the description fully covers return values: summary block fields, per-advisory detail, links, and alternative versions. It also addresses edge cases like scoped packages, partial failures, and bundlephobia timing. Given complexity, it leaves 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 clear descriptions for both parameters. The description adds extra meaning by explaining that version defaults to latest when omitted and that scoped packages like '@types/node' are accepted. This goes beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states the tool's purpose: a composite check for 'should I add this npm package' by aggregating data from deps.dev and bundlephobia. It uses specific verbs ('scan', 'fans out') and distinguishes itself from sibling tools like 'bet_research' or 'scan_competitor_ai_presence' by being npm-focused and multi-source.

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 triggers are given: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes NPM ecosystem only and directs to deps.dev:version for other ecosystems. Partial failure behavior is described, providing clear when-to-use and when-not-to-use guidance.

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

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

Discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K), and truncation behavior. None of this is in annotations, so adds significant value beyond readOnlyHint etc.

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-loaded with purpose, efficient examples, and technical details. Every sentence adds value with 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 purpose, usage, parameters, output format (passages with offsets and scores), behavior, and pairing with sibling tool. No output schema, but description sufficiently explains return values.

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 concrete examples for 'text' (e.g., SEC 10-K body) and 'query' (e.g., supply-chain risk), and clarifies 'limit' as top-N passages. Provides meaningful context 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?

Clearly states semantic search inside a fetched record, specifying verb, resource, and output (passages with offsets and scores). Distinguishes from sibling tools by mentioning ask_pipeworx_grounded.

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

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

Explicitly says when to use: when record is too large for prompt. Also describes pairing with ask_pipeworx_grounded for grounding over passages.

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 destruction. The description adds valuable details about the returned fields (IDs, name, type, regions, logo) and confirms global coverage, enhancing transparency beyond annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose and includes a practical usage hint, making it highly efficient and easy to parse.

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 parameters, a rich output schema, and thorough annotations, the description is complete. It explains what the tool returns and its purpose, leaving no gaps for an agent to misunderstand.

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 zero parameters (100% coverage), so the description naturally lacks parameter-specific info. Baseline score of 4 is appropriate as no additional parameter context is needed.

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

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

The description clearly states the tool returns a directory of all streaming sources worldwide with specific data fields (IDs, name, type, regions, logo). It distinguishes itself from siblings by advising use as a directory before filtering with list_titles.

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 ('Use as a directory before filtering list_titles by source'), providing a clear use case and referencing a sibling tool. It does not provide explicit when-not-to-use guidance, 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?

Discloses behavioral traits beyond annotations: requires OAuth, cannot be anonymous/BYO, delivery limits (SMS cap, webhook auto-disable), and signing secret returned once. 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?

Well-structured and front-loaded with purpose. Detailed but concise given complexity. Could trim some verbose examples slightly.

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?

Highly complete for a complex subscription tool with multiple types and delivery channels. Covers requirements, examples, constraints. No output schema, but description sufficiently explains return (new subscription id). Minor gaps like error handling not covered.

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?

Adds significant meaning beyond the input schema: explains each subscription type with concrete examples and clarifies delivery channel details (email, SMS with verification, webhook with HMAC). Schema covers 100% but description enriches 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?

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription id. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Explains when to use (to create subscriptions for proactive monitoring) and mentions requirements (Pipeworx OAuth account). Could explicitly mention alternatives like list_subscriptions for existing subs, but still strong guidance.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds valuable behavioral context: it returns example questions, can be called with no arguments or a focused topic, and draws from a live catalog. 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 a single focused paragraph with front-loaded alternative phrasings. It efficiently conveys purpose, usage, and parameters without extraneous words, though slightly dense.

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 tool (1 optional parameter, no output schema, rich annotations), the description fully covers purpose, when to use, parameter behavior, and what to expect. It is complete for an agent to make an informed decision.

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 the topic parameter described. The description enhances semantics by explaining that omitting topic yields a cross-category spread and listing example values, adding meaning beyond the schema.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions, distinguishing it from siblings like ask_pipeworx and discover_tools. It uses specific verbs ('returns', 'call') and specifies the resource ('category-bucketed example questions').

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 ('Use this FIRST when you do not yet know what Pipeworx can do for you') and how to use the optional topic parameter. While it doesn't explicitly list when not to use it, the context and sibling list provide sufficient 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 provide strong behavioral hints (readOnly, idempotent, not destructive), but the description adds no additional context beyond 'Title detail.' There is no contradiction, but the description fails to enhance understanding.

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

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

Extremely concise but under-specified. A single phrase 'Title detail.' is too minimal to be helpful; it is not a proper description of functionality.

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

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

Despite having an output schema and rich annotations, the description omits critical usage context. It doesn't explain that it returns details for a specific title or how to use the 'append_to_response' 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 description coverage is 0%, and the description provides no information about the parameters 'title_id' or 'append_to_response'. Without any compensation, the agent cannot infer proper 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 'Title detail.' is a tautology that merely restates the tool name and title. It lacks a specific verb and resource, and does not distinguish the tool from siblings like 'list_titles' or 'title_search'.

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

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

No explicit guidance on when to use this tool versus alternatives. The name implies it retrieves a single title's details, but no when-not or context 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds no further behavioral context, but does not contradict annotations. A score of 3 is appropriate as the description adds minimal value 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 extremely short, but this is under-specification rather than efficient conciseness. It fails to convey 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 the tool has three parameters, many sibling tools, and an output schema, the description is critically incomplete. It provides no context about search capabilities, scope, or return format.

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

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

Schema description coverage is 0%, so the description must compensate. However, it provides no explanation for the three parameters (types, search_field, search_value), leaving their meanings entirely unspecified.

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 'Search titles.' is a tautology, merely restating the tool name without specifying the resource or behavior. It provides no differentiation from sibling tools like list_titles or search_within.

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 usage guidance is provided. The description does not indicate when to use this tool versus alternatives, such as comparing with list_titles for listing all titles or search_within for narrower scope.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds specific information about return values (episode count, season number, year), which provides useful behavioral detail 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 concise sentence with an additional usage instruction. It is front-loaded with the core functionality and returns fields, with no wasted words.

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

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

For a simple tool with one parameter and strong annotations, the description covers purpose, usage context, and return fields. No additional details (e.g., pagination, rate limits) are necessary given the tool's straightforward nature.

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%, and the description only mentions 'Watchmode TV show ID' for the title_id parameter without specifying format, constraints, or examples. The description does not adequately compensate for the lack of schema parameter 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 retrieves seasons and episodes for a Watchmode TV show ID, listing specific return fields (episode count, season number, year). It distinguishes from sibling tools like title_search by specifying usage after searching for a 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 explicitly instructs the agent to use this tool 'after title_search to enumerate a show's structure', providing a clear workflow and context for when to invoke 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?

The annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond stating it is about 'streaming sources'. It does not disclose return format, pagination, rate limits, or any constraints. The description is essentially a label, not a behavioral disclosure.

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?

While only two words, the description is under-specified rather than concise. It sacrifices clarity for brevity, making it unhelpful for an agent. Concision should maintain utility; here it does not.

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 but its content is unknown, the description still fails to specify what the tool returns. For a tool with two parameters and siblings like 'sources', the description should explain scope or filter behavior. It is grossly 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?

With 0% schema description coverage, the description must compensate by explaining parameter meanings. It fails to do so entirely. The parameters 'title_id' and 'regions' are not explained; the description does not indicate that 'title_id' is required or that 'regions' is an optional comma-separated list.

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 'Streaming sources' is extremely vague. It does not specify whether the tool retrieves, lists, or manages streaming sources for a title. The name 'title_sources' implies a relationship to titles, but the description provides no action verb or resource clarification, and it does not distinguish this tool from similar siblings like 'sources'.

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?

There is absolutely no guidance on when to use this tool versus alternatives. The description lacks any context about prerequisites, typical use cases, or situations where another tool would be more appropriate.

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

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

Adds significant context beyond annotations: ownership enforcement, row deactivation vs deletion, and historical event availability via recent_alerts. Annotations already provide idempotentHint, readOnlyHint, destructiveHint.

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, 26 words, front-loaded with the primary action. 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?

For a simple tool with one parameter and no output schema, the description covers ownership, mutability, side effects, and ties to a sibling tool perfectly.

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 parameter description. The description only implicitly refers to the parameter via 'by id' and adds no extra semantics beyond the schema.

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

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

The description clearly states the verb 'cancel' and the resource 'subscription by id', distinguishing it from sibling tools like subscribe, list_subscriptions, and recent_alerts.

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

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

It indicates when to use (to cancel a subscription), specifies ownership enforcement, and explains the deactivation behavior with a link to recent_alerts. Does not explicitly exclude certain cases 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?

The description fully discloses behavioral traits: it returns a verdict, structured form, actual value with citation, and percent delta. It also mentions it replaces 4–6 sequential calls. Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds value beyond these.

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 yet comprehensive. It starts with natural-language examples, defines the tool, states usage context, specifies scope, and details return values. Every sentence adds value, and the structure is well-organized.

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

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

Given the single parameter with full schema, rich annotations, and detailed description, the tool definition is complete. The description explains the return values even without an output schema. It addresses all necessary aspects for an AI 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?

The single parameter 'claim' has complete schema description. The description adds context about the type of claims supported (company-financial) and natural-language format. With 100% schema coverage, baseline is 3, but the added context justifies a 4.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific examples of queries and distinguishes itself by noting it replaces multiple sequential calls, which differentiates it from sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the current scope (company-financial claims). It doesn't provide explicit 'when not to use' or alternative tools, 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.