Setlist Fm

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description confirms it's a read operation and adds context: scoring per model, the need for BYO API key for Anthropic, and that calls are passed through. No contradictions.

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

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

The description is concise and well-structured, covering purpose, usage, parameters, and return format in a few sentences. It could be slightly more streamlined but is efficient.

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

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

Despite lacking an output schema, the description lists return fields: per-model {score, confidence, signals, raw_response} + combined view. It explains the scoring range and default behavior, making it fairly complete for an agent to understand.

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

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

With 100% schema coverage, the description still adds value by explaining the default model for 'models', that '_apiKey' is only needed for anthropic, and that 'context' helps disambiguate. This goes beyond the schema's simple descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility 0-100. It specifies the verb 'probe', the resource 'LLMs', and the output 'visibility score'. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on individual entity probing.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains the default model and the optional Anthropic model with API key requirement. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already inform the agent of safe, deterministic behavior. The description adds value by listing the returned fields (name, MBID, Ticketmaster ID, etc.), which is beyond what annotations alone provide. No contradictions.

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

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose and output. No wasted words.

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

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

For a simple one-parameter tool with an output schema present, the description is complete. It specifies the input (mbid) and the output fields, leaving no ambiguity about what the tool does.

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

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

The single parameter 'mbid' has 0% schema description coverage. The description explicitly explains that it is a MusicBrainz ID, adding crucial meaning beyond the bare 'string' type in the schema.

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

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

The description clearly states the action ('Fetch'), the resource ('artist record'), and the method ('by MusicBrainz ID'). It lists specific return fields, distinguishing it from sibling tools like artist_search and artist_setlists.

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 when one has an MBID, but does not explicitly state when to use this tool versus alternatives like artist_search. No when-not-to-use or alternative references 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 declare readOnlyHint=true and idempotentHint=true, so the tool's safe, side-effect-free nature is established. The description adds value by specifying that results are paginated and listing return fields (name, MBID, sort name), which goes beyond annotations. No destructive behavior is implied.

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

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

The description is two sentences with no extraneous information. It front-loads the action and purpose, then lists what the tool returns. Every word contributes to understanding.

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

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

The description adequately covers search criteria and return fields for a search tool with an output schema. It mentions pagination, which is important. However, it does not explain optionality of all parameters even though the schema shows none required, and omits potential constraints like rate limits or external API dependence. Still, it is largely complete for a straightforward search 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 has 0% description coverage, so the description must compensate. It explains that artistName, artistMbid, and artistTmid are search criteria, covering three of five parameters. However, 'p' and 'sort' are not explained beyond examples in the schema, leaving some ambiguity. The description adds partial meaning but is not comprehensive.

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

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

The description clearly states the tool searches for artists by specific identifiers (name, MusicBrainz ID, Ticketmaster ID) and returns a paginated list with name, MBID, and sort name. This clearly distinguishes it from siblings like 'artist' (which likely retrieves a single artist) and 'artist_setlists' (which deals with setlists).

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 use for searching artists but provides no explicit guidance on when to use this tool versus alternatives like 'artist' or 'setlist_search'. No when-not or context for exclusion is given, leaving the agent to infer usage from the description.

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 openWorldHint, so the agent knows the operation is safe and idempotent. The description adds behavioral context by stating it returns paginated results with date, venue, city, and track lists. This goes beyond annotations, clarifying output structure and pagination 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 two sentences long with no redundancy. It front-loads the core purpose and concisely lists key return fields. Every word contributes value, making it efficient for an agent to parse.

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

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

Given the tool has 2 parameters (one required) and an output schema exists, the description is mostly adequate but lacks explicit parameter documentation (especially for 'p'). It covers the essential what and how, but the missing parameter detail prevents full self-containment. With schema coverage at 0%, more parameter context would raise the score.

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

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

Schema description coverage is 0%, so the description must explain parameters. It mentions 'mbid' as MusicBrainz ID but does not describe the 'p' parameter (page number). The word 'paginated' implies 'p' is a page indicator, but it is not explicitly defined. Additional detail about the required mbid format or p's range would improve clarity.

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

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

The description clearly states the tool fetches paginated setlists for a specific artist using a MusicBrainz ID. This verb+resource combination ('Fetch paginated setlists') with the specific identifier ('artist identified by MusicBrainz ID') distinguishes it from sibling tools like 'setlist_search' or 'venue_setlists', which operate on different entities or criteria.

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

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

No usage guidelines are provided. The description does not specify when to use this tool over alternatives like 'setlist_search' or 'artist', nor does it mention any constraints or preconditions. The tool's purpose is clear, but an agent lacks guidance on tool selection.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. The description adds that it routes to one of 4,774 tools, returns structured answers with stable citation URIs, and is 'one fast call'. No contradiction with annotations.

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

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

The description is long but well-structured, front-loaded with purpose and usage guidelines. Each sentence provides value, though some redundancy exists (e.g., multiple examples).

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

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

Given the tool's complexity, many sibling tools, and no output schema, the description is remarkably complete. It covers purpose, usage, behavioral traits, examples, and alternatives comprehensively.

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

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

Schema coverage is 100%, so the schema already documents the parameter and its aliases. The description adds context about the types of questions to ask but does not add significant new semantics beyond the schema.

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

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

The description clearly states the tool's purpose: answering factual questions about real-world entities, events, or numbers using structured data, with a preference over web search. It lists specific domains (SEC filings, FDA data, etc.) and contrasts with sibling tools.

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

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

Explicit guidance: 'START HERE for most questions' and step up to ask_pipeworx_grounded or deep_research when appropriate. Provides examples and contexts where this tool should be used, and distinguishes from siblings.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: costs one extra LLM call, returns explicit refusal reasons, and extracts answer only from tool result. No contradiction with annotations.

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

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

Description is slightly long but well-structured, front-loaded with key purpose, then details. Each sentence adds value (usage guidance, cost, return format). Not overly verbose.

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

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

Given high complexity (routing across 4,774 tools, refusal reasons, cost warning), the description covers all critical aspects: input, process, output format with explicit refusal reasons, and usage guidance. No output schema but return values are detailed.

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

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

Schema has 100% coverage with 6 parameters (all aliases for question). Description mentions 'Your question in natural language' but adds little beyond 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 explains the process: picks the right tool, fetches data, extracts answer using only tool result. It distinguishes from sibling 'ask_pipeworx' by specifying the grounded mode vs regular.

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

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

Explicitly states when to use: 'when an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial verdicts, legal claims, medical lookups, public statements). Also states when not to use: 'prefer ask_pipeworx for casual lookups', providing clear context and alternatives.

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

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

Description fully discloses tool behavior: fan-out to category-specific data packs, response shapes, resolver contract, parent event extraction, news fields with fallback handling, safety mechanisms (low-confidence short-circuit, closed markets, wide-spread warning), and resolution-rule risk. Annotations already mark it read-only/idempotent, and description adds extensive context without contradiction.

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

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

Very long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Front-loaded with purpose and usage. Could be slightly more concise by trimming some fan-out examples, but the density is warranted given 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?

No output schema, so description carries full burden. It thoroughly explains all return fields: market details, analysis including edge and 24h-move warning, evidence source keys, resolver contract with confidence levels, parent event info, news fields with fallback, and safety statuses. Covers all aspects for a 3-parameter tool.

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

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

Schema coverage is 100%, but description adds significant value: explains market input formats (slug, URL, question), depth enum (quick vs thorough and their effects), include_raw default and when to use. Examples in schema further clarify usage.

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

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

Description clearly states it researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question), actions (resolve, classify, fan-out, return evidence), and provides multiple examples. It distinguishes itself from sibling tools like polymarket_edges by focusing on comprehensive research for a single bet.

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

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

Explicitly states when to use: 'for should I bet on X, what does the data say about Y, or is there edge in Z'. Also covers safety, resolution-rule risk, and how to interpret results. Provides clear guidance on when not to trust analysis (low-confidence match).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns city name, state, country, and geolocation coordinates, providing useful behavioral context 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 with two sentences, front-loading the purpose and adding a practical usage note. 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?

An output schema exists, so return structure is covered elsewhere. However, the description fails to explain the 'p' parameter, and does not state that all parameters are optional. For a search tool with 3 parameters, this is incomplete.

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

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

The input schema has 3 parameters (p, name, country) with 0% description coverage. The description explains 'name' and 'country' as search criteria but does not mention 'p' (likely page number), leaving its purpose unclear. This is a significant gap given the low schema coverage.

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

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

The description clearly states the tool searches setlist.fm for cities by name or country, differentiating it from sibling search tools like artist_search or venue_search. It also mentions the usefulness for resolving city identifiers before further searches.

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

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

The description indicates when to use (for resolving city identifiers before searching setlists or venues) but does not explicitly state when not to use or provide alternatives. The context is clear enough for an agent to infer appropriate 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, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 informative but slightly long. It front-loads with typical user queries and is well-structured, but could be tightened without losing content.

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 covers behavior, data sources, sorting, and return format (paired data + URIs). All necessary context is provided for effective use.

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

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

Schema coverage is 100% but the description adds meaning: it explains the expected input format (tickers/CIKs for companies, drug names) and gives examples. This goes beyond the schema's description.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific examples like 'X vs Y'. It distinguishes itself from sequential lookups and sibling tools by being a dedicated comparison tool.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. It also explains the two entity types and what data each pulls.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and idempotency. The description adds that it returns 'the full list of countries,' which is consistent with the annotations and provides basic 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 a single, well-structured sentence that front-loads the purpose ('Return the full list...') and adds usage guidance. No extraneous words.

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

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

Given the tool has no parameters, an output schema exists (though not shown), and the annotations provide safety guarantees, the description is complete. It tells the agent what the tool returns and why to use it, which is sufficient for a simple data retrieval 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 tool has zero parameters, so the description has no parameter details to add. The schema coverage is trivially 100%, and the description's mention of returning a full list of countries adds meaning beyond the schema, which only defines an empty object. The agent understands no input is needed.

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

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

The description clearly states the tool returns the full list of countries with ISO codes and names, specifying the resource (countries) and the verb (return). It distinguishes itself from sibling tools by indicating its use for looking up valid country codes before filtering setlist or venue searches.

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

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

The description provides explicit guidance: 'Use to look up valid country codes before filtering setlist or venue searches.' This tells the agent when to use it, though it does not explicitly mention when not to use it. However, for a simple lookup tool, this is sufficient.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), description adds account requirements, paid plan info, data sources count, parallel processing, output format (findings with citations, gaps), expected latency (15-60s), and limitation on current news. No contradiction with annotations.

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

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

Description is long but well-structured with clear paragraphs, warnings upfront, and no redundant sentences. Information is front-loaded (account requirement, alternative). Could be slightly trimmed but efficiently packs essential 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 complexity (parallel research across 1242 sources, 4774 tools, no output schema), description covers input requirements, process details, output format, limitations, alternatives, and authentication. No gaps for AI agent to successfully invoke 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 are documented in input schema. Description adds extra meaning: depth enum is explained (quick=3, standard=5, thorough=8) with paid plan qualifier, and question is described as 'natural language' and 'broad/multi-part is fine'. This provides valuable context beyond schema.

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

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

The description clearly states 'Grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources' and explains decomposition into facets and output format. It distinguishes from sibling ask_pipeworx by noting this is for broad/multi-part questions over structured data, not single lookups or current news.

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

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

Explicitly provides when-to-use ('broad/multi-part questions over structured data') and when-not-to-use ('BREAKING or colloquial CURRENT-NEWS', 'single lookup') with specific alternative (ask_pipeworx). Also mentions account requirement and that 'thorough' depth needs paid plan.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: returns the top-N most relevant tools with full schemas, ready to call directly with no second lookup. This explains the result format and process, going 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?

The description is approximately 100 words, front-loading the core purpose, then listing domains, explaining the return value, and giving usage guidance. Every sentence serves a clear function with no redundancy or 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?

Despite having no output schema, the description fully explains what is returned: top-N tools with names, descriptions, and full schemas, ready to call directly. It covers the input parameters' aliases and examples. The tool has 6 params (all with schema descriptions) and no nested objects or enums, and the description addresses the key aspects completely.

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 6 parameters. The description adds value by summarizing that the main parameter accepts natural language descriptions and includes examples. It also explicitly mentions that 'task, q, description, search' are aliases for query, which consolidates the schema's information into a clearer statement. The baseline is 3, but the aggregation and examples raise it to 4.

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

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

The description starts with 'Find tools by describing the data or task,' which precisely states the verb and resource. It lists many specific domains (SEC filings, FDA, etc.) and distinguishes itself from sibling tools by stating 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by a list of domains. It further advises 'Call this FIRST...' which gives clear context for usage. It does not explicitly state when not to use, but the guidance is strong.

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, openWorldHint, etc.), description details data sources (SEC, XBRL, USPTO, news, GLEIF), return fields (cik, filings with URIs, fundamentals, patents, news, LEI), and potential failure mode (USPTO sunset with soft-fail). No contradiction with annotations.

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

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

Description is relatively long but every sentence adds value. Front-loaded with examples and purpose. Slightly verbose but justified given tool complexity. Could be slightly more concise.

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

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

No output schema, but description thoroughly explains all returned fields, data sources, parameter constraints, and failure modes. Complete and sufficient for agent to understand tool behavior and response format.

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

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

Schema has 100% coverage with descriptions. Description adds context: value accepts ticker or zero-padded CIK, not names; type is only 'company'. Provides additional format guidance and alternatives for unresolved names.

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

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

Description clearly states it provides a 'full cross-source profile of a US public company' with specific example queries. It distinguishes from siblings like 'resolve_entity' and 'compare_entities' by explicitly mentioning when to use alternative 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 ('holistic view') and when-not-to-use ('names not supported, use resolve_entity first'). Also advocates preferring this tool over chaining single-source lookups.

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

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

Annotations already indicate destructiveHint=true, and the description confirms the destructive action ('Delete'). It adds context about clearing sensitive data, which enhances transparency beyond the annotation alone.

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 only: the first states the core purpose, the second provides usage guidance. No wasted words, and the critical information is front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description fully covers its purpose, usage context, and relationship to 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?

The input schema already fully describes the single parameter 'key' (100% coverage). The description only reiterates 'by key' without adding new semantic detail, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory', with the qualifier 'by key'. It also mentions companion tools 'remember' and 'recall', helping distinguish it from similar 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?

Explicitly states when to use ('context is stale, the task is done, or you want to clear sensitive data') and mentions related tools ('Pair with remember and recall'), providing clear context for selection.

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

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

Annotations already declare safe, idempotent, read-only behavior. Description adds concrete steps (fetches, extracts, emits) and output format, enhancing transparency 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?

Four sentences with no waste. First sentence captures core action. Subsequent sentences provide context and output format. 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 simple tool with rich annotations and complete schema, description covers all needed information: purpose, process, output, and use cases. No gaps.

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

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

Schema coverage is 100% with clear descriptions. Description doesn't add new parameter details, but reiterates the url purpose. Minimal added value beyond schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific actions (fetch, extract, emit). It distinguishes itself from siblings by being a focused utility for AI crawler indexing, unlike other tools that cover different domains.

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

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

Provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. No explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile well. The description adds value by specifying the exact fields returned and the default behavior of only returning active subscriptions, which is not explicitly in the 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 two sentences: the first clearly states purpose and output, the second gives usage guidance. Every sentence adds value with no redundancy or fluff.

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

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

The tool is simple with one optional parameter and no output schema. The description covers purpose, return fields, and usage context. It could mention that the subscriptions are for the caller (already in description), but overall it is complete enough for an agent to use correctly. Missing details like ordering or limits are not critical 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%, and the schema already describes the 'include_inactive' parameter with its meaning and default. The description does not add any additional detail about the parameter, so it meets the baseline but does not exceed it.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), and explicitly lists the return fields (id, type, params, created_at, etc.). It distinguishes the tool from siblings like 'subscribe' and 'unsubscribe' by clarifying it's for reviewing, not adding or removing 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 explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implies when not to use it (for subscribing/unsubscribing).

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 rate limits (5 per identifier per day) and that the tool does not count against tool-call quota. Annotations are all false, so no contradiction. The description adds useful behavioral context beyond annotations.

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

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

The description is a single focused paragraph of about 6 sentences. It is front-loaded with the main purpose, and each sentence adds value. No redundant or unnecessary information.

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

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

For a simple feedback tool with no output schema and neutral annotations, the description thoroughly covers purpose, usage scenarios, content guidelines, rate limits, and quota impact. It is complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant extra meaning to parameters beyond the detailed schema descriptions for 'type' (enum with explanations) and 'message' (plain text). The 'context' parameter is well-described in schema.

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

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

The description explicitly states the tool sends feedback to the Pipeworx team, listing specific categories (bug, feature, data_gap, praise) with clear definitions. It distinguishes from sibling tools, which are all data retrieval or analysis tools, not for feedback.

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

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

The description provides explicit guidance on when to use the tool, including specific scenarios for each feedback type. It also advises on what to include (tool/pack context) and what to avoid (end-user prompts), and notes rate limits and quota implications.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, and caching duration (5min-1h depending on window). This exceeds what annotations provide.

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

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

The description is a single paragraph but well-organized, starting with the main result. It is concise with no wasted words. Could be slightly improved by structuring into bullet points or sections, but it is clear and efficient.

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

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

The description mentions the output includes 'top tools, top packs, and total call volume' but does not specify the format (e.g., JSON, list) or structure. For a tool with no output schema, this is a gap. The caching and privacy details are good, but the return format is 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% with a description for the window parameter. The description adds further semantics by explaining the effect of each enum value ('Shorter windows surface what's hot right now; longer windows show steady-state demand.'), which aids parameter selection.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It specifies the verb 'returns' and the resource 'what's trending on Pipeworx'. The three use cases further clarify its purpose and distinguish it from sibling tools.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, aligning with trends). Caching behavior is also mentioned. However, no explicit 'when not to use' guidance or comparison to alternative sibling tools is given, which 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 annotations (readOnly, openWorld, idempotent), the description discloses detailed behavioral traits: monotonicity checks, partition_sum logic, Jaccard similarity threshold, placeholder filtering, and fill check against live CLOB depth. It even warns when not to trade ('realizable_edge_pp ≤ 0 means... not in the book; do not trade it'). 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 long but well-structured, with each sentence adding value. It front-loads the main purpose and uses clear separators (e.g., 'SEMANTIC ANCHOR:', 'PARTITION FILTER:', 'FILL CHECK:'). While efficient, it could be slightly tighter to improve scannability.

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 provides a thorough explanation of the response structure, including fields like `gap_pp`, `suggested_trade`, and partition check details. It also covers edge cases (placeholder filtering, low similarity) and integrates with sibling tools. No significant 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?

While the input schema provides basic descriptions for `event` and `topic`, the description adds rich meaning: for `event` it explains child market walking and partition checks; for `topic` it describes cross-event scanning and flattening. It also details the behavior with no arguments (trending_scan). This goes far 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 function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It includes specific verbs and resources, and distinguishes between three modes (trending_scan, event, topic), making it easy for an agent to understand the core purpose.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It recommends event mode for specific markets and explains when cross-event is better. It also mentions a sibling tool for custom sizing, offering clear alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds extensive behavioral context: caching strategy, model families (e.g., lognormal barrier, GDELT ratio), output structure with diagnostics, and edge calculation details (slippage, Kelly caps). 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 detailed and well-structured with sections for model families, but it is verbose and dense. The key purpose is front-loaded, but the wall of text may overwhelm an agent. Every sentence adds value, but conciseness is sacrificed for completeness.

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

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

Given the complexity (9 parameters, no output schema, rich behavioral details), the description is highly complete. It explains the output structure (by_segment, diagnostics), why segments may be empty, caching, and edge calculations. It covers all necessary context for effective use.

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

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

All 9 parameters are described in the schema (100% coverage). However, the description enriches understanding with extra context, such as the role of min_partition_leg_kelly in filtering partitions and the tradeable-edge knobs. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself by avoiding paging through hundreds of markets, differentiating it from siblings like polymarket_arbitrage or polymarket_kalshi_spread.

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

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

The description provides clear usage context, noting it is designed for daily betting discovery and that Fed bets are excluded with explanation. It does not explicitly compare with sibling tools but offers enough context for agents to decide. The caveat about Fed data reliability adds valuable 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, idempotentHint, true, and destructiveHint false. The description adds that it reads from snapshots with a 60-day TTL, decay is computed from daily closes (not intraday), and gaps in snapshot_dates indicate no data. No contradiction with annotations.

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

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

The description is well-structured: starts with purpose, then explains response fields (tracked, expired, snapshot_dates), and ends with limits. It is dense but lacks redundancy. Could be slightly more concise, but overall effective.

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

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

Despite no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) with field details. It also covers limitations (TTL, decay computation). Very complete for a tool with simple parameters.

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

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

Schema descriptions already cover both parameters (days, window) with defaults and limits. The description adds context: 'snapshot family' for window and 'lookback' for days, reinforcing usage. With 100% schema coverage, baseline is 3, and description adds extra 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 clearly states the tool provides 'edge persistence and decay telemetry' and specifically answers 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges (which provides snapshots) by focusing on time-series analysis.

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 that this tool is for understanding edge longevity ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying when to use it. It does not explicitly state alternatives to avoid, but the context is clear.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description consistently adds behavioral context: it walks the order-book ladder, returns verdicts (clean/degraded/cannot_fill), and warns about risks like stranded positions. No contradiction with annotations.

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

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

The description is well-structured: front-loaded with core purpose and required parameter choice, then breaks down each mode with input/output details, and concludes with when to use. Every sentence provides necessary context; no redundancy. While lengthy, the complexity warrants it.

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 comprehensively covers all expected return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also explains edge cases and risks, making it fully informative.

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

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

Schema coverage is 100%, so baseline 3. The description adds rich semantics: explains the side parameter's behavior per mode, the meaning of size_usd in both modes (spend/target proceeds for single-market, settlement notional for basket), defaults, and constraints (clamp 10–1,000,000). This goes well beyond the schema 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's purpose as a 'realizable-vs-theoretical edge check' against live order-book depth. It distinguishes between single-market and basket modes with explicit verbs and resources, and differentiates from siblings polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on their signals.

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

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

The description provides explicit when-to-use guidance: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or any polymarket_edges trade above ~$500. It explains why (theoretical overround not capturable on thin books, partial fills convert arb to unhedged position) and how (choose market or event parameter).

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

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

Annotations (readOnlyHint: true, openWorldHint: true, idempotentHint: true) are already present. The description significantly expands transparency by explaining when the tool returns meaningful vs. meaningless spreads (via compatibility_warning and temporal_alignment), how skipped leg-pair comparisons are categorized, and the rarity of actual tradeable spreads. 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 thorough and uses formatting (bold, bullet-like structure) to break down complex information. It front-loads the core purpose and then details modes, response fields, and safety warnings. While lengthy, each sentence contributes essential clarity for a nuanced tool. Could be slightly trimmed, 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?

Given the tool's complexity (cross-venue, compatibility checks, temporal alignment) and lack of output schema, the description provides sufficient context: it explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and the meaning of counters. It equips the agent to interpret both success and warning 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?

Input schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the two operational modes (topic vs. explicit tickers) and providing examples, which helps the agent understand how to combine parameters. This goes beyond the schema's basic descriptions.

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

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

The description clearly defines the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two-venue comparison. The two explicit modes (topic shorthand and custom pairings) further clarify its specific functionality.

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

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

The description explains when to use the tool (comparing pricing across venues for the same question) and provides two modes of invocation. It warns that pre-mapped topics often yield non-tradeable spreads due to compatibility issues, guiding users away from false expectations. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage, though the differences are 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=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about scoping (anonymous IP, BYO key hash, account ID) 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 two sentences long, front-loaded with the core action, and every sentence provides essential 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?

For a simple tool with one optional parameter and no output schema, the description covers all needed context: action, scoping, usage scenario, and relationship to sibling tools. It is fully 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?

With 100% schema coverage, the description adds significant meaning: it clarifies that omitting 'key' lists all saved keys, and ties the parameter to the 'remember' tool. This goes well beyond the schema's basic description.

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

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

The description clearly states the verb ('retrieve' or 'list'), the resource ('value previously saved via remember' or 'all saved keys'), and distinguishes from siblings like 'remember' and 'forget'. It also provides concrete examples of use cases.

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

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

The description explains when to use the tool ('look up context the agent stored earlier') and mentions scoping and pairing with other tools. It does not explicitly state when not to use it, but the sibling names make the context clear.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description details a state-modifying effect via mark_read: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This directly contradicts the annotations, making the description misleading.

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, front-loaded with the core purpose, and structured logically: purpose, return fields, filter options, side effect, alternative access. Every sentence adds meaningful 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?

Given the tool has 5 optional parameters and no output schema, the description covers the core behavior (alert retrieval, filtering, mark_read side effect) and mentions the return format. It is missing explicit ordering and error handling, but overall it is fairly complete for a read-oriented feed 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, so baseline is 3. The description adds value beyond schema by providing examples (e.g., 'sec_8k' for type), explaining the effect of mark_read, and contextualizing parameters like since as an ISO timestamp and limit's range and default.

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 pulls fired events from the subscription feed, names the return fields (source, citation_uri, payload), and mentions filtering by type and timestamp. It distinguishes itself from siblings like list_subscriptions by focusing on event alerts, not subscription management.

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 suggests polling is fine and points to an HTTP endpoint as an alternative for scripts/dashboards, giving clear context. However, it does not explicitly exclude other tools or scenarios 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?

The description discloses rich behavioral details: fans out to multiple sources (SEC, GDELT, GNews, USPTO), fallback logic (GDELT preferred, GNews on rate limit), soft-fail for patents, parallel execution, and return structure (grouped changes, total count, citation URIs). This adds significant value beyond the annotations, which only indicate read-only, idempotent, and non-destructive behavior.

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

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

The description is well-structured, starting with example queries, then explaining core functionality, sources, parameters, return format, and alternative. It is somewhat verbose but every sentence adds value. Minor tightening could improve, but it is clear 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 tool's complexity (multi-source parallel fetch, fallback logic, no output schema), the description is comprehensive. It explains the output format, handles edge cases like soft-fail, and provides an alternative tool. It leaves no major gaps.

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

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

The input schema already provides good parameter descriptions (100% coverage). The description adds useful context: examples of relative shorthand for 'since', typical monitoring value, and explanation of how the tool uses parameters to fan out across sources. This goes 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 provides a change feed for a company in a given time window, covering filings, news, and patents. It gives multiple example queries and explicitly distinguishes itself from the sibling 'entity_profile' tool for static profiles.

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

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

The description provides explicit when-to-use guidance with example queries and directly mentions an alternative tool: 'Use entity_profile instead when you want the static profile...' It does not explicitly state when not to use, but the alternative is clear.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. Description adds persistence details (24h for anonymous, permanent for authenticated) and scoping by identifier. Could explicitly note overwrite behavior for same key.

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

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

Single paragraph, front-loaded with purpose, then usage guidelines, then technical details. Every sentence adds value with no redundancy.

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

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

No output schema, but the description covers purpose, usage, parameters, storage semantics, scope, and pairing with siblings. Sufficient for a simple key-value store.

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 extra meaning. It provides example keys like 'subject_property' in the description, which aligns with 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 the tool saves data for reuse across conversations/sessions, with specific examples like tickers and preferences. It distinguishes from siblings recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and mentions pairing with recall and forget. Also covers scope differences for authenticated vs anonymous users.

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

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

Annotations already provide safety hints (readOnly, idempotent). Description adds that each call cascades through several lookup endpoints, replacing 2-3 manual lookups. No contradiction with annotations.

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

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

Description is concise (6 sentences), front-loaded with examples and usage instruction. Every sentence provides 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?

Despite no output schema, description explains return format for both entity types and covers purpose, usage, and input details. Lacks explicit error handling or edge case notes, but sufficient for this straightforward tool.

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

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

Schema coverage is 100%, but description adds substantial meaning: for 'company' it details return fields (ticker, CIK, company_name, citation URI); for 'drug' it details RxCUI, ingredient, brand, citation. Also explains that 'value' for company can be ticker, CIK, or name, auto-disambiguated.

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 resolves names to canonical identifiers, gives example queries ('What's the ticker for...'), and explicitly says to use it when you have a name but need an ID. It distinguishes from sibling tools by specifying its role.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and lists supported types. Implies when not to use (already have an ID). Could be improved with explicit exclusions.

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

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

Annotations already indicate idempotent, read-only, and non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a structured result. It also highlights the optional Anthropic API key requirement, adding 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 three sentences, front-loaded with the core action, followed by details and a use case. Every sentence is informative and there is no redundancy or unnecessary text.

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

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

Despite no output schema, the description specifies the return structure (ranked list with score, confidence, signal density). It explains the mechanism and includes entity limits. This is complete for a batch comparison 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 description coverage is 100%, so baseline is 3. The description adds value by explaining the first entity as subject and the rest as competitors, which is not in the schema. This provides additional semantic meaning.

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

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

The description clearly states the tool compares AI visibility across multiple entities, uses ai_visibility_check, ranks results, and surfaces insights. It distinguishes from the sibling ai_visibility_check by explicitly mentioning batch comparison and competitive audits.

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

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

The description provides a concrete use case and example question, implying when to use the tool. It mentions the entity range (2-8) in schema but does not explicitly contrast with single-entity checks, though the sibling context makes it clear.

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

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

Annotations already mark it as readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral details: partial failure degradation, bundlephobia first-measurement delay (5-30s), and graceful handling of timeouts (sources_failed listed). 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 moderately long but well-structured: front-loaded with core purpose, then details. Every sentence adds value (scope, behavior, fallback). Slight verbosity but appropriate given 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?

Despite no output schema, the description explains the return structure (summary block, per-advisory detail, links, alternative versions) and covers error behavior and timing. For a composite tool with 2 params and no output schema, this is fully complete.

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

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

Schema coverage is 100% (both parameters described). The description adds meaning beyond schema: scoped packages are accepted, version defaults to latest. This provides useful context not in the schema.

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

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

The description clearly states the tool's composite purpose: a single call to evaluate an npm package across deps.dev and bundlephobia. It specifies the audience (agents answering 'is X safe/popular/small') and distinguishes from siblings by focusing on npm packages, while noting that other ecosystems are handled elsewhere.

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

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

Explicit usage context: 'Use whenever an agent asks...' and 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly tells when to use and when not, with direct alternatives.

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

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

Annotations already declare safe, idempotent, non-destructive. Description adds beyond: truncation at 200K chars with flag, embedding details, windowing. 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?

Three sentences, front-loaded with purpose. Every sentence earned: purpose, usage context, technical details. No fluff.

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

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

Covers return format (passages, offsets, scores) despite no output schema. Includes limitations and pairing with sibling. Complete for 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%. Description adds natural-language examples for query and clarifies default limit and max chars. Adds value beyond schema, but some repetition of schema description.

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

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

Clearly states it performs semantic search inside a fetched record. Uses specific verb 'search within' and resource 'source'. Distinguished from siblings like ask_pipeworx_grounded and other search tools by focusing on internal document search.

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

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

Explicitly tells when to use: when record is too large for prompt. Provides clear alternative: pairs with ask_pipeworx_grounded for grounding. No ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context by detailing the returned fields (artist, event date, venue, city, full track list) and the source (setlist.fm). There is 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 action, resource, and return values. It is front-loaded with the key information and contains no extraneous words.

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

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

Given the tool's simplicity (one parameter, read-only) and the presence of an output schema, the description provides sufficient context. It lists the high-level fields returned, which is complete for an agent to understand the tool's capability.

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

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

The schema has 0% coverage, but the description identifies the parameter as 'setlist.fm setlist_id' and provides an example in the schema. This adds meaning beyond the empty schema, clarifying the format and purpose of the single required parameter.

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

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

The description clearly states the action ('Fetch a single setlist') and the resource ('by its setlist.fm setlist_id'), listing the specific fields returned. It distinguishes itself from siblings like 'setlist_search' (which searches) and 'artist_setlists' (which fetches by artist), 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 implies usage when you have a known setlist_id. The sibling tools provide context for alternatives, but the description does not explicitly state when not to use this tool or name specific alternatives. Still, the context is clear enough for an agent.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: returns paginated results with artist, venue, date, and tracks. This goes 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 sentences: first states purpose and search parameters, second describes output. No wasted words; front-loaded with key action 'Search setlist.fm setlists.'

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 13 optional parameters and a rich output schema, the description covers main search dimensions and return fields. It could mention default behavior when no parameters are provided (e.g., returns nothing) but is otherwise sufficient for a search 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 description coverage is 0%, so description must compensate. It lists several search criteria (artist name/MBID, date, year, city, etc.) but does not cover all 13 properties (e.g., p, cityId, venueName). The examples in the schema partially fill gaps, but the description adds meaningful clarification without being exhaustive.

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

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

The description clearly states it searches setlists from setlist.fm, lists multiple search criteria, and mentions pagination and return fields. It effectively distinguishes from sibling tools like artist_setlists or venue_setlists by indicating a general search interface.

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 enumerates search parameters but does not provide explicit guidance on when to use this tool versus alternatives (e.g., using artist_setlists for a specific artist). It implies usage through context but lacks exclusions or best practices.

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

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

Adds significant behavior beyond annotations: returns subscription id, details delivery channels (SMS 10/day cap, webhook auto-disable after 10 failures, signing secret). Annotations indicate idempotent and non-destructive; description confirms safe creation.

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?

Packed with details but well-structured. Could be slightly more concise (e.g., delivery details repeated), but each sentence adds value. Front-loaded with purpose and prerequisites.

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

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

Covers all aspects: required/optional params, types, delivery, constraints, return value. No output schema, but description mentions 'Returns the new subscription id'. Complete for a subscription tool.

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

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

Schema coverage is 100%, but description adds extensive meaning: explains each type's params with examples (e.g., sec_8k items like ['5.02']), delivery patterns and constraints (phone verification, HMAC signing). 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 the tool creates a proactive monitoring subscription to a live-data event stream, with specific verb 'Create' and resource 'subscription'. It distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation and persistence.

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 context: requires Pipeworx OAuth account, no anonymous/BYO. Includes supported types with examples and delivery options. Could mention when not to use (e.g., for one-off pulls use 'recent_alerts'), but sufficient for typical use.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable context on return format (category-bucketed examples from live catalog) without contradicting annotations. No hidden behaviors omitted.

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?

Slightly longer but front-loaded with actionable query phrases. Every sentence adds distinct value, and the structure (scenario, output description, usage advice) is logical.

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

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

Despite no output schema, the description fully explains the return value (category-bucketed examples with tool shape). For an onboarding tool, this is complete and 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?

Input schema covers the one parameter (topic) at 100% description coverage. The description enhances this by explaining the effect of providing the optional topic: it focuses the examples. This adds clarity 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?

Description clearly states the tool is for onboarding ('What can I ask Pipeworx?') and returns example questions with tool+argument shapes. It distinguishes from sibling tools by positioning itself as the first tool to use when the agent doesn't know Pipeworx's capabilities.

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

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

Explicitly tells when to use (first touchpoint), alternatives for specific needs (ask_pipeworx, entity_profile, etc.), and how to call (no args vs topic parameter).

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. Adds value beyond annotations by explaining the deactivation effect and persistence of history.

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

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

Two sentences, front-loaded with the core action, no redundant information. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description fully covers the effect, ownership, and implications for historical data.

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

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

The single parameter 'id' is fully described in the schema. The description does not add further parameter-level detail, but baseline is 3 due to 100% schema coverage.

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

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

Clearly states it cancels a subscription by id, with ownership enforcement. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the cancel action and the deactivation behavior.

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 ownership is enforced, guiding that only own subscriptions can be cancelled. Does not explicitly contrast with alternatives, but the context of 'unsubscribe' and sibling names makes usage clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context (e.g., rate limits, authentication needs, or quirks).

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

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

Single sentence with no unnecessary words. Purpose and return value stated succinctly.

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

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

Given one parameter, full annotation coverage, and an output schema (as signaled), the description covers the essential purpose and return data. Minor missing info on error cases, but acceptable for a simple fetch tool.

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

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

Schema coverage is 0% (no description for 'user_id'). The description mentions the parameter in context and provides an example, but does not specify format constraints or validation 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 states a specific verb ('Fetch') and resource ('user profile') with a required parameter ('user_id'). It enumerates returned fields, distinguishing it from sibling tools like 'user_attended' which focuses on concerts.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., 'user_attended' or 'search_within'). No when-not-to-use conditions or side-effect disclaimers.

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 openWorldHint, covering safety. The description adds that it returns setlists with date, artist, venue, and track list, but does not disclose pagination details (e.g., default page size) beyond the mention of 'paginated'.

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

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

Single sentence with no filler, front-loaded with the core action ('Fetch paginated list'), and includes all key elements efficiently.

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. Description covers what is returned (date, artist, venue, track list). Minor missing details on pagination behavior (e.g., page size), but overall sufficient for a straightforward use case.

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

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

Schema coverage is 0%, so description must compensate. It explains user_id as the required identifier and implies p is for pagination via 'paginated list', but does not explicitly define p's meaning, range, or default. 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?

Clearly states 'Fetch paginated list of concerts a setlist.fm user has marked as attended, by user_id.' This is a specific verb+resource+scope, and it distinguishes from sibling tools like 'user' or 'setlist_search' which serve different purposes.

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

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

The description implies usage context (to get a user's attended concerts) but does not explicitly state when to use this tool versus alternatives or any prerequisites/limitations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by detailing the returned verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), extracted structured form, actual value with citation, and percent delta, as well as stating it replaces 4-6 sequential calls. This provides behavioral insight 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, front-loaded with usage examples and purpose, and each sentence adds value. It efficiently covers the tool's function, use case, supported domain, and output, with no redundant or 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?

Despite having no output schema, the description adequately explains the return structure (verdict types, citation, delta). It covers domain limitations (US public companies) and the value proposition. It could be slightly more complete by explicitly noting that claims must be financial and about US public companies.

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

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

The single 'claim' parameter has 100% schema coverage with a clear description. The tool description adds extra value by providing natural-language examples of valid claims (e.g., 'Apple's FY2024 revenue was $400 billion'), which enhances understanding beyond the schema.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with specific examples like 'Is it true that...' and 'fact check'. It uniquely distinguishes itself by specifying the domain (company-financial claims) and stating it replaces multiple sequential calls, making its purpose unmistakable.

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 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. However, it lacks explicit guidance on when not to use it (e.g., for non-financial claims) and does not mention alternative tools for other claim types.

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 the tool as read-only, idempotent, and non-destructive. The description adds value by specifying exactly what data is returned (name, city, country, coordinates, URL), which is additional behavioral context beyond the annotations.

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

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

The description is a single sentence that is concise, front-loaded with the action and resource, and contains 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 low complexity (1 parameter, simple return) and the presence of an output schema, the description is adequately complete. It covers the purpose, parameter, and return data without needing further details.

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

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

The input schema has one parameter 'id' with 0% description coverage. The description adds meaning by stating 'by venue id', clarifying that this is a venue identifier. However, it could further specify the format or source of the ID.

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' and the resource 'setlist.fm venue record by venue id', and lists the returned fields. It distinguishes from sibling tools like 'venue_search' (search) and 'venue_setlists' (setlists).

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 when you have a specific venue ID, but it does not explicitly mention alternatives like 'venue_search' for when the ID is unknown, nor does it provide 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, idempotentHint, and destructiveHint. The description adds that the result is a 'paginated list' and includes 'name, city, country' in results, but does not explain pagination behavior (page parameter, page size) or the underlying API. It adds moderate 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 two sentences long, front-loaded with the action, and contains no redundant information. Every word serves a purpose.

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

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

The description covers the main purpose, search criteria, and return fields. The output schema exists, so return values are documented. However, it lacks details on pagination control (e.g., how to use the 'p' parameter) and does not mention the default page size or result limit. Still, it is mostly complete for a search 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 description coverage is 0%, so the description must compensate. It mentions four of seven parameters (name, city, country, state) but misses others like 'p' (page), 'stateCode', 'cityId'. It adds meaning for the mentioned parameters but is incomplete.

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

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

The description clearly states the verb 'Search', the resource 'venues on setlist.fm', and the searchable criteria (name, city, country, state). It also mentions the return fields, distinguishing it from sibling tools like 'venue' and 'venue_setlists'.

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 searching by name, city, country, or state, but does not explicitly state when to use this tool versus alternatives like 'venue' or 'venue_setlists'. No direct comparison or exclusions are provided.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds value by mentioning pagination and return structure (date, artist, track lists), providing 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 one short sentence (39 words) with no wasted words. It front-loads the purpose and includes key details (pagination, return fields) efficiently.

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 rich annotations and existence of an output schema, the description is fairly complete. It explains what is returned and pagination, but could elaborate on pagination details (e.g., page size, next page indicator).

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

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

Schema coverage is 0%, so the description must compensate. It explains the id parameter (venue id) and hints at pagination via the word 'paginated', but does not detail the p parameter (e.g., page number semantics, default, range).

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

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

The description clearly states the tool fetches paginated setlists for a specific venue by its id, distinguishing it from sibling tools like venue_search (search venues) and artist_setlists (setlists by artist).

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

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

The description implicitly guides usage: when you have a venue id and want its setlists. It doesn't explicitly mention when not to use or alternatives, but the sibling list provides context, making the usage clear enough.

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