Ticketmaster

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

Annotations already communicate read-only, open-world, and idempotent behavior. The description adds valuable context beyond that: the free default model, the requirement to pass an Anthropic API key, and the fact that Anthropic calls are billed directly to the user. This is useful behavioral and cost disclosure.

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

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

The description is compact and well-structured: it begins with a clear purpose, then explains defaults, return values, and use cases. Every sentence is informative and there is no unnecessary repetition or filler.

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

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

Given that there is no output schema, the description rightly includes the return structure ({score, confidence, signals, raw_response} + combined view). It also covers default behavior, costs, and target use cases, making it complete enough for a 4-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%, so the baseline is 3. The description adds extra meaning by naming the default model and explaining the relationship between `models` and `_apiKey`, including the cost implication—something the schema alone does not fully convey.

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 has a specific verb ('probe') and resource ('LLMs'), and clearly states the output (visibility score 0-100 per model). It is easy to understand what the tool does, but it does not explicitly distinguish itself from closely related sibling tools such as scan_competitor_ai_presence.

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

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

The description gives concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This provides clear guidance on when to use it, but there is no explicit 'when not to use' or comparison with alternative sibling tools.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description's extra context is valuable. It discloses that the tool routes to thousands of tools, fills arguments, returns citations, and is a single fast call, which goes beyond the safety profile provided by annotations.

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

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

The description is longer than average but every sentence earns its place: it starts with the key directive, explains capabilities, provides examples, and defines escalation paths. Though slightly verbose, the information density is high and well-organized, making it effective rather than bloated.

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

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

With no output schema, the description clearly explains return values ('structured answer with stable pipeworx:// citation URIs'). It covers the tool's scope (5,529 tools, 1,455 sources), types of data, usage triggers, and alternatives, making it complete for an agent to decide when and how to invoke the tool.

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

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

The input schema has six parameters but all are aliases for 'question' with 100% schema coverage, so the baseline is 3. The description adds meaning by explaining the types of acceptable questions ('what is', 'look up', 'find') and giving concrete examples (SEC filings, FDA data, weather), which helps the agent frame queries appropriately.

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

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

The description clearly states what the tool does: it routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, making its role as the default entry point 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?

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'works on every tier'. It also explains when to step up to ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions), plus lists trigger phrases like 'what is', 'look up', and 'get the latest'.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds crucial context about the experimental nature: candidate routing improvements may be live under test, and results are compared against the stable router. It also states there is no active candidate currently, so behavior matches ask_pipeworx exactly, which is a key transparency disclosure.

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

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

Three sentences effectively explain the beta relationship, current state, usage, and fallback behavior. Each sentence serves a distinct purpose without waste. The text is well-structured, front-loaded with the core identity, and includes a clarifying note about not being a fallback.

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-required-parameter tool with no output schema, the description covers all necessary context: what it does, its relationship to siblings, when to use it, and current behavior. It even addresses the potential concern about beta reliability by stating it is a full working router. The mention of 'same response shape' compensates for the absent output schema.

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

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

The input schema already has 100% coverage, describing all six parameters and their aliases. The description adds no new parameter-specific details, just says 'same arguments' which is redundant given the schema. Baseline 3 applies because the schema carries the full burden, and the description doesn't need to compensate.

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 identifies the tool as a beta version of ask_pipeworx, an 'identical universal router' with the same tools, arguments, and response shape. This clearly conveys that it is a query-routing tool, but it relies on the reader knowing what ask_pipeworx does, so it's not fully self-contained. It does distinguish itself from the stable ask_pipeworx via its experimental routing status.

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

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

The description explicitly tells the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate, so it matches ask_pipeworx) and contrasts with the stable router. The phrase 'Falls back to nothing' prevents the misconception that it's a fallback, making usage guidance unambiguous.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses the return format including evidence as a verbatim quote, confidence, source, and refusal_reason. It also details explicit refusal reasons and the extra LLM call cost, giving a full picture of 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 dense but every sentence serves a purpose: purpose, process, return format, usage guidance, and cost. It is well-structured with clear cause-effect relationships and no redundancy.

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

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

Given the tool's behavioral complexity (routing, refusal handling, evidence extraction) and the absence of an output schema, the description thoroughly covers all relevant aspects: success and failure payloads, refusal reasons, use cases, and cost implications. It is fully self-contained.

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

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

Schema coverage is 100% with all parameters being aliases for 'question' and described as natural language. The description adds context that the question is used for routing, but does not significantly alter or enhance the parameter 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 that this is a 'hallucination-resistant answer mode for high-stakes reads' and explains it routes to the right tool and extracts answers only from tool results. This distinguishes it from siblings like ask_pipeworx and ask_pipeworx_beta by emphasizing grounded, evidence-based answers.

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

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

It explicitly says when to use this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the alternative (ask_pipeworx) and explains the cost trade-off.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. However, the description adds no behavioral context beyond the word 'single,' which is trivial. It does not describe return behavior, locale handling, or any other operational details.

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

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

Two words is not conciseness but under-specification. The description is too brief to convey the tool's purpose or usage, and it lacks structure or front-loading of key information.

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

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

Despite having annotations and an output schema, the description fails to communicate what the tool does or when to use it. For a simple lookup tool, a minimal but informative description like 'Get a single attraction by ID' would suffice, but this does not meet even that bar.

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

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

With 0% schema description coverage, the description was expected to explain the parameters. It provides zero information about 'id' or 'locale'. The schema examples hint at usage, but the description itself adds no semantic 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 'Single attraction.' essentially restates the tool name/title without specifying a verb or action. It gives only a vague hint that the tool deals with one attraction, failing to distinguish it from the sibling attraction_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?

The description provides no guidance on when to use this tool versus alternatives like attraction_search, event, or venue. There is no mention of prerequisites, intended use cases, or exclusions.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds value by specifying the return payload (name, ID, classifications, images) and naming the Ticketmaster Discovery API. It does not disclose edge cases like the default-feed behavior, but that is captured in schema, so the description contributes reasonable 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 two concise sentences with no filler. It front-loads the action and resource, then lists return fields. Every sentence earns its place.

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

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

With a rich output schema and comprehensive annotations, the description is sufficient for an agent to select and invoke the tool. It could mention the keyword-omission behavior, but that is provided in the schema. For a search tool with high schema coverage, this is nearly complete.

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

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

The input schema has 100% property description coverage, so the description does not need to elaborate on parameters. It mentions 'keyword, classificationName, or other filters,' which aligns with schema properties but adds little meaning beyond what property descriptions already provide. 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 searches attractions (artists, sports teams, performers) by keyword and other filters, and lists the return fields (name, ID, classifications, images). This specific verb+resource combination distinguishes it from sibling tools like event_search and venue_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?

The description provides clear context that this is for searching attractions, not events or venues, which helps agent selection. However, it does not explicitly name alternatives or state when not to use it; the conditional behavior (omitting keyword returns default feed) is in the schema, not the main 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 establish readOnly=true, idempotent=true, and non-destructive, but the description adds substantial behavioral context beyond that: low-confidence short-circuiting, closed-market status handling, resolver match confidence semantics, parent-event extraction, news fallback mechanisms (GDELT 429s), and resolution-rule risk (flat-50¢ void settlements). This is a rich behavioral contract that goes far beyond what annotations provide.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loaded purpose. Each section adds necessary detail for a complex tool, and there is minimal repetition. It is slightly verbose but not bloated, so it earns a 4 rather than 5.

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

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

With no output schema, the description fully documents the response structure: result.market, result.analysis, result.evidence, resolver contract fields, parent_event fields, and status values (low_confidence_match, market_closed_or_inactive). It also covers failure modes and edge cases like news fallback and cancellation-rule parsing, making the description self-sufficient for an agent to anticipate all relevant outcomes.

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 each parameter described, so the baseline is 3. The description adds real value by illustrating how to pass different `market` formats (slug, URL, question text), providing fan-out examples that clarify interpretation (e.g., 'BTC bet → coingecko + fred + gdelt+gnews'), and explaining the practical consequences of `include_raw` and `depth` choices. This elevates semantics beyond the raw schema.

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

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

The opening sentence states a specific, unique purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edges by focusing on per-bet research. The 'Use for' examples ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') further clarify the intended niche.

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

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

The description gives explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides category-specific fan-out examples that implicitly guide when to use specific data sources. However, it does not explicitly name sibling tools as alternatives or state when NOT to use this tool, which would merit a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety expectations. The description adds context that the data comes from the 'Ticketmaster Discovery API' and details the exact structure returned (segment, genre, sub-genre hierarchy), which goes beyond what annotations provide.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then specifies the returned data hierarchy. No unnecessary words or redundancy, making it appropriately 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?

For a simple get-by-ID tool with a rich output schema, the description is mostly complete: it names the resource, the lookup method, and the expected data hierarchy. The only gap is the undocumented 'locale' parameter, but given the output schema covers return values, this is a minor omission.

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

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

Schema description coverage is 0%, and the description only hints at the 'id' parameter via 'by ID'. The optional 'locale' parameter is completely undocumented, leaving it unexplained. Since the schema provides no descriptions, the description should compensate but only partially addresses the parameters.

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

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

The description clearly states it returns 'full detail for a single classification by ID', specifying both the resource (classification) and the scope (single by ID). It distinguishes itself from the sibling tool 'classifications' (plural) which likely handles listing or searching, 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 the tool is used when you have a specific classification ID and want detailed hierarchical data. However, it does not explicitly mention when to use this over alternatives like 'classifications' or provide any exclusion criteria, leaving usage guidance 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 establish read-only, idempotent, non-destructive behavior. The description adds context about the taxonomy hierarchy and the 'list all' scope, which goes beyond the schema. It doesn't discuss pagination or return format, but the safety profile is fully covered by annotations and an output schema exists.

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?

A single, well-structured sentence conveys the API source, the action, a concrete example, and the practical use case. Every phrase earns its place 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?

With zero parameters, rich annotations, and an output schema, the description provides all necessary context for selecting and invoking the tool. It clearly explains the type of data returned and how it should be used in conjunction with event_search.

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 input schema fully covers parameter semantics. The description reinforces that no input is needed by saying 'list all', and it provides useful guidance about classificationName values for downstream use with event_search.

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 all') with a clear resource ('event classification segments, genres, and sub-genres') and provides a concrete hierarchy example (Music > Rock > Alternative). This distinguishes it from the singular sibling 'classification' by emphasizing the plural, exhaustive listing 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?

It explicitly states when to use this tool: to discover valid classificationName values for filtering event_search. It doesn't name exclusions or directly contrast with the singular 'classification' tool, but the intended use case is clear and actionable.

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

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

Beyond the read-only/idempotent annotations, the description details data sources (SEC EDGAR/XBRL for company, FAERS/FDA for drug), fiscal-year handling, sorting by primary metric, and output format (paired data + citation URIs). This adds rich 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 dense yet efficient, front-loading trigger phrases and the core value proposition. Every sentence serves a purpose: usage examples, preference directive, per-type behavior, sorting, and output formatting. No filler.

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

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

Given there is no output schema, the description adequately covers return values ('paired data + citation URIs'), sorting, and data sources. It fully addresses the tool's complexity and use cases, leaving no critical gaps for an agent to infer.

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 schema already describes both parameters, the description enriches them substantially: it explains the 'type' choices (company pulls 10-K financials, drug pulls adverse-event counts) and gives concrete examples for 'values' (tickers vs drug names). This is a meaningful addition 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 a specific action: side-by-side comparison of 2-5 companies or drugs in one call. It distinguishes itself from sequential single-pack lookups, aligning with the sibling entity_profile while explicitly positioning its own 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?

Provides explicit trigger phrases ('Compare X and Y', 'X vs Y') and a strong directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains when to use type=company vs type=drug, giving clear usage context.

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

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description details the findings packet structure (evidence, confidence, citation_uri, gaps[], contradictions[]), latency expectations, depth-specific behaviors, and the guarantee that citations are always fetchable. It also clarifies the tool never invents answers. 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 it front-loads the critical account requirement and uses paragraphs to group related information. Every sentence adds value, though density is high; a bit of formatting would 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?

With no output schema, the description fully describes the return packet, including citations, gaps, contradictions, and hop field. It also covers performance, auth tiers, and depth semantics, making it complete for a complex tool with only two 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?

Although the schema already documents both parameters, the description adds substantial meaning: it defines depth levels precisely (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop) and confirms the question parameter can be 'broad/multi-part.' This goes beyond the schema's terse descriptions.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly distinguishes it from open-web search and from sibling ask_pipeworx. The core actions (decomposes, routes, returns) are specific and unambiguous.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions' and 'For a single lookup use ask_pipeworx' plus advice to prefer ask_pipeworx for breaking news. It also lists prerequisites (account, paid plan for thorough) and a fallback: 'If you are not signed in, use ask_pipeworx instead.'

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing the return format (top-N with full schemas, ready to call directly, no second lookup) and the fact that results are directly callable, which goes beyond the annotations.

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

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

The description is front-loaded with the core purpose and includes domain examples and usage guidance. The enumerated domain list is somewhat long but informative; every part earns its place.

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

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

The description covers the tool's return format, use cases, and when to call it first. There is no output schema, so the description compensates by explaining what results contain. It does not mention pagination or limit defaults, but those are in the schema.

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

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

Schema description coverage is 100%, with all parameters (query, aliases, limit) documented with examples. The description does not add additional parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description begins with a specific verb+resource: 'Find tools by describing the data or task.' It clearly lists supported domains and distinguishes itself from sibling tools by positioning as a discovery tool that returns callable schemas, rather than performing a specific task.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use by saying 'not just one answer,' but does not name explicit 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 mark readOnly, idempotent, and non-destructive. The description adds behavioral context by detailing the fan-out across SEC EDGAR, XBRL, USPTO, news (GDELT→GNews fallback), and GLEIF, and discloses the patents API 'sunset May 2025 — soft-fails until reactivated'.

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

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

The description is long but every clause contributes information. It is front-loaded with query examples, then proceeds to data sources, return fields, and input constraints, using semicolons for scannability. It earns its length 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?

There is no output schema, so the description carries the full burden of explaining returns. It enumerates all returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and covers input limitations, fallbacks, and the parallel-call behavior, making it highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples ('AAPL', '0000320193'), clarifying the zero-padded CIK format, and explicitly stating that names are not supported—this reinforces the schema without being redundant.

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 'full cross-source profile of a US public company', with specific verbs like 'tell me about X' and 'brief me on Tesla'. It differentiates from sibling tools by instructing to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed.

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

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

It explicitly states when to use the tool: 'when the user asks for a holistic view'. It also gives an alternative: 'use resolve_entity first if you only have a name', and describes the types of queries that should use it.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior, but the description adds no behavioral context. It does not explain what 'single event' implies, what data the event contains, or any side effects, leaving the burden unmet despite extensive 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?

At only two words, the description is under-specified rather than concise. It adds no useful information, and even the minimal text is redundant with the tool name 'event'.

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?

Although the tool has a simple schema and an output schema exists, the description fails to establish the tool's purpose or usage. With many event-related siblings, a complete description should clarify that 'event' retrieves a single event by ID, making this minimally viable at best.

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

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

Schema description coverage is 0% and the description provides no semantics for 'id' or 'locale'. The description does not even hint that these parameters identify and localize the event, so the agent gets no help beyond the raw schema field names.

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

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

The description 'Single event.' provides no verb or action; it merely restates the tool name and indicates singularity. It fails to say whether this retrieves, creates, or updates an event, and does not distinguish it from siblings like event_search or event_images.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer the tool's role from the name alone.

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

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

The description adds no behavioral context beyond what the annotations already convey. It doesn't explain how images are returned, whether the event ID must exist, or any additional operational traits. The annotations cover the safety profile, but the description itself is silent.

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

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

The description is extremely short, but it is under-specified rather than concise. It merely restates the title, so the sentence does not earn its place. No useful information is packed into the brevity.

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

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

For a tool with a single generic 'id' parameter and no schema description, the description is insufficiently complete. It doesn't explain the nature of the images, the relationship to the event, or the return structure. An output schema exists, but the description still leaves the tool's purpose ambiguous.

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 schema coverage at 0%, the description carries the burden of explaining the 'id' parameter. The phrase 'Images for an event' implies that the id refers to an event, but it doesn't explicitly state that the parameter is an event identifier or describe the expected format. This provides marginal value over the bare schema.

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

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

The description 'Images for an event' restates the title 'Event Images' without adding a verb or clear action. It fails to specify whether the tool retrieves, lists, or uploads images, making it essentially tautological.

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

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

No guidance is provided about when to use this tool versus alternatives like 'event' or 'event_search'. The description gives no context on prerequisites, selection criteria, or exclusions, leaving the agent without direction.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable caveats: omitting keyword returns an unfiltered default feed, and keyword matches may be imprecise compared to venueId. This goes beyond annotation coverage and helps avoid misuse.

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, then usage guidance, then return info. Every sentence earns its place with no fluff or redundancy.

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

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

Given the rich schema (13 params, 100% covered), output schema, and helpful annotations, the description is complete. It covers key use cases, return contents (dates, venue, ticket links), and critical caveats. 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?

The schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra semantic value by explaining how to combine parameters (e.g., using venueId from venue_search, using date window for 'this month') and warns about keyword behavior.

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

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

The description clearly states the tool's function: searching live events via Ticketmaster's Discovery API with a comprehensive list of filters. It distinguishes itself from sibling tools like venue_search by focusing on events and mentioning venueId from venue_search for exact matches.

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

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

It explicitly states preferred use cases ('what is on at <venue>', 'upcoming <artist> concerts', 'events in <city> this month') and provides guidance on when to use keyword vs venueId. This helps the agent choose between event_search and venue_search.

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 destructive and idempotent behavior. The description adds context about what is destroyed ('previously stored memory by key') and a use case for clearing sensitive data. It does not contradict annotations.

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

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

Three concise sentences with the main verb front-loaded. Every sentence adds value: purpose, when to use, and relationship to sibling tools.

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?

This is a simple one-parameter tool with no output schema. The description, combined with annotations and the existing schema example, fully covers what the agent needs to know to select and invoke it correctly.

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

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

Schema coverage is 100%, and the parameter 'key' is described as 'Memory key to delete.' The description does not add much beyond this, but the schema itself is fully sufficient given the tool's simplicity.

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 a specific verb+resource: 'Delete a previously stored memory by key.' This clearly distinguishes the tool from sibling tools like 'remember' and 'recall' by specifying the delete operation on memories.

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

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

It explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall,' giving clear context for usage relative to sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable operational detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' plus 'Output is a single text blob ready to drop at site-root/llms.txt'. This enriches the behavioral profile 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 followed by a bulleted use-case list. It front-loads the purpose, then explains the process/output, and ends with actionable use cases. Every sentence adds distinct value with zero 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 (2 params, no output schema) and the description effectively covers input, processing, and output format. It also communicates the practical application via use cases. Minor omissions like failure behavior on inaccessible URLs are not critical for a read-only, idempotent tool with this simplicity.

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

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

Schema description coverage is 100% with detailed explanations for 'url' and 'max_links' (including default and max). The description's mention of 'key links' aligns with max_links but adds no new parameter-specific semantics. Baseline 3 is appropriate because the schema already carries the parameter documentation burden.

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 opens with a specific verb+resource+scope: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' by stating the deliverable is the actual llms.txt file, not just a check or scan.

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

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

Provides three concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). This gives clear context on when to use it, though it does not explicitly name alternative tools or negative cases. The 'for any URL' phrase implies broad applicability.

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, so the safety profile is covered. The description adds useful behavioral context: the tool is scoped to the caller's subscriptions, returns specific fields, and defaults to active-only subscriptions. This exceeds the annotation baseline.

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

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

The description is two sentences, front-loaded with the tool's action, and every clause adds value: scope, return fields, and concrete use cases. No filler or 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?

The tool is simple with one optional parameter, and the description covers purpose, scoping, return fields, and usage guidance. While there is no output schema to define field semantics, the named fields are reasonably self-explanatory. A slightly richer description of 'params' or 'type' could push this higher, but the current coverage is adequate for a low-complexity 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 schema coverage is 100% for the single optional parameter include_inactive, and its description in the schema is clear ('Include cancelled subscriptions in the response (default false)'). The tool description does not need to add parameter semantics, but it also does not add extra value beyond the schema, so the baseline 3 applies.

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 and resource ('List the caller's active subscriptions') and clearly distinguishes active from cancelled via the include_inactive parameter. It also lists the return fields, making the tool's purpose unmistakable and distinct from sibling tools like subscribe/unsubscribe.

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

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

The description provides clear when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly name alternative tools or when-not-to-use, but it gives sufficient context for appropriate 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 provide minimal information (all hints false). The description compensates fully by disclosing behavior: filing returns a claim_token, passing it back later reads status, rate-limiting (5 per identifier per day), no quota impact, and the instruction not to paste the end-user's prompt.

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

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

The description is long but every sentence carries important information: purpose, usage, exclusions, token mechanics, rate limits, and strategic impact. It is front-loaded with the core purpose and then flows logically through when-to-use, constraints, and follow-up. Slightly verbose but efficiently structured.

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

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

For a feedback tool with 4 parameters, one nested object, no output schema, and minimal annotations, the description covers everything an agent needs: when to file, what to include, exclusion criteria, token follow-up, rate limits, and expected response. It is fully self-contained.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining claim_token usage in detail ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and elaborating on message content ('Don't paste the end-user's prompt'). This adds actionable context.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from the many search/research sibling tools, and further details the exact feedback categories (bug, feature/data_gap, praise).

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 when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog...') and provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' with an explicit alternative ('file it with that server instead').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' These disclose data provenance, privacy, and caching behavior 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 structured with a lead sentence stating the primary output, followed by use cases and technical details. Each sentence earns its place: it explains what it returns, why it's useful, what the data is, and how it's cached. No fluff or repetition.

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

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

Given no output schema, the description compensates by explaining the output format ('top tools, top packs, and total call volume', 'just (pack, tool, count)'), the time windows, use cases, data source, privacy, and caching. It is complete for an agent to decide whether and how to invoke the tool.

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

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

The schema covers the only parameter (window) with 100% description coverage, including semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' The description mentions the window values but adds no additional parametric meaning beyond the schema, so the baseline 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 opens with a clear, specific statement of what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('returns') and resource ('top tools/packs/call volume'), and distinguishes itself from siblings by emphasizing the aggregated, self-referential nature ('What other AI agents are calling on Pipeworx right now').

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

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

The description provides explicit usage scenarios: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' It gives clear context for when to use the tool, though it does not explicitly name alternative tools or state when not to use it.

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

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

The description discloses behavioral quirks far beyond the readOnlyHint: deviation threshold (>3pp), placeholder filter (>20% returns null), semantic similarity threshold (≥0.30 Jaccard, skipped_low_similarity), and fill check logic (realizable_edge_pp ≤ 0 means do not trade). It also explains what the response includes and warns about thin legs. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK, Response). Each sentence delivers actionable information; no fluff. The front-loading of usage modes helps scanning.

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

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

Given the tool's complexity (multiple modes, filters, fill check) and no output schema, the description fully specifies return fields (opportunities[], gap_pp, suggested_trade, reasoning, partition_check{...}, realizable_edge_pp_at_book, thin_legs). It covers all modes and edge cases, making the tool safely invocable.

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

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

Although schema descriptions already cover both params 100%, the description adds rich semantics: event is explained as walking child markets and checking date/threshold-axis ordering, topic is described as cross-event flattening and comparator on union. It also clarifies the no-arg behavior, which the schema doesn't cover.

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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings like polymarket_edges by specifying the arbitration method and modes (trending_scan, event, topic), making the tool's unique purpose evident.

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 mode selection guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also recommends an alternative for custom sizing ('For custom sizing use polymarket_fill_risk') and explains why cross-event mode is useful ('catches ... by May 31 vs ... by Jun 30 patterns').

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses extensive behavioral details: three response segments, model family specifics, placeholder-slug filters, per-sport biases, 24h-move warnings, Fed bets excluded from ranking, diagnostics for empty segments, and cache behavior. It also warns that edges may already be priced in.

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 densely packed with valuable information organized into logical segments. It front-loads the purpose and then details the response structure, knobs, and diagnostics. While slightly verbose, every sentence earns its place 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?

The description covers the full response structure including by_segment, fed_candidates/fed_note, and _diagnostics, along with the fields carried by each opportunity. It also explains why segments may be empty and the caching behavior, making it complete despite the absence of an output schema.

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

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

The input schema already has 100% coverage, but the description adds critical context about how the tradeable-edge knobs (min_liquidity, max_spread_pp) drop unrealizable opportunities and how min_partition_leg_kelly applies specifically to per-leg Kelly inside partitions. It clarifies interactions like why min_kelly doesn't apply to partition arbs, which goes 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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which is a specific verb+resource+outcome. It also explicitly frames the use case ('what should I bet on today') and distinguishes it from other sibling tools by mentioning agent discovery without paging hundreds of markets.

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

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

The description sets clear context: this is for discovering betting opportunities quickly, particularly when you want to avoid manually paging through many markets. It does not explicitly name alternative tools or state when not to use it, but the context is sufficient.

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

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

Despite readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: snapshot TTL limits, gaps in snapshot_dates due to cache-miss behavior, decay computed from daily closes (not intraday), and response semantics for tracked/expired items. This goes far beyond what annotations provide.

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

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

The description is information-dense and well-structured with clear ARGS, RESPONSE, and LIMITS sections. Every sentence contributes useful detail without fluff or redundancy. It is longer than average, but the tool's complex response format justifies the length.

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

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

The tool has no output schema, so the description must explain return values. It does so thoroughly: tracked[], expired[], and snapshot_dates[] are all defined with their contents and implications. Limitations (TTL, snapshot gaps, daily closes) are also disclosed, making the description complete for an agent to use the tool correctly.

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

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

Schema coverage is 100% and both parameters have detailed descriptions. The description repeats the defaults but does not add meaning beyond the schema; in fact, it omits the clamp range for days. Since schema already handles semantics, description adds no significant value, so baseline 3 is appropriate.

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

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

Clearly states the tool provides 'edge persistence and decay telemetry' and answers the concrete question 'how long has this edge existed and is it shrinking?'. This differentiates it from sibling tools like polymarket_edges, which presumably returns current edges, by focusing on historical persistence and decay.

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 when to use it: when you need to understand edge persistence/decay vs a fresh edge. It does not explicitly name alternatives or state 'when not to use', but the context and the distinguishing question provide clear usage context. Some credit lost for no 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 readOnlyHint and destructiveHint:false, lowering the burden. The description adds extensive behavioral context: it 'walks the ladder', returns partial fill information, and for baskets highlights 'thin_legs' and 'forced_directional_risk'. It also explains the behavioral risk of partial fills converting an arb into an unhedged position, which is a non-obvious operational detail beyond what annotations convey.

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 tightly structured: it opens with a one-sentence purpose, then clearly labels REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections. Each sentence carries essential information—no filler. The use of uppercase section headers and bullet-like returns makes navigation easy despite the density.

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

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

With no output schema, the description fully enumerates the return fields for both modes, including the verdict values, per-leg details, and risk indicators. It also covers parameter defaults, clamping, mode-specific interpretations, and the strategic use case. There is no gap in what an agent needs to know to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so parameters are already documented. The description goes beyond by explaining the economic interpretation of `side` in basket mode ('sell_yes = capture overround... buy_yes = capture underround'), the dual meaning of `size_usd` (spend on buys vs target proceeds on sells; settlement notional in basket mode), and the 'auto' default logic for side. This adds substantial practical meaning to each 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 opens with a clear purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It differentiates from siblings by explicitly naming related tools (polymarket_arbitrage, polymarket_edges) and positioning itself as the pre-trade fill-risk validation. It also specifies two distinct modes (single-market and basket), each with a concrete verb and resource.

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

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

The description gives explicit when-to-use instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It clearly explains the required input (market or event) and how each parameter behaves differently depending on mode, effectively acting as an usage guide. No ambiguities remain about when this tool should be invoked.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description richly discloses behavior: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype meanings, and the response structure. It also honestly cautions that pre-mapped ≠ tradeable, adding valuable non-obvious 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 long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes substantive information—no filler. The front-loaded core definition and organized layout make it easy to scan.

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

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

Given the complexity of cross-venue matching, the description thoroughly covers return values (leg-by-leg prices, spread, top_spreads_pp), safety warnings (compatibility_warning), and temporal alignment. With no output schema, this self-contained description is sufficient for an agent to understand what the tool returns and when to trust it.

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

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

Input schema already covers all three parameters with descriptions, so baseline is 3. The description adds meaningful context by explaining the two modes and how explicit parameters override topic-mapped counterparts, which goes beyond the schema's individual parameter descriptions.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons and details two distinct operation modes (topic shortcuts vs explicit tickers).

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

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

The description provides explicit usage context: when to use topic mode vs explicit mode, and warns that most pre-mapped topics are not tradeable. It lacks explicit comparison to alternative tools, but the mode guidance is clear and practical.

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 this as read-only, idempotent, and non-destructive. The description adds useful behavior: omitting the key lists all saved keys, and results are scoped to an identifier. However, it does not disclose the return format or behavior when a key is missing, which would be valuable given there is no output schema.

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

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

The description is four sentences, each conveying distinct, non-redundant information: core behavior, use case with examples, scoping, and relationships to sibling tools. It is efficiently front-loaded and avoids filler.

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 strong annotations, the description covers purpose, usage, scoping, and integration with remember/forget. The only gap is the absence of any indication of the return structure, but for a simple retrieval this may be considered acceptable.

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

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

The input schema covers the parameter well (100% coverage) with the description 'omit to list all keys'. The tool description adds practical examples of typical key values ('target ticker, an address, prior research notes') and reinforces the omit behavior, going slightly beyond the schema's bare 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 uses a specific verb ('Retrieve') and resource ('a value previously saved via remember') and clearly distinguishes two modes: retrieving a single value or listing all keys. It explicitly relates to sibling tools remember and forget, making the tool's unique role 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 provides a clear use case ('look up context the agent stored earlier... without re-deriving it from scratch') and offers explicit guidance on when to pair with remember and forget. It implies when not to use it (i.e., when you need to save or delete), but does not discuss when to prefer a research or search sibling tool over this memory recall 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?

Annotation Contradiction: The description discloses a state-changing side effect ('Set mark_read:true to flag returned events read so the next call only shows newer ones'), which directly contradicts the readOnlyHint: true annotation. This makes the behavioral profile misleading despite the description's transparency.

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

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

The description is relatively concise and front-loaded with the main action. It includes useful extras like the alternative HTTP endpoint without being wordy. Every sentence serves a purpose, though the HTTP endpoint could be considered a minor digression.

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 moderate-complexity tool with no output schema, the description covers the return payload, filtering, mark_read behavior, and polling. It provides sufficient context for an agent to use the tool effectively, though the contradiction with annotations slightly undermines completeness.

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

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

The schema already covers 100% of parameters, so the baseline is 3. The description adds semantic value by explaining the purpose of type ('sec_8k') and since (ISO timestamp), and by detailing the side effect of mark_read, going beyond simple parameter definitions.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states what the tool does and distinguishes it by mentioning the persisted feed and evaluator-written alerts, setting it apart from other tools like recent_changes or event_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?

The description says 'Polls work fine' and offers an alternative HTTP endpoint for scripts/dashboards, which implies usage scenarios. It also explains filtering by type and since, giving practical context. However, it does not explicitly name sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: fans out to multiple APIs, follows a fallback order, soft-fails for USPTO due to PatentsView sunset, and returns a specific structure with pipeworx:// citation URIs. No contradictions.

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

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

The description is front-loaded with natural-language use cases, then compactly details sources, fallbacks, and output. Every sentence adds useful information without repetition 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?

Because there is no output schema, the description correctly includes the return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers parameter formats, edge cases (rate limits, API sunset), and alternative tool guidance, making it fully self-contained.

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

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

Schema coverage is 100%, so the baseline is high. The description goes further by explaining `since` accepts ISO date or relative shorthand, suggests '30d' as a typical window, and clarifies that `value` can be a ticker or zero-padded CIK, which adds practical 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 names the tool as a change feed for a company over a time window, enumerates the data sources (SEC EDGAR, GDELT/GNews, USPTO), and differentiates it from the sibling tool entity_profile, which returns a static profile. The verb 'returns' is implied but the scope is unambiguous.

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

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

The description explicitly says 'Use entity_profile instead when you want the static profile' and explains when this tool is appropriate. It also provides fallback logic for news sources (GDELT preferred, GNews on rate-limit/5xx) and parameter recommendations ('Use "30d" or "1m" for typical monitoring').

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

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

Beyond the annotations (idempotent, non-destructive, not read-only), the description discloses key behavioral traits: key-value scoping by identifier, persistence differences between authenticated and anonymous sessions (24 hours), and the cross-session retention capability. This gives the agent a solid understanding of the tool's runtime 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 efficiently written, with the core purpose front-loaded in the first sentence. Every sentence contributes value: purpose, usage examples, storage semantics, persistence details, and companion tools. There is no filler or redundant language.

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 key-value store with no output schema, the description provides complete necessary context. It explains what to store, when to use it, how persistence works, and how it relates to sibling tools (recall/forget). No essential information is missing for an agent to invoke correctly.

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

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

The input schema already provides 100% description coverage for both parameters, so the baseline is 3. The description adds useful context about 'scoped by your identifier,' which affects how keys should be chosen, and clarifies that values can hold any text. This additional scoping insight elevates the parameter semantics 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 opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly states the tool's function as a memory store and distinguishes itself from sibling tools by naming recall and forget for retrieval and deletion. This makes the purpose unmistakable and distinct.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' followed by concrete examples (ticker, address, preference, research subject). It also indicates companion tools ('Pair with recall to retrieve later, forget to delete'), effectively outlining when to use this tool versus alternatives.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses important behaviors: identifiers are source-labeled, unresolved items appear in an `unresolved` field, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. This gives the agent a clear model of what to expect.

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

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

The description is long but dense and front-loaded with example queries that clarify intent. While some content (e.g., accepted input formats) repeats the schema, every section serves a purpose; the structure is coherent and 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?

Even without an output schema, the description thoroughly specifies return values for both company and drug types, including the CIK/ticker/LEI/FIGI fields, source labeling, `unresolved` behavior, and the RxCUI citation. It also covers fallback behavior and the internal cascade, making it complete for a tool with this complexity.

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

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

The input schema already provides 100% coverage of both parameters, including enum values and input formats. The description reinforces these formats (e.g., 'ticker, CIK, or company name') but adds no new semantic information beyond what the schema states, so the baseline score of 3 applies.

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 its function: resolving user-spoken names to canonical identifiers required by other tools. The opening query examples and the directive 'Use FIRST whenever you have a name but need an ID' distinguish it from sibling lookup/analysis tools, 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 instructs when to use the tool ('Use FIRST whenever you have a name but need an ID') and enumerates accepted input formats for each type. It does not name alternative tools or state explicit exclusions, but the context is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds operational detail: 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and specifies the return format. 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?

Three sentences, front-loaded with the core purpose, then process, then use case and return format. Every sentence adds value; no wasted words or repetition of schema fields.

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

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

With no output schema, the description adequately explains the return value ('ranked list with score, confidence, signal density per entity'), the process, and the intended use case. It is slightly thin on edge cases (e.g., behavior when fewer than 2 entities) but sufficient for a read-only 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%, with detailed descriptions for all parameters including entities, models, _apiKey, and context. The description restates 'your brand + N competitors' but adds no new parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes from sibling ai_visibility_check by focusing on multi-entity comparison and ranking, and explicitly names the process (probes with ai_visibility_check, ranks by score).

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 clear context: 'Useful for competitive AI-marketing audits' with an example question, establishing when to use. Does not explicitly name alternatives or exclusions, but the use case is unambiguous.

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 read-only/idempotent, and the description adds behavioral details: fan-out across two services, partial failure handling, and a 5-30s latency warning for first bundlephobia measurement. 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?

Three dense sentences cover purpose, usage, output, limitations, and failure modes. Every clause adds information; 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?

For a composite tool with no output schema, the description lists the summary fields, links, alternatives, and failure behavior. It covers ecosystem scope, latency, and graceful degradation, making it nearly self-sufficient.

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

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

Schema provides 100% description coverage for both parameters, including scoped package support and version default. The tool description adds no extra parameter semantics beyond schema, so baseline 3 applies.

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

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

Description states it is a composite check for npm package adoption, clearly distinguishing from siblings by specifying the fan-out to deps.dev and bundlephobia and the NPM-only scope. It names the exact use case ('is X safe / popular / small'), making it unique among research 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 'Use whenever an agent asks...' provides clear trigger conditions. It also names an alternative for other ecosystems ('deps.dev:version directly'), which is a direct when-not-to-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?

Even with annotations declaring readOnly, openWorld, and idempotent, the description adds meaningful behavioral details: every passage carries an offset for verification, uses BGE-base-en embeddings + cosine over 500-char windows, and truncates inputs over 200K chars with a flag. These go well beyond annotations and disclose implementation 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 front-loaded with the core function, then flows logically into usage, pairing, and technical details. Every sentence adds unique value—no filler or repetition. Despite its length, it remains concise and well-structured, appropriate for 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?

With no output schema, the description compensates by specifying return format: 'top-N passages with character offsets and similarity scores.' It also covers edge cases (200K char cap, truncation) and provides a strong pairing suggestion. For a search tool, this is thorough and self-contained.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The tool description adds example queries ('supply-chain risk', 'fiscal year 2024 revenue') and clarifies the 'top-N passages' behavior, but most parameter semantics remain in the schema. This meets the baseline of 3 without substantial additional 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 opens with 'Semantic search INSIDE a fetched record,' which clearly states the tool's purpose with a specific verb and resource. It distinguishes itself from siblings by emphasizing it operates on already-fetched text, contrasting with broader Q&A tools like ask_pipeworx.

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

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

It explicitly states when to use: 'Use when the record is too big to cram into the prompt' and provides a concrete alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and even names the sibling, satisfying 5-level criteria.

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

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

Beyond the annotations, the description discloses important behavioral traits: it requires a Pipeworx OAuth account, anonymous/BYO users cannot persist subscriptions, SMS delivery requires a verified phone and has a 10/day cap, and the feed is always on. These are meaningful side-effect and constraint details that help an agent anticipate real-world outcomes.

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

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

The description is dense but well-organized, front-loading purpose before diving into types and delivery. Every clause serves a purpose, though the long single block is somewhat heavy and omits two schema types and webhook from the top-level summary.

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

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

The description is incomplete as a standalone overview: it lists only three of the five enum types (missing patent_grant and clinical_trial) and mentions only feed/email/sms, omitting webhook. The schema fills those gaps, but the description's 'Supported types' and 'Delivery channels' labels are misleadingly narrow.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for sec_8k items (e.g., items:["5.02"]), polymarket topic (e.g., topic:"fed"), and fred_series series_id, plus delivery constraints like phone verification and rate caps. These examples clarify the parameter format beyond the schema's property descriptions.

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

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

The description uses a specific action verb ('Create') with a concrete resource ('a proactive monitoring subscription to a live-data event stream') and states the key return value ('Returns the new subscription id'). It clearly distinguishes this tool from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description explains that the feed is always on and can be pulled via recent_alerts or GET registry.pipeworx.io/alerts.json, implying subscribe is for proactive push-based monitoring rather than manual polling. It gives concrete type examples and delivery options, though it does not explicitly name excluded alternatives or when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect expectations. The description adds that it returns ranked suggestions and is tied to the Ticketmaster Discovery API, but doesn't disclose additional behaviors like result limits or pagination. Since annotations carry most of the burden, the description adds modest value beyond them.

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 purpose, then a usage note. No filler or repetition. Every sentence adds value.

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

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

The tool is simple (one parameter, no nested objects) and has an output schema, so the description doesn't need to detail return values. It covers the what, the output type, and the when-to-use. Slight gap: no mention of any limitations or edge cases (e.g., no results), but overall it's sufficiently complete for its complexity.

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

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

The schema only defines a 'keyword' string with no description (0% coverage), but the tool description explicitly explains its meaning: 'autocomplete suggestions for a keyword' and 'resolve partial names.' This compensates for the schema gap by telling the agent the parameter should be a partial name, adding clear semantics.

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

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

The description states a specific verb+resource: 'autocomplete suggestions for a keyword: returns matching events, attractions, and venues ranked by relevance.' It clearly distinguishes from sibling search tools by explicitly positioning this as a pre-resolution tool for partial names before querying other endpoints.

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 clear usage context: 'Use to resolve partial names before querying other endpoints.' This tells the agent when to use the tool, though it doesn't explicitly name alternative tools or state when not to use it, which would earn a 5.

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

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

Annotations already declare safety (readOnly, non-destructive, idempotent). The description adds behavioral context beyond annotations: it returns category-bucketed examples drawn from a live catalog, and describes the effect of omitting or providing the topic parameter. It does not discuss edge cases or potential variability, but for a read-only suggestion tool this is adequate.

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

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

The description is long but well-structured: it opens with example queries to help recognition, then states purpose, output, parameter behavior, and when-to-use. Every sentence contributes useful information; the list of example phrasings could be trimmed slightly but serves to clarify the tool's trigger scope.

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

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

For a tool with one optional parameter and no output schema, the description fully covers what the tool does, what it returns (including the tool+argument shape), and when to use it. It also situates the tool among siblings and explains the optional topic behavior, making it complete for an agent to invoke correctly.

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

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

Schema already describes the parameter at 100% coverage, so baseline is 3. The description adds value by providing concrete example values ('finance', 'pharma', 'betting') and clarifies the parameter's effect (focus the spread) and optionality, going beyond the schema's bare 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's purpose: it is the onboarding entry point for an agent to discover what to ask Pipeworx. It specifies the output (category-bucketed example questions with exact tool and argument shape) and differentiates from siblings by naming ask_pipeworx, entity_profile, and compare_entities as meta-tools to learn about.

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

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

Explicitly instructs when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also provides guidance on optional topic filtering and examples of valid topics, which clarifies how to invoke it in different scenarios.

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

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

Beyond annotations, the description discloses key behaviors: ownership enforcement ('you can only cancel your own subscriptions') and the non-destructive nature ('row is deactivated (not deleted)'). This adds significant value beyond the annotations' readOnly=false and destructiveHint=false, clarifying exactly what happens without contradicting them.

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 concise sentences, each adding necessary context: the action, ownership constraint, and soft-delete behavior. It is front-loaded with the verb and resource, and every sentence earns its place 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 mutation tool with one parameter, the description covers the essential facets: what it does, side effects, and ownership conditions. The pointer to recent_alerts provides a complete picture for the agent to select and invoke the tool correctly. No output schema is present, so no return-value explanation is required.

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 id parameter is well-described in the schema as 'Subscription id (uuid) returned by subscribe.' The description does not add further parameter details, which is acceptable because the schema fully defines the only parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Cancel a subscription by id.' This is a specific verb (cancel) with a resource (subscription). It also distinguishes from siblings by noting the soft-delete behavior and referencing recent_alerts for historical events, making its role in the subscription lifecycle unambiguous.

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

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

The description provides contextual guidance: it can only cancel the user's own subscriptions and that deactivation preserves historical events accessible via recent_alerts. This implies the appropriate use case (when you want to stop alerts but retain data), though it doesn't explicitly name alternatives like list_subscriptions or subscribe for other actions.

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 include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail beyond these: the specific verdict list, the distinction between could_not_verify (check did not happen, not evidence) and unsupported (no source), and the two routing paths. 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 dense and information-rich, but somewhat long. Every sentence contributes value, from usage context to return semantics to the important caller note. The front-loaded examples and clear paragraphing help structure it, though it could be slightly trimmed without loss.

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 return values (verdicts, actual value with citation, reasoning), handling of edge cases (could_not_verify vs unsupported), and the two operational paths. With only 2 well-documented parameters, the description covers all necessary context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning: for tolerance_pct, it explains that it 'overrides the tolerance implied by the claim wording' and recommends 1–2 for hallucination detection. The claim parameter is illustrated with concrete examples. This goes beyond the schema's basic definitions.

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

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

The description states a specific verb and resource: 'natural-language claim verification against authoritative sources.' It is clearly distinguished from siblings by focusing on fact-checking claims (e.g., 'fact check', 'verify the claim that…') and explicitly notes it replaces 4–6 sequential calls, making its role unique among the listed 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 is provided: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between financial claims (via SEC EDGAR/XBRL) and other claims, and clarifies when to use tolerance_pct for hallucination detection. No exclusions are needed, but the context is complete.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, which convey safety and idempotency. However, the description adds no behavioral detail beyond those annotations, such as whether it returns a single venue by ID or what happens if no venue is found.

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

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

The description is extremely short, but this is under-specification rather than conciseness. A single vague phrase does not earn its place because it provides almost no useful information to the agent.

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

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

Despite having annotations and an output schema, the description completely fails to explain the tool's core function. The agent cannot reliably determine what 'single venue' means operationally or how it relates to sibling tools, making the description inadequate for correct tool selection and invocation.

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

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

The input schema lists 'id' and 'locale' with 0% description coverage. The description does not explain the meaning or purpose of these parameters, leaving the agent to infer that 'id' identifies a venue and 'locale' might affect localization, but with no explicit guidance.

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

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

The description 'Single venue.' is a noun phrase that merely restates the tool name (Venue) without stating an action. It does not specify whether this tool retrieves, creates, or deletes a venue, nor does it differentiate from sibling tools like venue_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?

There is no guidance on when to use this tool versus alternatives like venue_search, attraction, or event. The description provides no context for choosing this tool in a workflow.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds context beyond annotations by specifying the return payload (venue name, address, city, state, capacity, coordinates, venue id) and the integration point with event_search. 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 entire description is one efficiently structured sentence. It front-loads the API source and search verb, then enumerates accepted filters and return values. No filler words or 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?

With an output schema present, the description needn't detail return structures, but it still summarizes them. It also provides API provenance (Ticketmaster Discovery API), all optional filters, and a downstream usage hint (pass venueId to event_search). Given the tool's search nature and good annotations, 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%, so all six parameters are documented with descriptions. The description merely echoes the parameter list (keyword, city, stateCode, countryCode, postalCode) without adding any new syntax or format details. It does not add meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description starts with 'search venues by keyword, city, stateCode, countryCode, or postalCode' — a specific verb and resource with clear scope. It also names the return fields and explicitly mentions the venue id for use with event_search, distinguishing it from sibling tools like venue (likely a direct lookup).

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

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

The description clearly indicates when to use this tool (when searching venues by various criteria) and provides a workflow hint by stating the venue id can be passed to event_search. It does not explicitly contrast it with alternatives like attraction_search or venue, but the search-oriented wording establishes the intended use case.

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