Brawl Stars

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

Annotations already mark the tool read-only, non-destructive, open-world, and idempotent. The description adds meaningful behavioral and cost context: the default Workers AI model is free, probing Anthropic requires a BYO `_apiKey` and bills the user directly, and returns include per-model score, confidence, signals, and raw_response. This goes well 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 three sentences, front-loaded with the core action and output, and every clause adds useful information: default model, BYO-key cost implication, return structure, and use cases. No filler or redundant wording.

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

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

For a tool with no output schema, the description adequately describes purpose, model options, API-key requirements, return fields, and use cases. It does not explain scoring methodology or error handling, but those are not essential for selecting or invoking 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%, so the baseline is 3. The description adds value beyond the schema by explaining default behavior ('Default model is Workers AI Llama-3.3-70b (free)'), the API-key/cost relationship for Anthropic, and the overall return shape. This is helpful but not exhaustive, as parameter details are already well covered in the schema.

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

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

The description opens with 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model,' clearly stating a specific verb, resource, and measurable output. It distinguishes itself from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring across multiple models.

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 provides clear use contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default vs optional Anthropic model path. However, it does not explicitly state when not to use it or contrast with sibling alternatives, so it stops short of full when/when-not guidance.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description does not contradict them. The description adds useful context by noting that the tool routes internally, fills arguments, and returns citation-bearing structured answers.

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 considerably longer than needed and repeats the same guidance multiple times, such as 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', along with overlapping example lists. It would be stronger if trimmed to a single concise directive with one set of examples.

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

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

For a tool with no output schema, the description sufficiently explains what callers will receive (structured answer with pipeworx:// citation URIs) and how to choose among sibling tools. It also covers aliases and breaking-news fallback cases, so an agent has enough context to invoke it correctly.

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

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

The input schema has 100% description coverage, including all six properties and the alias relationships for the required question. The description adds no new semantic information beyond what the schema already 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 clearly states that ask_pipeworx routes questions to a large set of tools and returns structured answers with citations. It explicitly contrasts itself with web search and sibling tools like ask_pipeworx_grounded and deep_research, giving the agent a specific and actionable purpose.

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

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

It explicitly tells when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). It also mentions breaking-news behavior, providing strong usage guidance.

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

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

The description discloses that it is experimental, a full working router (not a fallback), and that results are compared against the stable router to decide merges. This goes beyond the annotations (readOnly, idempotent, etc.) and sets expectations about behavior 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 somewhat repetitive, e.g., 'same response shape' appears twice, and 'identical' is restated in different forms. It could be more concise, but it is still organized and not excessively long, so a middle score is fitting.

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

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

There is no output schema, but the description states 'same response shape' as ask_pipeworx, leveraging the sibling tool's known behavior. It also mentions comparison to the stable router and the experimental edge, providing enough context for typical usage, though not exhaustively detailed.

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

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

The schema description covers all six parameters, explaining they are aliases for the natural-language question. Since the schema provides 100% coverage and the tool description adds no extra parameter nuance, the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router, and distinguishes it from the stable sibling by noting identical functionality but with experimental routing improvements. The phrase 'universal router' plus the explicit comparison to ask_pipeworx conveys the purpose effectively.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that currently no candidate is active, so it matches ask_pipeworx exactly, which helps decide between stable and beta versions. This gives clear situational 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 establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds valuable behavioral context beyond annotations: it details the refusal mechanism (refusal_reason values like not_in_source, tool_error, data_truncated), the evidence-verbatim-quote output, and the extra LLM call cost — all behaviors an agent needs to predict side effects and failure modes.

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 purpose and every sentence earns its place: purpose, routing behavior, extraction mechanism, return/refusal shape, usage conditions, and cost trade-off. It is dense but not padded; the only mild over-specification is the parenthetical list of example high-stakes domains, which is brief and illustrative rather than redundant.

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

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

Despite lacking an output schema, the description compensates by fully specifying the return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and the refusal enum, so an agent can anticipate both success and failure outputs. Combined with explicit usage guidance and cost awareness, the tool is operationally well-described for its complexity level.

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

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

Schema coverage is 100% — all six parameters (question plus five aliases q, text, input, query, prompt) are described, with each alias explicitly labeled 'Alias for question.' The description adds no further parameter nuance, but with full schema coverage the baseline 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 opens with a specific purpose — 'Hallucination-resistant answer mode for high-stakes reads' — and uses a clear verb ('EXTRACTS the answer') tied to a distinct resource behavior. It explicitly differentiates from the sibling ask_pipeworx by emphasizing evidence-cited, source-grounded answers versus casual lookups, making the tool's role 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?

Usage guidance is explicit and actionable: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' directly states when to choose this tool. It also gives the negative case — 'prefer ask_pipeworx for casual lookups' — and explains the trade-off ('Costs one extra LLM call'), leaving no ambiguity about 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?

The description discloses rich behavioral details beyond the readOnly/openWorld/idempotent annotations: resolver contract with match confidence, blocking statuses (low_confidence_match, market_closed_or_inactive), wide-spread tradeability warnings, news fallback flags, and cancellation-rule risk. These are significant operational behaviors not inferable from annotations alone.

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

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

The description is long but organized with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.). It front-loads the core purpose and usage. While verbose, the length is justified by the tool's complexity, though it could be trimmed without losing value.

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

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

With no output schema, the description compensates thoroughly by detailing response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extractor, news field fallback logic, and safety statuses. It also covers edge cases like wide spreads and cancellation rules, making it complete for a complex tool.

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

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

The input schema already has 100% coverage with descriptions for all three parameters (market, depth, include_raw) and examples. The description reinforces these (e.g., market slug/URL/question text) but does not add new parameter-level meaning beyond what the schema provides. 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 first sentence states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' The classifier list (crypto_price, fed_rate, etc.) and fan-out examples further distinguish it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly says: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool. It does not name alternatives or provide exclusions, but the niche is well-defined.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds context about the response content (name, star powers, gadgets) and source ('official API'), which goes beyond the annotations. No unknown side effects or caveats are mentioned, but this is acceptable given the annotation coverage.

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

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

The description is a single, tightly worded sentence that conveys the tool's purpose and output. It includes no filler and is front-loaded with the API context.

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

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

For a simple single-entity lookup with an output schema available, the description is adequately complete. It covers the essential function and return values. It does not differentiate from sibling tools, but this is a minor gap given the tool's simplicity.

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

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

The schema has a single required 'id' of type number. The description adds that it is a 'numeric ID' for a brawler, which gives minimal semantic meaning beyond the schema. It does not explain the ID's range, origin, or how to obtain it, so the compensation for low schema coverage is limited.

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

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

The description clearly states it provides detailed information for a single Brawl Stars brawler by numeric ID, listing specific return fields (name, star powers, gadgets). This differentiates it from the sibling 'brawlers' tool by emphasizing 'single brawler'.

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

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

The description implies usage for looking up a specific brawler's details, distinguishing it from the plural 'brawlers' tool by the singular/plural distinction. However, it does not explicitly state when not to use the tool or name alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and side-effect expectations. The description adds context about the data source ('official API') and the data structure (list with ID, name, star powers, gadgets), which helps set expectations about the response content. This goes beyond the annotations 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 a single, compact sentence that front-loads the key information: it is the official Brawl Stars API and returns a complete list of brawlers with specific attributes. No filler or redundant phrasing; every word contributes to understanding the tool's purpose and output.

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

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

Given the tool has no parameters, a rich set of annotations, and an output schema, the description fully covers what the tool does and what it returns. The description explains the return fields explicitly, which complements the output schema. For a simple list endpoint, this is complete; no additional behavioral notes are necessary.

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

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

The tool has zero parameters, so there is nothing to document. The schema coverage is 100% (empty schema). The description correctly focuses on the return payload rather than parameters, which is appropriate for a no-argument tool. Baseline for 0 params is 4.

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

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

The description clearly states the tool provides a complete list of all brawlers with specific fields (numeric ID, name, star powers, gadgets). This is a specific resource (brawlers) with a clear scope (all, complete list), distinguishing it from the sibling tool 'brawler' which likely targets a single brawler.

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

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

The description implies the tool is for retrieving the full roster of brawlers, which is a clear use case. However, it does not explicitly contrast with alternatives like 'brawler' or 'rankings_brawlers', nor does it mention when not to use this tool. Usage context is implied rather than explicitly stated.

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, which covers the safety profile. The description adds the list of returned fields, which is useful context, but no details on rate limits, authentication, or edge cases. No contradiction with annotations.

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

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

The description is a single, focused sentence that directly states the purpose and key return fields. Every word earns its place, with no filler or redundancy.

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

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

Given the tool's simplicity (one parameter), the presence of annotations, and an output schema, the description is adequate. It would be more complete with explicit usage guidance or alternative tool references, but the current level of detail is sufficient for a basic profile lookup.

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

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

The schema has only 'tag' with no description, so coverage is 0%. The description clarifies that the tag is a club tag, and the example '#2CCCCCCCC' provides format guidance. This compensates partially, but the description does not fully specify valid tag formats or special characters.

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 the tool returns a 'full club profile' for a club tag and lists specific fields, clearly indicating the resource and scope. It lacks an explicit verb but is still understandable. It differentiates from sibling tools like 'club_members' by focusing on the overall profile rather than a membership list.

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 given on when to use this tool versus alternatives such as 'club_members' or 'rankings_clubs'. The description implies its use for fetching club details, but it does not state exclusions or reference 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 readOnly/openWorld/idempotent/non-destructive, covering the safety profile. The description adds valuable behavioral context: it explains pagination via limit/after/before cursors and specifies the exact member fields returned, going 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?

Two concise, information-dense sentences front-load the purpose and field list while also covering pagination. No filler or redundancy.

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

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

With an output schema present and strong annotations, the description adequately covers the operation, parameters, and pagination. The tool's complexity (4 params, 1 required) is well addressed.

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

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

Schema description coverage is 0%, so the description carries the burden. It identifies 'tag' as the club identifier and explains 'limit/after/before' as pagination cursors, though it could elaborate more on cursor semantics (e.g., positional vs. value-based).

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 'paginated member list for a club tag' and enumerates the returned fields (name, tag, trophies, role, name color), making the tool's purpose specific and distinguishable from sibling tools like 'club' (club info) and 'player' (individual data).

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

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

The description gives clear context: use this for a club's member list when you have a club tag. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of full usage guidance.

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

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

Annotations already declare safe read-only behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. This goes well beyond the annotation hints.

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

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

The description is somewhat long but every sentence carries value: trigger phrases, data sources, edge cases, sorting, and output. It is front-loaded with user intent patterns, staying efficient despite its 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 explains what is returned (paired data + citation URIs) and how results are ordered. It also specifies per-type data fields, covering both parameters thoroughly and making the tool understandable without additional lookup.

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 meaningful semantics: it explains what each type ('company' vs 'drug') pulls (financials vs adverse events/approvals), and gives examples of values. This enriches the bare enum/array 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 clearly states it performs side-by-side comparison of 2–5 companies or drugs in one call, with explicit trigger phrases. It distinguishes itself from sequential single-pack lookups and sibling tools by emphasizing parallel execution and scope.

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 guidance via trigger phrases and 'ALWAYS PREFER over sequential single-pack lookups.' However, it does not name specific alternative tools or provide when-not-to-use conditions, leaving a slight gap in exclusion guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with the description, which adds substantial behavioral detail: second-hop iteration, gap recovery, contradictions[], semantic excerpting, citation_uri resolvability, and timing. No contradictions exist between description and annotations, and the description enriches understanding of the tool's behavior.

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

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

The description is long but information-dense, with each sentence contributing useful details (capabilities, comparisons, depth semantics, timing, citation behavior). It is well-structured, though slightly repetitive in contrasting ask_pipeworx multiple times. Overall concise for the complexity it covers.

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

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

Despite lacking an output schema, the description fully explains the return format (findings packet, hop field, citation_uri, contradictions[], gaps[]) and operational details like timing and excerpting. It provides all context an agent needs to decide and use the tool effectively.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description adds extra context beyond the schema by elaborating on depth behaviors (quick=3, standard=3 with gap recovery, thorough=6 paid) and emphasizing that 'question' is natural language. The added value is moderate but meaningful, hence a 4.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources, decomposing questions and returning findings. It explicitly distinguishes from sibling tools by calling out ask_pipeworx for single lookups and breaking news, and notes 'this is NOT open-web 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 gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' and when not to use it: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also explains depth options and expected timing, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, establishing the operation is safe and repeatable. The description adds valuable behavioral context beyond annotations: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and each result is 'ready to call directly, no second schema lookup needed.' This gives the agent a clear expectation of the return payload and usability. It does not, however, detail pagination or error behavior, which for a discovery tool with no output schema could be useful but is not critical.

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

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

The description is moderately sized but every sentence serves a purpose: purpose, use cases, return behavior, and priority. The domain list is a bit long but informative. It is front-loaded with the core purpose and uses clear sentence structure, so no wasted words.

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

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

Given the lack of an output schema, the description thoughtfully explains what the tool returns (top-N tools with names, descriptions, and full input schemas). It also covers usage context, aliases, and priority guidance. It is complete enough for a discovery tool: the agent knows what to expect, when to use it, and how to act on the results. Minor gap: no mention of the 'limit' parameter behavior, though the schema covers it.

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

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

Schema description coverage is 100%: every parameter (q, task, limit, query, search, description) has its own description with the query parameter documented in detail. The description adds no new parameter semantics beyond restating the alias behavior, which is already in the schema. The baseline of 3 is appropriate because the schema does the heavy lifting and the description does not 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 opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly differentiates itself from siblings by being a discovery meta-tool, and the rest of the description elaborates on the kinds of tools it can find (SEC filings, financials, FDA drugs, etc.). This is a clear, non-tautological statement of purpose.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: [list].' It also gives priority guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides a clear decision rule for when to invoke 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?

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing behavioral nuances: patents soft-fail due to API sunset, empty FDA sections are expected for small-molecule companies, empty sections are 'real no data, not a bug,' and private companies return resolved:false with an explicit notes line. It also explains sources_used/sources_failed. This is exemplary 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 information-dense and front-loaded with examples, but it is a single monolithic paragraph that is exceptionally long. Every clause adds value, yet it could be better structured with sections or bullets for scanning. It is adequate but not concise in form.

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

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

Given the tool's complexity and the absence of an output schema, the description remarkably covers all necessary context: return fields, source list, edge cases, fallback behavior, failure semantics, and accepted input formats. An agent has enough information to invoke this tool correctly and interpret its results without further lookups.

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 meaningful extra semantics by stating that 'type' accepts 'company' or 'ticker' interchangeably with the same value shapes, and that value can be a ticker, zero-padded CIK, or company name resolved via SEC EDGAR. This goes beyond the schema's field descriptions.

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

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

The description opens with concrete user phrasings and a precise definition: 'full cross-source profile of a US public company in ONE parallel call.' It clearly states the tool compiles data across SEC, XBRL, patents, contracts, FDA, H-1B, news, and GLEIF, distinguishing it from simple single-source lookups. This is a specific verb+resource with clear scope.

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

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

The description explicitly says to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides trigger phrasings like 'Tell me about X' and 'brief me on Tesla.' It does not mention sibling tools like compare_entities or resolve_entity, so the when-not guidance is only partial, but the core usage context is clear.

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

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

The word 'Current' hints at a temporal snapshot (vs historical), which is a tiny behavioral trait beyond the strong annotations (readOnly, openWorld, idempotent). However, nothing is disclosed about return type, size, or interpretation. The description adds almost no behavioral context beyond what annotations already imply.

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 three words, it is extremely brief, but this is under-specification rather than conciseness. It lacks the substance needed to justify its brevity; the phrase does not earn its place with useful 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?

Even though the output schema exists, the description is too vague to understand what 'events rotation' means or why an agent would call this tool. No context about the domain, expected results, or relationship to sibling tools is provided, making the tool effectively opaque.

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 and schema coverage is 100%. Per the rubric, 0 parameters earns a baseline of 4. No parameter descriptions are needed since there are none.

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 'Current event rotation.' is a noun phrase that simply restates the tool's name 'events_rotation' without any verb or action. It fails to specify what the tool does, what an 'event rotation' is, or how it differs from siblings. This is a tautology.

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 or which alternatives to consider. With 40+ sibling tools, the description gives zero context for selection or exclusion.

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 destructiveHint and idempotentHint. The description adds context about what is destroyed ('a previously stored memory') and the specific reasons for deletion, including clearing sensitive data. This goes beyond the basic annotation flags 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 short, information-dense sentences. The core action is front-loaded, followed by usage guidance and related tool references. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple single-parameter delete operation with strong annotations (destructive, idempotent), the description provides purpose, usage scenarios, and relationships to sibling tools. No output schema exists, but the behavior is adequately covered without needing return-value details.

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

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

Schema coverage is 100% with 'key' described as 'Memory key to delete'. The description adds the nuance that the key refers to a 'previously stored memory', implying a relationship with the 'remember' tool. This reinforces the parameter's purpose and lifecycle context, slightly exceeding the schema baseline.

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

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

The description clearly states the action ('Delete') and the resource ('memory') with the method ('by key'). It distinguishes itself from sibling tools like 'remember' and 'recall' by focusing on removal, making the purpose unambiguous.

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

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

The description gives explicit conditions for use ('when context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with 'remember' and 'recall' as related tools. However, it does not explicitly contrast when to use 'recall' for retrieval vs 'forget' for deletion, so it falls slightly short of full guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and 'Output is a single text blob ready to drop at site-root/llms.txt.' This goes beyond annotations to describe output format and intended placement.

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: purpose, process/output, and use cases. No filler, front-loaded with the primary action, each sentence adds unique value.

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

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

With 2 well-documented params, no output schema, and full annotations, the description sufficiently covers the input, process, output format, and common use cases. It even names the destination filename (site-root/llms.txt).

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 100% of parameters with descriptions (url, max_links with default/max). The description only mentions 'key links' in the output, which loosely relates to max_links, but adds no additional parameter-level detail beyond the schema. 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 clearly states 'Generate a production-ready llms.txt file for any URL' – specific verb (Generate), resource (llms.txt), and scope (any URL). It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation rather than visibility scanning.

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

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

The description lists explicit 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 provides clear context for when to use. It doesn't mention alternatives or when not to use, 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds behavioral details beyond the annotations: it lists the exact returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifies the scope as the caller's own subscriptions. It also implicitly discloses that only active subscriptions are returned by default, matching the include_inactive parameter semantics.

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

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

The description is three sentences, front-loaded with the core action, followed by a concise list of return fields and a clear usage directive. No wasted words.

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

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

For a simple list tool with a single optional parameter and no output schema, the description covers the purpose, return format, and usage scenario. Combined with the schema and annotations, an agent has all needed 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?

The schema fully documents the only parameter (include_inactive) with a default value, so schema_description_coverage is 100%. The description itself does not mention this parameter, so it adds no additional meaning beyond the schema; baseline 3 is appropriate.

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

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

The description uses a specific verb 'List' with a resource 'the caller's active subscriptions' and enumerates the return fields. It distinguishes from sibling tools by explicitly framing this as a review step before adding more subscriptions or finding an id to cancel.

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

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

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and implies alternatives (subscribe/unsubscribe) without needing to name them.

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?

With only negative annotations, the description carries the full burden and excels: it discloses the claim_token flow for anonymous filing, how to later retrieve status, the daily rate limit, that it is free, and that feedback influences roadmap. No annotation contradiction.

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

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

The description is substantial but every sentence serves a purpose: purpose, categories, exclusions, claim_token mechanics, rate limit, and quota impact. The most important information is front-loaded, and there is 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 the tool's moderate complexity (4 params, nested object, no output schema), the description fully explains the feedback lifecycle, response behavior, constraints, and scope. It leaves little ambiguity about what happens when the tool is invoked and how to follow up.

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 beyond the schema by explaining the practical claim_token usage pattern and the 'don't paste the end-user prompt' guidance, though most parameter meaning is already in the schema.

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

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

Opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling research/query tools by naming concrete use cases (bug, feature, data gap, praise) and explicitly scoping to Pipeworx tools.

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

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

Provides explicit when-to-use guidance for each feedback type and an explicit when-not-to-use: if the tool came from a different MCP server, file it there instead. It also gives a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists') and practical constraints like rate limits.

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

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

Annotations already mark it read-only/idempotent, and the description adds valuable context: derived from CF analytics-engine, no PII, and caching behavior (5min-1h). This goes beyond basic safety flags and helps the agent understand data provenance and timeliness. 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 slightly longer than necessary but well-structured, with a curiosity-provoking opening, clear function statement, numbered use cases, and a data note. Each sentence contributes value; no fluff is present.

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 read-only tool with one optional parameter and rich annotations, the description covers purpose, use cases, return contents (top tools/packs/count), data source, privacy, and caching. It is sufficient even without 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 only parameter (window) is fully documented in the schema with its enum and semantics, including the trade-off between short and long windows. The description repeats this but doesn't add new parameter-specific information, 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?

The description clearly states it returns trending data (top tools, top packs, and total call volume) and frames it as 'What other AI agents are calling on Pipeworx right now.' This distinguishes it from sibling tools like discover_tools by focusing on aggregate real-time usage rather than static discovery.

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

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

Three explicit use cases are listed, giving clear guidance on when this tool is beneficial: discovering hot data sources, confirming canonical popularity, and aligning with agent needs. However, it doesn't mention specific alternatives or exclusions, so it's a 4 rather than 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 readOnly, idempotent, and safe behavior. The description adds value by enumerating the exact return data (trophies, club, brawler count, wins, experience level), giving the agent a clear picture of the response shape beyond the structured hints. 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?

A single, front-loaded sentence that conveys the API, the operation, the parameter format, and the key return fields. No filler or redundant content.

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

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

This is a simple one-parameter read-only tool with a rich output schema and comprehensive annotations. The description covers the essential return content and parameter meaning. It could mention error behavior (e.g., invalid tag) but that's a minor gap.

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

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

The input schema has zero description for the 'tag' parameter, so the description carries the burden. It clarifies the parameter with a real example (#9LJ2YR9…) and states that it's a Brawl Stars player tag, effectively compensating for the sparse 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 specifies the action (retrieving a full profile) and resource (a Brawl Stars player tag), and lists concrete fields returned. It distinguishes itself from siblings like player_battles and rankings_players by focusing on overall profile stats.

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 a player's full profile is needed) but does not explicitly state exclusions or name alternative tools. The field list provides implicit differentiation, but no direct guidance about when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the 'recent' scoping and 'official API' context but does not mention limits, pagination, or authentication. No contradiction.

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

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

One clear, front-loaded sentence that immediately names the resource and then lists the data fields. Every word contributes value, no padding.

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 one-parameter read-only tool with an output schema, the description is mostly complete. It names the scope ('recent battle log') and includes key result fields. A minor gap is not specifying how far back 'recent' goes or any limit on number of battles, but the output schema likely provides structure.

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

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

Schema has 1 parameter (tag) with 0% description coverage. The description only says 'player tag' without explaining the format or encoding, leaving the example '#ABC123DEF' in the schema to carry the burden. This does not compensate for low schema coverage.

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

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

The description uses a specific verb (retrieves) and resource (recent battle log for a player tag) and enumerates the data fields returned. It clearly distinguishes from sibling tools like 'player' (likely profile) and 'events_rotation'.

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 the tool (when you need a player's recent battle history) but provides no explicit alternatives, exclusions, or 'when not to use' guidance. The sibling list is not referenced in the description.

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

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

The description goes far beyond the annotations. It discloses the fill-check behavior and the critical caveat that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' It also explains internal filtering (Jaccard similarity threshold, placeholder slug filtering) and that the tool may return null signals. This is rich behavioral context that the read-only/idempotent hints do not 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 exceptionally well-structured, with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) that make it scannable. Every paragraph adds substantive information, and the opening sentence front-loads the purpose. The length is justified by the complexity, though it could be trimmed slightly without losing 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?

Despite the absence of an output schema, the description outlines the response structure (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, etc.). It covers all three operation modes, filtering rules, similarity thresholds, and the arbitrage fill-check caveat. For a complex tool with multiple modes and edge cases, the description is exceptionally 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 schema already covers both parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful examples for each parameter, clarifies mode selection (e.g., 'event (recommended for a specific market)'), and explains the semantics of each mode in detail. While it doesn't introduce entirely new parameter fields, it enhances the practical understanding of how to use event vs. topic.

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 precise action: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly states what the tool does and its method, and the mention of 'arbitrage' distinguishes it from sibling tools like polymarket_edge_tracker (which tracks edge movements) and polymarket_fill_risk (which assesses fill risk).

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?

Usage guidance is explicit and prescriptive: 'Call with NO args for a `trending_scan`... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also explains when to use each mode (event for a specific market, topic for cross-event), provides concrete examples, and directs to an alternative tool ('For custom sizing use polymarket_fill_risk'). This leaves no ambiguity about when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: caching ('Cached 1h at the KV level'), output structure (by_segment, _diagnostics), internal gates (e.g., partition placeholder fraction skipping), and the fed-candidates exclusion logic with rationale. This goes well beyond 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 effectively organized with uppercase section labels, making it scannable, but it is very lengthy and contains details that are not essential for invocation (e.g., per-sport alpha values, Run 8 gate relaxation history). It is verbose, so it does not earn the higher end of the scale.

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

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

Despite having no output schema, the description fully specifies the response top-level keys (by_segment, fed_candidates/fed_note, _diagnostics) and their meaning, including edge-case handling like 'why a segment is empty' and the 24h-move warning. This gives callers everything needed to understand the 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 description coverage is 100% with detailed parameter descriptions already present (e.g., min_liquidity, max_spread_pp). The tool description mentions the knobs but only restates their purpose; it does not add meaning beyond the schema. Thus the baseline 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 opens with a clear and specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes the tool from siblings by detailing its three response segments (model_driven, structural_arbitrage, concentrated_longshot) and its focus on discovery, which is not present in sibling descriptions like polymarket_arbitrage or bet_research.

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 states the intended use case ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets'), which gives clear context for when to invoke this tool. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it falls short of 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?

Adds substantial operational context beyond annotations: snapshot writes on cache-miss causing gaps, 60-day TTL bound, and decay computed from daily closes of edge_pp_net net of default slippage. No contradiction with readOnlyHint or other annotations.

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

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

Description is long but well-structured with purpose, args, response, and limits. Each section provides necessary details—the response format is particularly valuable given no output schema. No fluff.

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

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

Covers purpose, parameters, exact response structure (tracked, expired, snapshot_dates), and limitations (TTL, data gaps, computation basis). Sufficient for an agent to understand expected behavior and interpret results, even without 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?

Schema already documents both parameters completely (lookback days, window family). Description merely restates defaults and adds the phrase 'snapshot family', which does not add meaningful semantic value beyond the schema.

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

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

States that it provides 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers 'how long has this edge existed and is it shrinking?', distinguishing it from current-edge 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?

Clearly frames the use case with 'a fresh wide edge and a 3-week-old wide edge are different trades', implying when to leverage historical persistence. It does not name an alternative explicitly but the context is evident from the 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, openWorldHint, idempotentHint, and non-destructive. The description goes far beyond that, detailing mode-specific behavior: how size_usd is interpreted differently in single vs basket modes, what fields are returned (top_of_book, vwap_fill_price, slippage_pp, etc.), and the risk of partial basket fills. It adds crucial context about forced directional risk and the meaning of verdicts (clean|degraded|cannot_fill), which is not captured by annotations. No contradiction.

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

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

The description is long, but every section earns its place: core purpose, required parameters, single-market behavior, basket behavior, and usage context. It is front-loaded with the primary operation and structured around modes. The density is high, though a slightly more structured format (e.g., bullet lists) could improve scannability without losing 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 no output schema, the description must explain return values, and it does thoroughly for both modes: top_of_book, VWAP, slippage, shares filled, max fillable, theoretical vs realizable sums, capture ratio, per-leg details, thin_legs, and forced directional risk. It also covers prerequisites, thresholds, and worst-case risk scenarios. Given the tool's complexity, the description is complete and self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful nuance: it clarifies the mutual exclusivity of market vs event, explains side defaults per mode (auto in basket), and details the varying interpretation of size_usd (spend vs proceeds vs settlement notional). This goes beyond the schema's parameter descriptions, elevating the 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 a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage (which finds arb) and polymarket_edges (which lists edges) by framing it as the verification/risk-check step. The two distinct modes (single-market and basket) are explicitly named and explained.

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

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

Explicit when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books not capturable, partial fills create directional risk), which helps the agent reason about both usage and exclusion. Alternative tools are named, making decision-making straightforward.

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 annotations already declaring read-only, idempotent, non-destructive behavior, the description adds extensive behavioral context: pairing_unverified is always set, unclassified legs are never paired, temporal_alignment null means unparsed rather than aligned, spreads are gross of Kalshi fees, and non-equivalent bet shapes invalidate the signal. This goes well 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 thorough and logically organized by field labels and codes, but it is extremely long and contains redundant temporal-alignment caveats and repeated warnings. It earns its place mostly, but the token cost is high and the structure is one dense wall of text rather than tight, scannable prose.

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 present, the description carries the full burden of explaining return behavior, and it succeeds: it covers leg-by-leg prices, top_spreads_pp, compatibility codes, skipped counters, temporal_alignment semantics, fee disclosure, and low-confidence inspection paths. An agent has all necessary context to call and interpret 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?

Schema coverage is 100%, so the schema already documents all three parameters. The description adds meaningful context beyond that: topic is a set of pre-mapped shortcuts that auto-fetch events, explicit kalshi_event_ticker and polymarket_event_slug support custom pairings and override the mapped side, and both modes run the same matcher. This is more than the baseline schema-only case.

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 resource: a cross-venue spread between Kalshi and Polymarket for the same resolving question, and details two operation modes and the output shape. It does not use an explicit action verb like 'compute' and does not explicitly contrast itself with sibling tools such as polymarket_arbitrage, so it stops short of 5.

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

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

The description gives clear when-to-use guidance for both modes, explains that explicit tickers override topic mappings, and warns strongly that returned pairs can still carry compatibility warnings and that pre-mapped topics are not automatically tradeable. However, it never names an alternative sibling or explicitly says when to use a different tool, so the 'vs alternatives' component is missing.

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, so the safety profile is known. However, the description adds no behavioral context beyond the word 'rankings'—it does not disclose pagination behavior, ordering, filtering scope, or what exactly the returned rankings represent. The 'Country' qualifier is the only additional context, but it is minimal and does not describe underlying 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 extremely concise but not in a useful way—it is a short noun phrase that sacrifices clarity for brevity. It lacks a subject-verb structure and reads more like a subtitle than a functional description. This is under-specification rather than effective conciseness.

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

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

With five parameters, no parameter documentation, and no behavioral details, the description is grossly incomplete. While an output schema exists, it does not compensate for the lack of input semantics and tool purpose. The agent cannot infer when to use this tool or what it returns beyond the tautological phrase.

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

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

Schema description coverage is 0%, so the description must compensate for the five parameters (after, limit, before, brawlerId, countryCode). It provides no information about parameter meanings, formats, or relationships. The description is entirely unhelpful for understanding what values are expected or how parameters interact.

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 'Country brawler rankings' is essentially a restatement of the tool name, lacking a verb or explicit action (e.g., 'retrieve', 'list'). It adds only the 'Country' modifier, which is already implied by the required 'countryCode' parameter. It does not distinguish the tool from siblings like 'rankings_clubs' or 'rankings_players' beyond the resource name.

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, what scenarios it fits, or how it differs from alternatives. There are no explicit exclusions or references to sibling tools. The only implied usage is that it relates to brawler rankings, but no context is given about when to prefer this over similar rankings 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 provide readOnlyHint, idempotentHint, and destructiveHint=false, establishing this as a safe read operation. However, the description adds no extra behavior information beyond what annotations imply. It does not describe pagination behavior, data scope, or any caveats, so the burden is on the annotations alone.

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

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

The description is extremely under-specified. While it is short, it is not conciseness—it omits essential information. A useful description would be at least one full sentence covering the tool's action and key parameters. The current fragment does not earn its place as it provides no actionable value.

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

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

Given the tool has 4 parameters (1 required) and an output schema, the description is severely incomplete. It fails to explain what 'rankings' means, how the parameters interact, or what kind of data will be returned. The output schema exists but does not compensate for the absence of any explanatory text. This is inadequate 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?

Schema description coverage is 0%, leaving the description to explain parameters. It fails to do so: the description is a single vague phrase with no mention of after, limit, before, or countryCode. There is no explanation of what these parameters control, making it impossible for an agent to construct correct arguments based on the 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?

Description is 'Country club rankings.' which merely restates the title 'Rankings Clubs' in a slightly different word order. It lacks a verb or explicit action, making it a noun phrase rather than a clear instruction. It also does not distinguish from sibling tools like rankings_brawlers or rankings_players.

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. There is no mention of appropriate contexts, prerequisites, or exclusions. The description gives no hint about how countryCode, limit, before, and after should be used or why one would choose this over rankings_players.

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

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

The annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral details such as pagination, sorting, or response structure, leaving the tool's runtime behavior largely undisclosed.

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 appropriately concise. For a tool with four parameters and no other documentation, a single noun phrase does not earn its place as an adequate description.

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 (four parameters, no schema descriptions) and the existence of an output schema, the description still fails to explain how to use the tool effectively. It lacks parameter semantics, usage context, and behavioral notes, making it incomplete for an agent to select and 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?

With schema description coverage at 0%, the description needed to compensate by explaining the parameters. It only hints at countryCode via 'Country' and says nothing about limit, after, or before. This is insufficient for a four-parameter tool.

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

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

The description 'Country player rankings.' names a resource and implies a retrieval operation, but it lacks a specific verb and does not clearly differentiate from sibling tools like rankings_brawlers or player. It is more than a pure tautology because it adds the 'Country' filter, but it remains vague about what the tool actually returns.

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 such as player, player_battles, or rankings_brawlers. The description provides no context about typical use cases, prerequisites, 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 cover read-only and non-destructive traits. The description adds valuable context about scoping to an identifier and the ability to list all keys, 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 two sentences, front-loaded with the primary action, followed by usage context and scoping. Every sentence contributes, 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?

The description covers purpose, when to use, scoping, and relationship to sibling tools. For a single-parameter read-only tool, 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 the key parameter is fully documented in the schema. The description adds the tip to omit the key to list all keys, but this is also present in the schema description, adding minimal extra meaning.

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

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

The description clearly states the tool retrieves a previously saved value or lists all keys, using a specific verb and resource. It also distinguishes from siblings by referencing remember and forget.

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

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

The description explicitly says when to use the tool ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and names alternatives: 'Pair with remember to save, forget to delete.'

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

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

There is a direct contradiction with the annotations: readOnlyHint=true conflicts with the description's disclosure that setting mark_read:true will flag events as read, modifying state. The description otherwise provides useful context (payload fields, polling safety), but the contradiction invalidates 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 compact and front-loaded with the primary action. Each sentence adds necessary information: return content, filtering, mark_read behavior, and the alternative feed URL. No wasted words.

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

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

Despite no output schema, the description explains what each returned event carries (source, citation_uri, raw payload) and covers the key parameters. However, it does not mention limit or unread_only, though those are in the schema. The contradiction with annotations also slightly undermines overall completeness, but the description itself is sufficiently informative for a polling 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 already has 100% coverage with descriptions for all parameters, but the tool description adds valuable clarification: it gives a concrete type filter example ("sec_8k") and explains the mark_read side effect in operational terms, exceeding the schema's baseline.

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

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

The description clearly states the tool's function: pulling fired events from a subscription feed. It specifies the resource (alerts feed) and the action (pull), and distinguishes itself from sibling tools by focusing on alert retrieval rather than subscription management or other data.

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

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

The description notes that polling works fine and offers an alternative endpoint (registry.pipeworx.io/alerts.json) for scripts and dashboards, implying the tool is for agent-context use. It also explains mark_read behavior for subsequent calls, but does not explicitly contrast with sibling tools like list_subscriptions or recent_changes.

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 significant behavioral details beyond annotations: it fans out to SEC EDGAR, GDELT/GNews fallback, USPTO with PatentsView sunset soft-fail, and returns structured changes[] with citation URIs. These add useful context that annotations (readOnly, openWorld, idempotent) do not cover, making the tool's runtime behavior transparent.

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, front-loaded with the core purpose, and each segment adds relevant detail (sources, fallbacks, formats, output). While it is one long sentence with many clauses, it avoids fluff and earns its length, but could be slightly better structured for 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?

There is no output schema, so the description appropriately explains what the tool returns ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers edge cases like GDELT preference, GNews fallback, and USPTO soft-fail, making it complete for a multi-source 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% for all three parameters, so the schema already explains them well. The description adds value by providing concrete examples for 'since' ('7d', '30d', '3m', '1y') and clarifying that 'value' can be a ticker or CIK. This is helpful beyond the schema descriptions, though not heavily necessary given the high coverage.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with concrete examples like 'What's new with X' and 'updates on Acme'. It also distinguishes itself from the sibling tool entity_profile by explicitly stating when to use that instead, fulfilling differentiation.

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

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

The description gives explicit usage guidance: use for recent changes/news/filings, and explicitly directs to entity_profile when the static profile is needed. This clearly delineates when to use this tool versus an alternative, satisfying the dimension.

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 significant behavioral context beyond the annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and it pairs with recall/forget. This enriches the idempotentHint and destructiveHint already provided, offering retention and scoping specifics not present in structured data.

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

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

The description is three sentences long, front-loads the purpose, and each sentence earns its place: purpose/usage, storage mechanics, and pairing with sibling tools. No filler 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?

For a simple two-parameter memory store with no output schema, the description covers purpose, usage context, persistence behavior, and integration with recall and forget. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the input schema already fully documents key and value. The description reinforces the key-value concept and gives practical examples, but it does not add new semantics beyond the schema. Per baseline rules, a 3 is appropriate when the schema carries the descriptive load.

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 — across this conversation or across sessions.' This clearly states what the tool does and distinguishes it from sibling tools like recall and forget by explicitly naming them as counterparts.

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 when you discover something worth carrying forward... so you don't have to look it up again.' It mentions alternatives (recall, forget) but does not explicitly contrast with them or state when not to use this tool. Thus, it has clear context but lacks 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral context beyond those: it reports unresolved identifiers explicitly under 'unresolved', returns 'figi_candidates' on ambiguous matches, labels identifiers with their source, and degrades gracefully when GLEIF or OpenFIGI is unavailable. No contradiction with annotations 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?

The description is long and dense, with heavy parenthetical nesting in the company-type section, but it is front-loaded with purpose and clear first-use guidance. Nearly every sentence adds operational detail—sources, failure behavior, input caveats—so the length is mostly justified despite some editorializing like 'replaces 2-3 manual lookups.'

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 does the work of explaining what the tool returns: CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, and brand, plus the 'unresolved' field and 'figi_candidates' ambiguity behavior. It also covers edge cases like ISIN-to-LEI mapping, non-US issuers, and degraded enrichment, making it complete 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?

Even though schema coverage is 100%, the description adds meaning the schema lacks: the 'value' parameter gets crucial guidance to pass the entity name only, with the counter-example 'NEW YORK ST DORM AUTH revenue bonds' explaining why trailing security-class words fail. It also documents accepted input forms for company (ticker, CIK, ISIN, name) and drug (brand or generic), going well beyond the schema's enum and one-line 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 opens with concrete user phrasings ('What's the ticker for…', 'find the CIK for…') and then states a specific verb+resource action: resolve a user-spoken name to canonical/official identifiers. It clearly scopes the tool to company and drug entity types, which differentiates it from siblings like entity_profile and compare_entities even without naming them.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when the tool is appropriate versus when it returns candidates rather than asserting an answer. However, it does not explicitly name alternatives or state when not to use this tool, so it misses the top-tier 'when-not/alternatives' bar.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds that it internally calls ai_visibility_check per entity, ranks results, and returns a ranked list with score, confidence, and signal density, which is valuable beyond the safety hints.

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 main action, no redundant wording. The example query adds practical value without bloat.

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 clearly states the return structure (ranked list with score/confidence/signal density) and covers the main behavior. Minor gaps like exact scoring scale or error handling, but adequate for the tool's complexity.

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

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

All parameters are documented in the schema (100% coverage), and the description adds the crucial semantics that the first entity is the 'subject' and the rest are competitors, plus explains the effect of the 'models' option. This enriches the schema's baseline.

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

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

The description clearly states this tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks by score. This distinguishes it from single-entity tools like ai_visibility_check and other comparison 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?

It explicitly frames the use case as competitive AI-marketing audits with an example query ('does Claude know about us as well as our competitors?'). It implies you should use this when comparing multiple entities rather than single probes, but doesn't explicitly exclude alternative tools.

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

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

Beyond the readOnly/idempotent annotations, the description discloses composite fan-out, partial failure degradation, a 5-30s first-measurement latency for bundlephobia, and the sources_failed field. This provides valuable operational 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?

While the description is relatively long, it is densely packed with necessary information: purpose, usage, output structure, ecosystem limitations, and failure behavior. The structure front-loads the main idea and each subsequent clause adds value.

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

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

For a composite tool with no output schema, the description enumerates the summary fields, per-advisory details, links, and alternative versions, and covers latency and failure modes. This is comprehensive.

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 100% of the parameters with descriptions, and the description doesn't add new parameter-level semantics beyond referring to the overall use case. 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 opens with a clear composite 'should I add this npm package' check and identifies the two data sources (deps.dev and bundlephobia). This verb+resource combination is distinct from sibling tools like scan_competitor_ai_presence and validate_claim, making its 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?

Explicitly states when to use: "Use whenever an agent asks 'is X safe / popular / small'..." and gives a direct alternative for other ecosystems (PyPI/Maven/Cargo/Go via deps.dev:version directly), so it covers both when-to-use and 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the embedding model (BGE-base-en), windowing (500-char overlapping windows), the 200K char cap, and truncation-flagging. It also explains the return format (offsets and similarity scores), which is behavior not captured in annotations.

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

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

Four dense sentences, each serving a purpose: action, use case, sibling pairing, and technical constraints. No filler — it's front-loaded with the core action.

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

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

The description covers purpose, when-to-use, technical behavior, return format, and a sibling pairing, which is complete for a tool with no output schema and only 3 params. The 200K cap and offset detail address the main operational concerns an agent would have.

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

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

Schema coverage is 100%, so the schema already documents text, query, and limit. The description adds context for the text parameter ('e.g. a SEC 10-K body, an article') but does not provide significant additional parameter-level semantics beyond the schema's own 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 opens with 'Semantic search INSIDE a fetched record', a specific verb+resource. It differentiates from the sibling ask_pipeworx_grounded by explaining the workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 contrasts it with ask_pipeworx_grounded for grounding. This gives the agent a clear decision rule for selecting this tool over 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?

The description goes far beyond the annotations (readOnlyHint false, idempotentHint true) by disclosing authentication requirements, return value (new subscription id), delivery channel behavior (feed always on, email/SMS/webhook options), SMS verification and 10/day cap, and webhook signing secret and auto-disable after 10 failures. 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 but every sentence adds value: purpose, prerequisite, types with examples, and delivery channels with constraints. It is front-loaded with the main action and returns, and the structure logically flows from core to options. No redundant or filler content.

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

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

Given the tool's complexity (3 params, nested objects, 5 types, no output schema), the description covers all essential aspects: what it does, return value, auth requirements, supported types/filters, delivery channels and their caveats. It is self-sufficient and leaves no critical gaps 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 schema already has 100% coverage with detailed descriptions, but the description adds concrete examples for each type (e.g., items:["5.02"] = officer change, topic:"fed", series_id:"UNRATE") and delivery constraints (verified phone, signing secret). This enriches parameter understanding beyond the schema, earning a score above the baseline 3.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb (create) and resource (subscription), and explicitly distinguishes from siblings like list_subscriptions and unsubscribe by describing the creation action and supported event types.

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

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

The description provides clear context on when to use the tool: when you need proactive monitoring. It specifies prerequisites (Pipeworx OAuth account) and supported types. However, it does not explicitly name alternatives or when-not-to-use cases (e.g., for one-time queries use recent_alerts), so it falls short of a full 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 readOnly=true and openWorld=true, so the bar is lower. The description adds behavioral context by explaining what is returned (category-bucketed examples, live catalog, tool+argument shapes) and how to vary output via topic. It does not mention potential response size or rate limits, but these are not critical for a read-only informational tool.

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

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

The description is moderately long but front-loaded with example user queries that make the purpose instantly understandable. Every sentence adds relevant detail (categories, tool shape, usage). It could be slightly tightened, but the structure is effective and not verbose.

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

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

Given no output schema, the description adequately explains the return value: category-bucketed example questions with tool and argument shapes. It covers when to use, how to use, and what to expect. For a simple read-only tool with one optional parameter, this is complete enough. It does not go into exact response structure, but that is not necessary for onboarding context.

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

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

Schema coverage is 100% for the only parameter (topic), so baseline is 3. The description adds 'to focus' and examples like 'finance', 'pharma', 'betting', but these mostly repeat the schema's enum list. The only extra semantic is the 'Omit for a cross-category spread' guidance, which is already implied by the parameter being optional. No significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with exact tool and argument shapes for onboarding. It uses specific verbs ('Returns', 'Call') and distinguishes itself from siblings by positioning as the 'entry point' for learning what Pipeworx can do. It also lists concrete categories, making the scope 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: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also differentiates from meta-tools (ask_pipeworx, entity_profile, compare_entities) and explains how to adjust the call (no args vs. topic). This is clear context beyond the schema.

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 (non-read-only, non-destructive, idempotent), the description adds that ownership is enforced and that the row is deactivated not deleted, preserving historical events. This provides critical behavioral context about side effects and constraints.

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 main action and followed by two important behavioral caveats. No wasted words.

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

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

For a simple one-parameter tool, the description covers purpose, ownership, non-destructive behavior, and the relationship to recent_alerts. With the rich annotations and schema, no further context is necessary.

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

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

The single parameter id is fully described in the schema as a UUID returned by subscribe, so the description adds no additional parameter semantics. Schema coverage is 100%, 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 clearly states the tool cancels a subscription by id, using the specific verb 'cancel' and identifying the resource. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action.

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 context that ownership is enforced and canceling deactivates rather than deletes, which informs when to use it. It doesn't explicitly name alternatives, but the contrast with recent_alerts suggests the consequence of the action. Clear context but 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?

Beyond annotations (read-only, open-world, idempotent), the description reveals the dual-path logic (SEC EDGAR/XBRL vs grounded pipeline), the exact verdict list, citation format, and the critical error semantics (could_not_verify must not be treated as evidence). 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 each sentence carries unique information—trigger examples, purpose, routing logic, return fields, error semantics, and efficiency. It is front-loaded with user-intent examples and ends with a practical note.

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 verdict types, returned values (actual value + pipeworx:// citation + reasoning), and error handling (verification_error field; unsupported definition). It covers both the financial fast path and the general grounded path, making the tool 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 already covers both parameters with detailed descriptions (100% coverage). The tool description adds little direct parameter guidance; it mentions 'exact percent-delta math' but does not elaborate on tolerance_pct beyond the schema. Therefore the description adds marginal value over 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 explicitly names the task ('natural-language claim verification against authoritative sources') with example trigger phrases, and distinguishes it from sibling Q&A tools by framing it as a fact-checker and noting it replaces multi-step lookups.

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

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

Gives an explicit usage condition ('Use whenever the agent needs to check whether something a user said is factually correct'), differentiates handling for company-financial vs other claims, and warns about the meaning of could_not_verify and unsupported, preventing misuse.

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