Trakt

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read-only behavior. The description adds valuable context: it probes multiple models, scores 0-100, defaults to Workers AI (free), and passes the API key to Anthropic only when needed. No contradictions with annotations.

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

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

The description is three sentences long, front-loaded with the core action, and every sentence adds value. There is no redundant or extraneous information. It is perfectly concise.

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

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

Given the tool's moderate complexity (probing multiple models, optional API key, scoring), the description covers all essential aspects: input parameters, default behavior, optional key, return structure (per-model fields and combined view). No output schema is provided, but the description sufficiently describes the 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%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining that the default model is free and that '_apiKey' is required only when probing Anthropic. This provides context on usage that the schema alone does not.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the default model and optional other model. The tool is clearly distinct from siblings like 'ask_pipeworx' or 'deep_research' which serve different functions.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default model (free) and the need for an API key to probe Anthropic. However, it does not explicitly state when not to use or list alternative tools.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context about the routing mechanism (5,718 tools, 1496 sources) and the output format (structured answer with stable citation URIs), which is beyond what annotations say. It doesn't discuss rate limits or auth, but those are not critical given the safety profile.

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

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

The description is long but every sentence earns its place: it front-loads the critical advice ('PREFER OVER WEB SEARCH'), gives examples, explains alternatives, and ends with stepping-stone guidance. It's structured logically, though the length is substantial; the density is high but not wasteful.

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 no output schema, the description covers everything: the range of domains, the behavior, the output format (structured with citation URIs), and the usage context. It also addresses when not to use it (step-up tools). The agent has all the information needed to call it correctly.

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

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

Schema description coverage is 100%: the question parameter and all aliases are documented in the schema. The description doesn't add parameter-specific meaning beyond what's already there, so a baseline of 3 is appropriate according to the rules.

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 is exceptionally clear: it states the tool answers factual questions by routing to thousands of source tools, returns structured answers with citations, and explicitly differentiates from sibling tools like ask_pipeworx_grounded and deep_research. The verb and resource are precise, and the scope is well-defined.

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

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

Explicit guidance is everywhere: it says to prefer this over web search, identifies it as the default starting point, and provides concrete conditions for stepping up to ask_pipeworx_grounded or deep_research. It even includes examples for both general and breaking-news queries. This leaves nothing to inference.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses that candidate routing improvements are only active 'whenever one is under test', that none is currently active (with a retirement date), and that it is a full working router rather than a fallback stub. This gives useful behavioral context for an experimental edge tool.

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

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

Four sentences, each carrying distinct information: definition, live state, usage instruction, and fallback clarification. It is somewhat dense with parenthetical detail, but nothing is redundant and the key decision information appears early.

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

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

With no output schema, the description compensates by stating the response shape is identical to ask_pipeworx. It covers beta status, current active candidate, how to use, and experimental purpose, so an agent has enough context to invoke it correctly and set expectations.

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

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

The schema already documents the required 'question' parameter and all five aliases at 100% coverage, so the description need not repeat them. It references 'same arguments' as ask_pipeworx but adds no meaning beyond the schema; baseline 3 is appropriate.

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

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

Description names the tool as the beta version of ask_pipeworx, defines it as a universal router covering the same 5,718 tools with the same arguments and response shape, and explicitly contrasts it with the stable ask_pipeworx router. The current no-candidate state is stated, so an agent understands exactly what this tool is.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared with the stable router. It does not discuss when to prefer ask_pipeworx_grounded or other siblings, but the primary alternative is clearly named and the selection condition is given.

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

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

Beyond the readOnlyHint and idempotent annotations, the description discloses the full success/failure contract: returns {answer, evidence, confidence, source, fetched_at, refusal_reason:null} or an explicit refusal with enumerated reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also states the extraction is constrained to the tool result, which is critical behavioral context.

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

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

The description is information-dense and front-loaded with the purpose, then details the routing, return shape, refusal reasons, and usage. It is slightly long but every sentence earns its place, and the structure is logical. Not bloated.

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?

It covers the routing mechanism, success/refusal return shapes, refusal reason taxonomy, cost trade-off, and high-stakes use cases. No output schema exists, so the description fully compensates by specifying return structure. No critical information is missing for an agent to invoke it correctly.

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

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

The schema already fully documents all six parameters as aliases for the question, with a description for each and 100% coverage. The description adds no parameter-specific guidance beyond the conceptual routing behavior, so it contributes little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly differentiates from ask_pipeworx by the extraction behavior (uses ONLY tool result) and the additional LLM call cost. It names the exact use cases (quoted, cited, acted-on answers) and the resource (the answer, evidence, etc.).

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 gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and explicitly says 'prefer ask_pipeworx for casual lookups.' It also highlights the cost trade-off, leaving no ambiguity about selecting this over its sibling.

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

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

The description provides extensive behavioral context beyond the annotations, detailing the classification fan-out, response shapes, resolver contract, safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. There is no contradiction with annotations (readOnlyHint=true, 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?

The description is long but well-organized with section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and no unnecessary repetition. While it could be slightly trimmed, the detail is justified by the tool's complexity.

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

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

Given the complexity and absence of an output schema, the description fully covers the response shape, edge cases (low-confidence, closed markets, wide spreads), and resolution rules. It even includes practical warnings (e.g., checking cancellation rules before sizing sports bets).

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% (all parameters described), and the description adds significant value: 'market' accepts slug, URL, or text; 'depth' enum explained with defaults; 'include_raw' provides trade-offs on response size. This goes well beyond the schema alone.

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: to research a Polymarket bet by pulling Pipeworx data. It specifies the verb ('Research'), the resource ('a Polymarket bet'), and provides concrete examples of use cases ('should I bet on X'). This distinguishes it from sibling tools like deep_research or ask_pipeworx which are more general.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X"...') but does not mention when not to use it or suggest alternatives. While the use cases are clear, the lack of exclusions or alternative guidance prevents a perfect 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?

Beyond the annotations (which already indicate read-only, open-world, idempotent), the description reveals important behavioral details: it makes parallel calls, correctly handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. Nothing contradicts the annotations.

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

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

The description is informative but slightly wordy, especially the opening line which mixes many examples. However, it front-loads the key action and contexts. Every sentence adds value, but minor trimming could improve conciseness.

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

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

Given the tool's moderate complexity (two parameter types, two entity types, no output schema), the description covers what data is returned, cites sources, explains sorting, and quantifies efficiency. It leaves no critical gaps for an agent to understand how to invoke and interpret results.

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

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

The schema already documents type and values, but the description adds critical meaning: it explains what values mean (tickers/CIKs for companies, drug names for drugs), the allowed range (2-5 items), and how each type affects the data pulled. This fully compensates for any schema brevity.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call. It specifies the data sources (SEC EDGAR for companies, FAERS/FDA for drugs) and the exact metrics returned, making the purpose unmistakable and distinguishing it from single-entity tools like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and quantifies the efficiency gain ('Replaces 8–15 sequential lookups'). It gives strong guidance on when to use, though it does not explicitly mention cases where this tool should not be used, leaving room for improvement.

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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: account/tier requirements, parallel decomposition across 5,718 tools, 15-90s latency, gaps[] semantics, contradictions[], resolvable pipeworx:// citation_uri, and semantic excerpting. These are consistent with the annotations, so there is no contradiction.

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

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

The description is long but dense and front-loaded with the account gate followed by capability, alternatives, and depth behavior. Nearly every sentence carries distinct operational information, though a few depth details are repeated from the schema, preventing a perfect score.

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?

There is no output schema, but the description thoroughly specifies the findings packet structure, citation behavior, gaps[] and contradictions[], auth requirements, latency envelope, and sibling routing. Nothing essential for correct invocation or result interpretation appears to be missing.

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

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

Schema coverage is 100%, but the description goes further by adding operational meaning: depth:'thorough' is paid, quick/standard run 3 facets, standard re-angles gaps, thorough chases leads, and question explicitly accepts broad/multi-part natural language. It slightly overlaps with the schema's enum descriptions, but it still adds real value.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1496 STRUCTURED data sources' in ONE call. It explicitly says 'this is NOT open-web search' and distinguishes itself from ask_pipeworx, so an agent can recognize both what it does and what it does not do.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, use ask_pipeworx for single lookups, prefer ask_pipeworx for breaking/current-news topics, and use ask_pipeworx if not signed in. This leaves no ambiguity about sibling 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?

Description adds value beyond annotations by stating that results include full schemas with curated examples and are ready to call directly, and that no second lookup is needed. Annotations already declare readOnlyHint and idempotentHint, and description is consistent.

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

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

Description is a single paragraph that efficiently covers purpose, usage, and output. Slightly verbose with the list of topics, but overall front-loaded and without unnecessary sentences.

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

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

Given no output schema and moderate complexity, the description adequately describes return format (top-N tools with schemas) and usage context. Minor omission of sorting/relevance but compensated by examples.

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

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

Schema coverage is 100%, so the description adds minimal new information about parameters. It provides an overview that query accepts aliases, but the schema already documents each alias individually. 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?

Description clearly states the tool finds tools by describing data/task, lists extensive examples, and distinguishes from sibling tools like search and deep_research by focusing on tool discovery rather than data retrieval.

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

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

Explicitly says 'Use when you need to browse...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', 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?

Annotations already declare readOnlyHint, openWorldHint, etc. Description adds soft-fail for patents, news fallback, and return field details 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?

Single paragraph with example queries upfront and structured list of returns. Slightly verbose but 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?

No output schema, but description thoroughly explains all return fields, data sources, and edge cases (soft-fail, fallback). Complete for a 2-param 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%. Description adds context like zero-padded CIK requirement and that type is only 'company', going beyond schema descriptions.

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

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

Clearly states it returns a full cross-source profile of a US public company in one call, listing data sources and fields. Distinguishes from chaining single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining...' and specifies supported inputs (ticker/CIK, not names) with a fallback to resolve_entity.

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, so the description's 'Delete' and 'clear sensitive data' are consistent but add minimal extra insight. The description could mention irreversibility but is not necessary given the simple action.

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 cover purpose, usage, and context without wasted words. The most critical information is front-loaded in the first sentence.

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 1-parameter, no-output-schema tool, the description fully enables an agent to understand purpose, when to use, and how to use it. Pairing hints with sibling tools round out the context.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description adds no additional semantics beyond restating 'by key' and giving an example, which is adequate but not additive.

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') and the resource ('a previously stored memory by key'). It distinguishes itself from sibling tools 'remember' and 'recall' by indicating it is the deletion counterpart.

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 three clear usage scenarios: stale context, task completion, and clearing sensitive data. It also mentions pairing with 'remember' and 'recall', indicating when not to use it in isolation.

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

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

The description discloses that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This aligns with annotations (readOnlyHint, idempotentHint) and adds behavioral context beyond the annotations, such as the extraction process and output format.

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: two sentences followed by a usage list. The main action is front-loaded, and every sentence earns its place. No redundant information.

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

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

Given the simple tool (2 params, no output schema), the description fully explains the output format and usage. Annotations cover safety aspects. The description is complete enough for an agent to understand what the tool does and what to expect.

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

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

The input schema provides descriptions for both parameters (url and max_links), so baseline is 3. The description adds value by specifying default max_links (25) and max (50), and clarifying that the URL should be a full URL. Thus, it enhances parameter understanding beyond schema alone.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, specifying the actions (fetch, extract, emit) and the output format. It distinguishes itself from sibling tools by its specific function, which is unique among the listed siblings.

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

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

The description provides concrete examples of when to use the tool (e.g., getting a client's site indexed, drafting for own project, auditing competitors). While it does not explicitly mention when not to use it or alternatives, the usage contexts are clear and helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context by listing specific return fields, which is additional 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 concise (2-3 lines), front-loaded with example queries, and efficiently conveys purpose and output. 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 presence of an output schema, the description adequately covers purpose, input, and output. For a simple retrieval tool, it is complete and self-contained.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add new semantic meaning to parameters beyond the schema examples and field names.

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

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

The description clearly states it retrieves a single episode record by show, season, and episode number, listing returned fields (title, summary, runtime, air date, IDs). This distinguishes it from siblings like get_movie, get_show, and list_seasons.

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

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

The description implies usage for specific episode queries via example patterns, but does not explicitly state when to use this tool versus alternatives (e.g., list_seasons for all episodes). No exclusion criteria are provided.

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

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

Annotations already provide readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining the effect of the extended parameter and that it fetches from Trakt. 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: first establishes core purpose, second explains optional functionality. No wasted words, essential information 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 the schema covers parameter descriptions, annotations cover safety, and an output schema exists, the description is complete. It explains input variants and extended option, which is all that's needed.

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

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

Schema coverage is 100%, but the description adds specific meaning: it lists the fields included with extended='full' (plot, runtime, genres, etc.). This goes beyond the schema's enum values. The examples also illustrate 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 verb 'Fetch', the resource 'movie record', and the source 'Trakt'. It specifies multiple ID types (Trakt ID, slug, IMDB/TMDB ID) and optional extended parameter. This clearly distinguishes it from sibling tools like get_episode or get_show.

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

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

The description explicitly tells when to use the extended parameter to get additional fields. While it doesn't contrast with alternatives, the sibling context makes it clear this is for movies. It could mention scenarios where not to use it, but it's 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. Description adds details about return content and ID formats, but no mention of rate limits or error handling. Adds 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?

Front-loaded with example queries, followed by core description. Somewhat lengthy but each part contributes value. Could be slightly more 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?

With output schema present, return values are covered. Description provides typical use cases and parameter details for the two inputs. Adequately complete given the tool's simplicity.

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

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

Schema coverage is 100%, baseline 3. Description explains 'extended="full"' returns runtime, genres, cast, rating, etc., and that 'id' accepts Trakt ID, slug, or IMDb ID, adding meaning 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 retrieves TV show info, provides typical user queries, and specifies ID types. It distinguishes from siblings like get_episode and get_movie by focusing on show-level 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?

Example queries imply when to use (e.g., 'details on [series]'), but no explicit 'when not to use' or direct alternatives. Siblings provide context but without explicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining that passing extended='episodes' includes episode data in the response, which is behavioral detail beyond annotations. No contradictions.

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

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

Two sentences efficiently convey purpose and a key parameter detail. Front-loaded with example queries. No unnecessary words; 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 tool is simple with two parameters, and an output schema exists, so return values are covered. The description covers the main use case and the extended option. Omits details like default ordering or limits, but with the output schema and annotations, it's sufficiently complete for this tool.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description further clarifies the extended parameter by specifying the exact value ('episodes' and 'full,episodes') and its effect. This adds meaningful context beyond the schema, justifying above baseline.

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

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

Description clearly states the tool lists seasons of a show with episode counts, using specific examples like 'How many seasons of [show]' and 'list seasons of [TV series]'. It distinguishes from sibling tools like get_show and get_episode by focusing on aggregate season data, making purpose unambiguous.

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

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

Examples explicitly show when to use the tool (querying season counts or lists). However, it lacks explicit guidance on when not to use it or mention of alternatives like get_episode for individual episodes. Still, the context is clear enough for an agent to infer typical usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it lists active subscriptions by default and outlines the return fields, adding value beyond annotations without contradiction.

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

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

Two concise sentences: first covers purpose and output, second provides usage guidance. No wasted words.

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

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

Given the tool's simplicity (one optional param, no output schema, rich annotations), the description is fully adequate. It explains what it does, what it returns, and when to use 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 a single parameter (include_inactive) fully described. The description mentions 'active subscriptions' which implies default behavior but does not add significant new meaning beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the return fields (id, type, params, etc.). It distinguishes itself from siblings like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides both usage context and practical application.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later'), and notes that feedback doesn't count against quota. This is rich behavioral context beyond annotations.

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

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

The description is long but every sentence adds necessary detail for a tool with multiple use cases and a callback mechanism. It is front-loaded with the main purpose, then covers exclusions, token workflow, rate limits, and cost. No filler or redundancy.

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

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

Given the tool's complexity (4 params, nested objects, no output schema), the description fully covers usage scenarios, exclusions, token retrieval, rate limits, and team process. It explains enough about returns (claim_token, status) even without an output schema. This is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value by explaining the claim_token usage pattern concretely ('pipeworx_feedback({claim_token:"pwfb_…"})') and the context object's purpose in relating to Pipeworx tools/packs. However, the schema already documents each parameter well, so the increment is modest.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb (tell/feedback) and resource (Pipeworx team), and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on reporting issues or praise about Pipeworx 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?

Provides explicit when-to-use guidance: for bugs, feature requests, data gaps, or praise. Also gives a clear exclusion: only for tools served by this Pipeworx connection, not other vendors' MCP servers. Additionally, explains the claim_token workflow for reading previous feedback, which is a key usage pattern.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by disclosing: data source (CF analytics-engine), privacy (no PII), caching behavior (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?

Description is well-structured with a summary sentence followed by numbered use cases. However, it is slightly verbose; the use cases could be more concisely phrased.

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 is provided, and the description only vaguely mentions 'returns the top tools, top packs, and total call volume'. The exact structure of the response (e.g., format, keys) is missing, which may leave the agent guessing for a tool with simple but multiple return fields.

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

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

Schema already provides enum and description for window parameter. Description adds contextual meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose appropriately.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a window. It distinguishes itself from siblings like 'trending' (which may be domain-specific) and 'discover_tools' by specifying 'what other AI agents are calling on Pipeworx right now', making its niche 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?

Provides three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment of use case. However, it does not explicitly state when NOT to use the tool or compare with alternatives like 'trending' or 'popular', which are sibling tools.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds significant behavioral context: partition_check, Jaccard similarity threshold, partition filter, fill_check behavior, and response format. It fully compensates for the lack of output schema.

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

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

The description is lengthy but well-structured with clear sections and front-loaded purpose. Every sentence adds value for a complex tool. Minor verbosity could be trimmed, but it remains efficient given the tool's sophistication.

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 completely covers the response structure (opportunities array, partition_check object, fill_check fields). It addresses behavioral nuances (semantic anchor, partition filter) and references sibling tool for custom sizing. No gaps in context.

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

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

The schema has 2 optional parameters with descriptions, achieving 100% coverage. The description adds substantial meaning: explains the two parameter modes, the trending scan behavior with no args, and detailed semantics for event and topic parameters beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and briefly contrasts with sibling tools like polymarket_edges and polymarket_fill_risk, providing clear purpose and differentiation.

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

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

The description gives explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also explains when not to trade based on fill_check results and points to polymarket_fill_risk for custom sizing.

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

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

The description discloses extensive behavioral traits beyond annotations, including the three response segments, edge calculation details, caching at 1h, diagnostic information for empty segments, and exclusion of Fed bets from ranking. This transparency far exceeds what readOnlyHint alone provides.

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 excessively long and dense, mixing high-level purpose with intricate algorithmic details. While front-loaded with purpose, it lacks clear structural breaks (e.g., sections or bullet points) and could be more concise without losing essential information.

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

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

Given the tool's complexity with 9 parameters, no output schema, and rich internal logic, the description thoroughly explains the response structure, edge computation, tradeable-edge knobs, diagnostics, and caching policy. It provides sufficient context for an agent to understand and correctly invoke the tool.

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

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

With 100% schema description coverage, the baseline is 3. The description adds further meaning for several parameters, such as the real-world slippage context for slippage_pp and the interplay between min_kelly and min_partition_leg_kelly. Some parameters like limit and window receive only restatement, so not a full 5.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the purpose as 'what should I bet on today' and distinguishes from other tools by focusing on edge discovery without paging hundreds of markets.

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

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

The description implies usage for discovering edge opportunities and provides context for when to apply parameters like min_liquidity and max_spread_pp. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, limiting guidance on when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds extensive behavioral detail: how tracked, expired, and snapshot_dates are computed, including trend classification, decay calculation, and limitations (60-day TTL, daily closes not intraday). 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 long but well-structured: it starts with purpose, then inputs, then detailed response format (tracked, expired, snapshot_dates), then limitations. Every sentence provides necessary information 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?

With no output schema, the description fully explains return values (fields in tracked, expired, snapshot_dates) and limitations. Parameters are completely documented. The agent has all needed information 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 covers 100% of parameters but with minimal descriptions. The description adds defaults (14 days, '1wk' window), clamp range (2-30), and explains the meaning of window as 'snapshot family'. This adds significant value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge duration and trend, distinguishing itself from sibling tools like polymarket_edges which likely provide only current edges.

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

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

The description provides clear context on when to use the tool ('Answers how long has this edge existed and is it shrinking?') and implies that a fresh wide edge vs an old wide edge are different trades. However, it does not explicitly name alternative tools for when only current edges are needed, though the purpose makes this implicit.

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, etc. The description adds significant behavioral context: returns verdict (clean|degraded|cannot_fill), per-leg fill details, thin legs, and warns about forced directional risk. 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 lengthy and dense, covering many details. It is structured with sections (SINGLE-MARKET, BASKET) but could be more concise. Some sentences are verbose (e.g., 'the dominant loss mode in real arb-bot P&L'). Still well-organized, but not maximally efficient.

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

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

Given no output schema, the description thoroughly documents return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains both modes. It covers risk warnings and usage context. Minor omission: error handling for invalid slugs/URLs is not described.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: explains the dual interpretation of size_usd (max spend vs target proceeds for single-market; settlement notional for basket), default side logic for basket, and parameter relationships. Provides concrete usage details.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to show differentiation.

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

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

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains the risk of partial fills converting arb into directional positions, helping the agent decide when to invoke 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?

The description richly discloses behaviors beyond the readOnlyHint/idempotentHint annotations: two modes, compatibility_codes semantics, never-pairing unknown metric_type/match_subtype legs, skipped_unclassified and low_confidence_pairs placement, and temporal_alignment field. It even instructs that 'BOTH can be non-empty on returned pairs, so read them even when matched_pairs>0.' No contradiction with annotations.

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

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

The description is long and dense, but it front-loads purpose, then modes, response, and safety fields in a logical order. Every sentence adds information relevant to correct invocation, though the wall of text could be tightened with bullet lists or shorter clauses.

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

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

With no output schema to lean on, the description carries full responsibility for return values and safety semantics, and it delivers: it names top_spreads_pp, compatibility_warning/codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and the skipped_cross_type/subtype counters. An agent has enough context to call the tool and interpret its results correctly.

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

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

Schema coverage is 100%, but the description adds real meaning: it defines the topic list, explains the two modes, and clarifies that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. This goes beyond the schema's per-field descriptions and tells an agent exactly how parameter combinations behave.

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 opening sentence states exactly what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific verb and resource, and the venue pair makes it clearly distinct from sibling Polymarket-only tools like polymarket_arbitrage or polymarket_edges, even without naming 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?

The description gives clear context on when to use the tool ('when the bet shapes are equivalent that delta is a real signal') and strongly qualifies expectations by warning that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning. However, it does not explicitly name alternative tools or state conditions to prefer them over this one.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by explaining the metric (lifetime watch counts) and the temporal scope (all-time, not current trending). 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 a single sentence that efficiently conveys the tool's purpose with common query phrases, no wasted words. Well-structured and front-loaded.

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

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

Given the presence of an output schema (mentioned in context), the description does not need to explain return values. It adequately covers usage intent and behavioral characteristics. Complete for a listing tool with strong annotations.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description does not add additional meaning beyond the schema; it merely rephrases the purpose. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool returns all-time popular movies or shows based on lifetime watch counts, distinguishing it from current trending. It provides specific aliases like 'most-watched ever' and 'classic movies/TV'.

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

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

Explicitly says 'Use for best of all time lists' and clarifies it's not current trending, giving context for when to use. Does not explicitly mention alternatives beyond trending, but sibling tools include 'trending' which is implied as the alternative.

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 nature. The description adds valuable context about scoping and pairing without contradicting annotations.

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

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

The description is concise (3 sentences), front-loaded with the primary action, and every sentence adds unique 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 1-parameter tool, the description fully explains behavior (retrieve value or list keys), scoping, and pairing. No output schema is needed given the clear explanation.

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 (1 optional key). The description adds meaning by explaining that omitting key lists all keys, which is not evident from the schema alone.

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 retrieves values saved via remember or lists all keys if omitted. It distinguishes itself from sibling tools remember and forget by explicitly mentioning the pairing.

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

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

The description explicitly tells when to use this tool ('look up context stored earlier') and notes the scoping to anonymous IP, BYO key hash, or account ID. It also advises pairing with remember to save and forget to delete.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: the effect of mark_read on future calls, that the feed is persisted, and that polling is acceptable. No contradictions, and it 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 a concise paragraph with three key sentences: what it does, what it returns, and how to filter/use it. Every sentence adds value, no repetition, and the purpose is front-loaded.

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

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

With no output schema, the description adequately covers return fields (source, citation_uri, payload) and behavioral details (mark_read, polling). It provides sufficient context for an agent to use the tool effectively, though a bit more on limit/unread_only could help.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The tool description adds value by explaining how parameters like type, since, and mark_read interact (e.g., filtering, flagging read). This goes beyond the schema's individual descriptions.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It specifies what the tool returns (source, citation_uri, raw payload) and distinguishes it from sibling tools like list_subscriptions and search 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 explains filtering by type and timestamp, the mark_read parameter behavior, and that polls work fine. It also mentions an alternative API endpoint (GET .../alerts.json) for scripts/dashboards, offering guidance on when to use this tool vs. direct access. No explicit when-not-to-use, but sufficient for most scenarios.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: parallel call, GDELT to GNews fallback on rate limits, and USPTO soft-fail. 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 paragraph that front-loads with examples and purpose, but it is somewhat lengthy and includes some redundancy (e.g., repetition of 'change feed' concept). Still efficient overall, but could be trimmed 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?

Given the tool's complexity (multiple sources, parameter options, fallback behavior) and absence of an output schema, the description covers all key aspects: return structure, source behavior, parameter formats, and alternative tool usage. It is sufficiently 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%, baseline 3. The description adds meaning by explaining `since` formats (ISO date or relative shorthand) and providing a usage hint ('30d' or '1m' for typical monitoring'), and clarifying `value` accepts ticker or CIK. This elevates 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 it provides a 'change feed for a company in the last N days/weeks/months' using specific verbs like 'fans out to SEC...' and 'Returns structured changes[]'. It explicitly distinguishes from the sibling tool `entity_profile`, making the purpose unambiguous.

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

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

The description gives multiple example queries ('What's new with X', 'latest on Y') and explicitly advises when to use the alternative: 'Use entity_profile instead when you want the static profile...'. This provides clear contextual guidance.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, and the description adds behavior beyond annotations, such as scoping by user identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. 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 well-structured sentences: first defines purpose, second explains when to use, third details storage scope. Efficient and front-loaded with no redundant information.

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

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

For a tool with only two required parameters and no output schema, the description fully covers purpose, usage, persistence, and lifecycle, making it complete for agent understanding.

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

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

Schema coverage is 100% with clear descriptions for both key and value. The description adds minimal extra context (key-value pair scoped by identifier), so baseline 3 is appropriate.

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

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

The description clearly states 'Save data the agent will need to reuse later' as a key-value pair, and explicitly distinguishes from sibling tools 'recall' and 'forget' by mentioning pairing with 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?

Explicitly tells when to use ('when you discover something worth carrying forward') and provides context on persistence scoping, though it does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: graceful degradation if GLEIF/OpenFIGI are unavailable, explicit labeling of sources, and the statement that unresolved identifiers appear under 'unresolved' rather than being omitted. It also discloses internal cascading lookups, giving the agent a realistic expectation of cost and behavior.

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

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

The description is long and dense but well-structured: front-loaded with examples and a 'Use FIRST' directive, followed by supported types and behavioral notes. Some redundancy exists (e.g., 'Use FIRST' appears twice), but the length is justified by the tool's complexity and multiple entity types. It remains easily scannable.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It details return contents for both company (CIK, ticker, company_name, LEI, FIGI, ownership, unresolved identifiers) and drug (RxCUI, ingredient, brand, citation), fallback behavior, and input variants. This equips the agent to understand results and decide when to use the tool.

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

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

The input schema already covers both parameters (type, value) with descriptions, giving 100% coverage. The description further enriches semantics by explaining how ISIN maps to legal entity via GLEIF, examples for ticker/CIK/name, and the drug type details (RxCUI, ingredient, brand). This goes well beyond the schema's basic field 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 resolves user-spoken names to canonical identifiers, with a specific verb ('resolve') and resource ('a user-spoken NAME to the canonical/official identifiers other tools require as input'). It distinguishes itself from siblings like search or entity_profile by emphasizing it produces IDs needed by other tools, and it provides concrete examples for multiple entity types.

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

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

Explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This directly tells the agent when to invoke the tool. It also mentions that it replaces 2-3 manual lookups, reinforcing its role. While it doesn't list exclusions, the 'FIRST' directive and specific supported types provide 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?

Description provides behavioral details beyond annotations: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, returns list with score/confidence/signal density. No contradiction with readOnlyHint or other annotations.

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

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

Four sentences, each essential: purpose, mechanism, use case, output. No redundant or vague language. Front-loaded with key action.

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

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

Given no output schema, description fully explains return values (ranked list with score, confidence, signal density per entity). Also explains process (probe each entity, compare). Sufficient for an agent to understand behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that first entity in entities is treated as subject and rest as competitors, adding meaning beyond schema. Also clarifies models options in context.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and returns a ranked list. It distinguishes from sibling ai_visibility_check which checks single entities. Specific verb 'compare' and resource 'AI presence' with clear output.

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 mentions use case for competitive AI-marketing audits and gives example question. Implicitly shows when to use (multiple entities) vs. single entity check, but does not explicitly state when not to use or list alternatives other than ai_visibility_check.

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 reveals it fans out to two external services, lists exact return fields, and explains graceful degradation with sources_failed. 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?

Description is informative but somewhat lengthy. Front-loaded with the core purpose, then details. Every sentence adds value, though slight trimming could improve conciseness.

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 enumerates all return fields (summary, per-advisory, links, alternatives) and covers partial failures. Complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters. Description repeats schema info (package name, version) without adding new semantics. Baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia. It distinguishes from siblings by specifying NPM ecosystem only and directing other ecosystems to deps.dev:version directly.

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 to use when an agent asks about safety, popularity, size, or cost of adding a package. Also covers partial failures and timeouts, giving clear context on when to expect degraded behavior.

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 as true. The description adds value by explaining that returned matches include Trakt IDs usable in get_movie/get_show. No contradictions.

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

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

Two concise sentences with front-loaded purpose. No unnecessary words.

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

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

With full schema coverage and an output schema, the description is mostly complete. It lacks mention of pagination or ordering, but those are covered in the schema.

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

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

Schema descriptions cover all 9 parameters (100% coverage). The description adds a summary of filter options but does not provide additional meaning beyond the schema.

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

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

The description clearly states the tool performs full-text search across multiple catalog types (movie, TV show, episode, person, list) and specifies output as ranked matches with Trakt IDs. This distinguishes it from siblings like 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?

The description implies the tool is for general catalog search but does not explicitly state when to use it vs alternatives (e.g., search_within, discover_tools) or when not to use it.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals the embedding model (BGE-base-en), window size (500-char overlapping), distance metric (cosine), and truncation policy (200K char cap with flag). This fully discloses behavior.

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

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

Two efficient sentences followed by a usage guideline and technical note. Every sentence serves a purpose, front-loaded with core function, then context, then 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 the moderate complexity (semantic search with specific algorithm and constraints), the description covers all essentials: input limits, output format (passages, offsets, scores), technical specs, and integration with sibling tools. 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 coverage is 100%, but the description adds value by clarifying that 'text' is the fetched record, providing query examples, and noting the limit default. It enriches understanding beyond schema descriptions.

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

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

The description clearly states the tool performs semantic search inside a record, specifying the inputs (text, query) and outputs (passages with offsets and scores). It distinguishes itself from similar tools like 'search' and 'ask_pipeworx_grounded' by explicitly mentioning its niche.

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

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

Provides explicit when-to-use: 'when the record is too big to cram into the prompt' and highlights context-saving benefit. Also mentions pairing with 'ask_pipeworx_grounded' as an alternative workflow.

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 (readOnlyHint: false, openWorldHint: true, idempotentHint: true, destructiveHint: false), the description adds rich behavioral details: account requirement, subscription id return, type-specific parameters, delivery channel constraints (SMS cap, webhook HMAC signing and auto-disable). This significantly enhances transparency.

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

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

The description is somewhat lengthy but well-structured with clear sections and examples. Every sentence adds value; no fluff. Slightly more conciseness could be achieved, but it 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 tool's complexity (multiple subscription types, delivery channels, no output schema), the description is remarkably complete. It covers all necessary behavioral and input aspects, including return value (new subscription id), making it fully actionable for an agent.

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

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

Although the input schema covers 100% of parameters with descriptions, the tool description adds substantial meaning by explaining each subscription type's parameters in context (e.g., 'sec_8k: {ticker, items}' and examples) and detailing delivery options with constraints. This exceeds the schema information.

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 title 'Subscribe to Alerts' and description 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' clearly state the tool's purpose. It uses a specific verb ('create') and resource ('subscription'), distinguishing it from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

The description specifies that a Pipeworx OAuth account is required, and that anonymous and BYO accounts cannot persist subscriptions. It details supported subscription types and delivery channels but does not explicitly contrast with alternative tools or state when not to use this tool. However, the context is clear enough given 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by explaining the output structure (category-bucketed questions with exact tool+argument shape) and the dynamic nature (drawn from live catalog). No contradictions.

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

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

The description is well-structured with trigger phrases and examples, though slightly long. It front-loads common user queries and provides clear usage instructions. 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 simplicity (0 required params, 1 optional), the description is comprehensive: covers purpose, usage, output, and related tools. No output schema is needed because the description explains what is returned.

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 for the single optional parameter 'topic' with a clear description and allowed values. The description adds context by explaining when to omit (full spread) and how to use the parameter to focus.

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

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

Clearly states the tool returns category-bucketed example questions for Pipeworx, with a specific verb (suggest) and resource (questions). Distinguishes from siblings like ask_pipeworx and discover_tools by describing its role as an onboarding entry point.

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 to use first when not knowing Pipeworx's capabilities or to learn meta-tools. Provides guidance on calling with no arguments or with a topic. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds context about the data source (Trakt) and ranking method (active watchers), which provides value beyond the annotations. No contradictions.

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

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

The description is concise and front-loaded with the purpose. It is a single effective sentence, though the use of quotes and slashes makes it slightly less clean. Every part is relevant.

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 existence of an output schema, the description adequately covers the tool's purpose, data source, and ranking. It could mention pagination or result format, but these are covered by the schema. Overall sufficient.

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

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

Schema coverage is 100%, so the description adds little beyond what the schema already provides. It reiterates the type parameter but does not offer additional semantic meaning for the parameters.

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

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

The description clearly states it returns currently-trending movies or shows ranked by active watchers, using specific verb and resource. However, it does not explicitly distinguish from sibling tools like 'popular' or 'pipeworx_trending', which may also provide trending content.

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

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

The description provides clear context for using the tool: pass type='movies' or 'shows', and use for 'what should I watch' recommendations. It does not, however, include when not to use it or mention alternatives.

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

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

Discloses ownership enforcement, deactivation behavior, and historical data availability. Adds value beyond annotations; no contradictions.

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

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

Two concise sentences with front-loaded purpose. No unnecessary words.

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

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

Complete for a single-parameter tool with good annotations. Covers purpose, ownership, and data impact.

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 parameter fully; description adds relational context ('returned by subscribe'). Provides meaningful additional information.

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

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

Clear verb ('cancel') and resource ('subscription'). Explicitly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement and effect (deactivation, not deletion). No explicit when-not-to-use or alternatives, but sufficient context for proper use.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses the two-pipeline behavior, the verdict types, and crucially explains that could_not_verify means the check did not happen and must not be shown as evidence. This is critical behavioral nuance not inferable from annotations. No contradiction.

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

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

The description is lengthy but densely informative, with a clear structure: examples, when-to-use, routing logic, return details, and caveats. Each sentence contributes essential information, though it could be tightened for brevity.

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

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

With no output schema, the description compensates by detailing the verdict enum, the presence of a pipeworx:// citation, and the error semantics of could_not_verify/unsupported. It also explains the two processing paths for different claim types, making it sufficiently complete for a complex tool.

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

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

Both parameters have schema descriptions (100% coverage), but the description adds more: tolerance_pct overrides the tolerance implied by the claim wording, with a default capped at 5 and a recommendation to set 1–2 for hallucination detection. Claim gets example formats. This adds meaningful guidance 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 this tool verifies natural-language factual claims against authoritative sources, with explicit example phrasings ('fact check', 'verify the claim that…'). It distinguishes itself from sibling search/ask tools by focusing on claim verification and by mentioning it replaces multiple sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for company-financial vs other claims. It also notes the tolerance_pct usage for hallucination detection. It doesn't explicitly name alternative tools to avoid, but the when-to-use is clear.

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