Clash Royale

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral context: default model and free tier, BYO Anthropic key with direct cost to the user, and the per-model response structure including score, confidence, signals, and raw_response. 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 tightly packed in four sentences, with the primary purpose front-loaded in the first sentence. Every sentence earns its place—covering purpose, default behavior, return format, and use cases without redundancy.

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

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

With no output schema, the description compensates by clearly stating the per-model return fields and the combined view. It also covers cost implications, model selection, and practical use cases, making it sufficient for an agent to select and invoke the tool confidently.

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%, providing full parameter descriptions, so the baseline is 3. The description enriches meaning further by explaining the default model behavior and the cost/BYO implications of '_apiKey', adding value beyond the schema's factual descriptions.

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

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

The description clearly states the tool probes LLMs and scores visibility (0-100) per model, with a specific verb 'probe', resource 'LLMs', and scope covering business/brand/product/topic. It does not explicitly differentiate from the similarly named sibling tool 'scan_competitor_ai_presence', so it falls short of a 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 provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that signal when to use the tool. However, it does not mention when not to use it or reference alternative sibling tools, so it lacks the explicit exclusion criteria needed for 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?

Beyond the readOnly/idempotent annotations, the description discloses significant behavioral details: routes to 5,358 tools across 1,395 sources, fills arguments automatically, returns structured answers with stable citation URIs, is one fast call, and works on every tier. This gives the agent strong expectations of what happens when invoking the 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 lengthy but well-structured, front-loading the key directive and then adding examples and alternatives. Every section earns its place, though it could be tightened to reduce redundancy (e.g., repeated examples of question types).

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

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

Given there is no output schema, the description explains what the agent will receive (structured answer with citation URIs) and how the routing works. It covers most relevant aspects for a query tool, though it omits details about error handling or cases where no authoritative source is found. Overall, it's a solid, complete context for the tool.

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

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

The schema already covers all parameters as aliases for 'question' with 100% coverage, so baseline is 3. The description adds value by giving diverse example phrasings and guidance on natural-language queries, exceeding what the schema alone provides. Still, it doesn't deeply elaborate on parameter formatting nuances, so not a 5.

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

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

The description clearly states this tool answers factual questions by routing to authoritative sources, with a specific verb ('ask') and resource (Pipeworx). It explicitly distinguishes itself from web search and has many concrete examples, making its purpose unmistakable.

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

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

Explicitly instructs to 'PREFER OVER WEB SEARCH' and 'START HERE', and names specific alternatives (ask_pipeworx_grounded, deep_research) for when to step up. Also provides examples of question types and clarifies coverage of breaking news, leaving no ambiguity about when to use this tool versus siblings.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: it is a full working router with no fallback, currently identical to stable because no candidate is active, with candidate routing improvements enabled live under test. This transparency about its experimental edge and dynamic state goes beyond annotations.

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

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

Four sentences, each delivering essential context: beta status, identical behavior, current candidate state, usage guidance, and fallback clarification. It's slightly dense but efficiently structured 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?

Covers purpose, current state, usage, and experimental context. Without an output schema, it references 'same response shape' as ask_pipeworx, which is sufficient given the sibling. The description fully compensates for the lack of output schema by redirecting to the stable tool's behavior.

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

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

Schema has 100% coverage with all six parameters documented as aliases for question. The description adds no parameter-specific details, stating only that arguments are identical to ask_pipeworx. Baseline 3 applies since schema does the heavy lifting.

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 this as the beta version of ask_pipeworx, an identical universal router that routes questions to 5,358 tools. It distinguishes itself from the stable ask_pipeworx by its experimental routing improvements and current state. This specificity makes the purpose unmistakable.

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

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

Explicitly instructs to 'use it exactly like ask_pipeworx when you want the newest routing,' providing a clear when-to-use condition. It also contrasts with the stable router, implying the alternative when experimental edge is not desired. However, it doesn't list other alternatives like ask_pipeworx_grounded.

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

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

Beyond the read-only and idempotent hints in the annotations, the description explains the extraction mechanism, the exact return shape including evidence as a verbatim quote, and the refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). This provides critical behavioral context not captured by annotations.

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

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

The description is well-structured and front-loaded with the core purpose, then provides detailed return behavior and usage trade-offs. It is longer than the HIGH calibration example but every sentence adds necessary information, so a slight deduction for verbosity results in a 4.

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, mechanism, success and failure return shapes, refusal reasons, and usage guidance. Since there is no output schema, the detail on return format is essential and well-provided. It is sufficiently complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, with all six parameters described as aliases for 'question.' The description adds no additional parameter-specific information, so it meets the baseline 3 but does not exceed it.

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

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

The description clearly states it is a 'hallucination-resistant answer mode' that routes through tools and extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded evidence and refusal behavior.

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

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

It explicitly says 'Use whenever an answer will be quoted, cited, or acted on...' and lists high-stakes domains (financial verdicts, legal claims, medical lookups, public statements). It also contrasts with ask_pipeworx, stating 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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 extensive behavioral traits: the resolver contract with market_match_confidence and scores, fan-out parallelism, fallback news behavior with _fallback_attempted, blocking statuses for low-confidence and closed markets, cancellation-rule risk, and wide-spread tradeability notes. This far exceeds what annotations alone provide and helps agents anticipate edge cases.

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

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

The description is long but densely packed with high-value operational details, structured with clear caps-lock section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT) that make it scannable. Every sentence adds operational guidance; there is no filler or tautology.

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

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

Even without an output schema, the description fully documents the response structure (result.market, result.analysis, result.evidence), edge cases (low confidence, closed markets, wide spreads), cancellation-rule parsing, and news fallback. For a complex tool with fan-out and multiple data sources, this is a complete operational manual.

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 3 parameters, so the baseline is 3. The description reinforces the market parameter's flexibility (slug, URL, or question text) and gives examples, but most parameter-level detail (enum meanings, defaults, raw payload size) already exists in the schema. The description adds little new beyond what the schema and its examples convey, so a 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 specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from siblings by covering the full research workflow (resolve, classify, fan out, compare) and states concrete use cases like 'should I bet on X' or 'is there edge in Z'.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', which gives clear context. It also hints at when not to rely on it via safety short-circuit statuses, but it does not name any alternative tool explicitly, so it falls short of full 'when vs alternatives' 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety and behavioral profile is well covered. The description adds that it comes from the official API and lists the returned fields, but does not disclose further behaviors like pagination or rate limits. Given the strong annotation coverage, this is adequate.

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

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

The description is a single, well-structured sentence that front-loads the main purpose ('complete list of all game cards') and then lists the included fields. Every word earns its place with zero unnecessary filler.

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

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

For a simple, parameterless list tool with a rich set of annotations and an output schema, the description is largely complete. It clearly states the resource and return fields. Additional context like pagination or sorting is not needed for a 'complete list' endpoint, though a bit more detail on how the list is ordered could enhance completeness.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Baseline for 0-parameter tools is 4, and the description doesn't need to explain parameters. It adds no parameter-specific info, but none is required.

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's purpose: retrieving the complete list of all Clash Royale cards, with a specific verb ('complete list') and resource ('cards'). It also enumerates the fields returned (name, max level, elixir cost, rarity, type, arena, icon URL), effectively distinguishing it from sibling tools like clan or player.

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 explicit guidance on when to use this tool versus alternatives, nor any mention of exclusions. However, the description implies usage for obtaining the full card list, and for a simple parameterless resource the context is reasonably clear, but it lacks the explicit 'when to use' detail.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a small amount of context by listing what fields are included, but does not disclose any other behavioral traits (e.g., error handling, tag format). It does not contradict the annotations.

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

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

The description is a single, focused sentence that front-loads the API source and the core purpose. It lists fields efficiently without redundancy or fluff, earning its place.

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

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

For a simple, single-parameter read tool with an output schema and rich annotations, the description is adequate. It conveys the core function and field list. It does not describe return values, which is acceptable given the output schema, and does not need to explain safety due to annotations. Minor gaps like tag formatting are covered by the schema example.

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

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

Schema coverage is 0% for the 'tag' parameter, so the description must compensate. It clarifies that the tag is a clan tag, but it does not specify the required '#' prefix format or any validation rules. The example in the schema provides the format, but the description alone adds minimal semantic value beyond the parameter name.

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 retrieving a full clan profile by tag and lists specific fields (name, description, type, score, member count, trophies required, war trophies), which distinguishes it from narrower sibling tools like clan_members or clan_current_war. However, it lacks an explicit action verb like 'retrieves' or 'gets', making the purpose slightly implicit.

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 no guidance on when to use this tool versus alternatives. It does not mention that clan_members should be used for member lists or clan_current_war for war details, nor any exclusions or prerequisites. The context is entirely absent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds the specific output contents, but this is largely redundant with the output schema. It does not add context on rate limits, auth, or other behavioral traits beyond what annotations provide.

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

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

The description is a single, well-structured sentence that front-loads the source ('Clash Royale official API') and the core purpose. Every clause adds relevant detail without 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?

With a simple one-parameter tool, an output schema, and comprehensive annotations, the description sufficiently covers the tool's purpose and scope. It does not mention error cases or prerequisites, but these are not critical given the low complexity and presence of structured metadata.

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 parameter meaning. It only says 'for a clan tag', which merely restates the parameter name without explaining format (e.g., required '#' prefix, encoding) or constraints. The example in the schema is not part of the description, so semantics are inadequate.

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

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

The description states a specific verb+resource: 'current war status for a clan tag' and enumerates the exact data returned (war state, collection-day and war-day results, participants, battles remaining, standings). This clearly distinguishes it from sibling tools like clan_war_log (historical wars) and clan (general info).

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 current war status but does not explicitly contrast it with alternatives like clan_war_log or mention when not to use it. There is no explicit when/when-not guidance, only an implied scope based on the name and description.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral detail about pagination via limit/after/before cursors and the output fields, which is useful beyond the structured annotations.

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

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

Two sentences with no wasted words. Purpose, resource, output fields, and pagination are all front-loaded and fully specified.

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 rich annotations and an output schema present, the description covers the essential context: official API, member fields, and pagination. Nothing critical is missing for a straightforward list operation.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies 'tag' as a clan tag and mentions limit/after/before as cursors, but does not explain their exact semantics (e.g., the meaning of 'after' vs 'before'). This is partial but insufficient for full compensation.

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

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

The description clearly states the verb+resource: 'paginated member list for a clan tag' and enumerates specific fields (name, role, trophies, last active, donations). This distinguishes it from sibling tools like 'clan' or 'clan_war_log' by scoping to member 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 to list members of a specific clan via its tag, with pagination. It does not explicitly mention alternatives or when-not-to-use, but the context is unambiguous given the tool name and description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds meaningful context by noting it's the 'Clash Royale official API' and that it returns trophy counts and member totals. It does not contradict annotations and adds behavioral context beyond them.

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

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

The description is two concise sentences, front-loaded with the tool's purpose and API source, with no wasted words. It efficiently conveys the core functionality and return 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?

Although an output schema exists, the description does not fully cover the parameter space: pagination parameters (after, before, limit) are completely unaddressed. The tool has 8 optional parameters, and the description only hints at the main filters. For a search tool, pagination is significant, so completeness is moderate.

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

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

With 0% schema description coverage, the description must compensate for parameter meaning. It names five of eight parameters (name, locationId, minMembers, maxMembers, minScore) but omits pagination parameters (after, before, limit). This provides partial help but leaves meaningful gaps, so it only partially compensates.

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 action ('search clans') and the resource ('clans'), with a specific list of filters (name, locationId, min/max members, min score). It distinguishes this search tool from siblings like 'clan' (specific clan lookup) and 'rankings_clans' (rankings), 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 provides clear context for when to use this tool: when searching clans by name, location, membership size, or score. However, it does not explicitly mention alternatives or exclusions (e.g., use 'clan' for direct tag lookup), so it stops short of a full usage guideline.

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, establishing the safe read-only nature. The description adds that it is the official Clash Royale API and lists the data content, but does not elaborate on pagination behavior beyond cursor support, so the annotations carry the burden.

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

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

The description is a single sentence that front-loads the purpose and includes essential details about data and cursors. No filler or duplication.

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 annotations summarizing the safety profile, the description is largely complete for selection and invocation. The only minor gap is the lack of explicit alternatives, but given the clear distinction from sibling tools, this is sufficient.

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

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

Schema description coverage is 0%, but the description clarifies that 'tag' is a clan tag and that 'limit/after/before' are cursor parameters. This adds some meaning beyond the raw schema, though it doesn't explain the exact semantics of the cursors.

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 the war log for a clan tag, including past war seasons with participants, battles, wins, and final standings. This specific verb+resource distinguishes it from sibling tools like clan_current_war and clan_members.

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 'past war seasons,' clearly indicating this is for historical data, which implies it is the correct choice over clan_current_war for past conflicts. It does not explicitly name alternatives but provides clear contextual guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which the description complements with rich behavioral detail: pulls SEC EDGAR/XBRL data, handles off-calendar fiscal years, sorts results by primary metric, returns pipeworx:// citation URIs, and replaces 8–15 sequential lookups. This goes well beyond the structured fields.

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 trigger phrases and preference guidance, then organized by type. It is longer than strictly necessary but every sentence adds operational value—metrics, fiscal-year handling, sorting, citations. Slight redundancy between 'ONE parallel call' and 'Replaces 8–15 sequential lookups' prevents a 5.

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

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

Given no output schema, the description fully covers what the agent needs to expect: paired data, citation URIs, sorting behavior, and entity-specific data sources. It also addresses edge cases like off-calendar fiscal years and gives concrete examples, making the tool's behavior predictable and invocation safe.

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 type and values, so baseline is 3. The description adds meaningful semantic context by explaining what each type retrieves (10-K financials for companies, FAERS/FDA/trial counts for drugs), clarifying values as tickers/CIKs vs drug names, and noting the 2–5 range. This enriches the schema without redundancy.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific trigger phrases like 'X vs Y' and 'which is bigger.' It distinguishes itself from sequential single-pack lookups and sibling tools by emphasizing parallel comparison and citing specific metrics per entity type.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong when-to-use guidance. It also distinguishes usage by type (company vs drug) and notes the parallel-call advantage, effectively telling agents when to choose this over sequential alternatives.

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

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

Annotations already mark readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: account and plan requirements, 'this is NOT open-web search,' explicit 'gaps[] for facets the data couldn't answer (never invented),' a contradictions[] scan, semantic excerpting, hop fields, latency expectations (15-90s), and detailed citation behavior. This far exceeds what annotations provide.

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

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

The description is long, but every sentence carries needed information – from prerequisites to use cases to depth behavior to output format to performance. It is front-loaded with the account warning and critical sibling distinction. The length is fully justified for a tool with this many behavioral nuances, and the structure follows a logical progression.

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 bears full responsibility for explaining return values, which it does thoroughly: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]' and details about contradictions[], hop, and citation_uri. Combined with limitations, latency, and depth semantics, the description 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%, but the description enriches both parameters significantly. It explains depth values beyond the schema enum: 'quick=3 (single hop), standard=5 (default; adds a gap-recovery hop ... thorough=8 (paid; adds a full iterative hop).' It also clarifies that the question parameter supports 'broad/multi-part' questions and that decomposition is the point. This adds genuine semantic depth.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources' and explicitly explains it 'decomposes your question into focused facets, routes each to the right one of 5,358 tools IN PARALLEL, and returns a findings packet.' It distinguishes itself from open-web search and from the sibling tool ask_pipeworx, providing a specific verb+resource+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: 'Best for broad/multi-part questions over structured data' and provides exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also warns about account requirements and suggests ask_pipeworx if not signed in. This is a model of usage clarity.

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. The description adds valuable behavioral detail beyond these: it discloses that results include full input schemas with curated examples, that results are directly callable without a second schema lookup, and that it returns a top-N ranked set. This contextualizes the return format without contradicting annotations.

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

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

The description is four sentences, front-loaded with the core purpose, then expands with use cases, return behavior, and a directive. Each sentence serves a distinct function, though the domain list makes it slightly longer than strictly necessary. It is well-structured for an agent to parse.

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

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

Given that there is no output schema, the description fully explains what the tool returns: top-N tools with names, descriptions, and full input schemas with examples. It also conveys the meta-positioning (call FIRST for discovery) and provides a concrete list of supported domains. This is sufficiently complete for an agent to know when and how to invoke it, and what to expect from the result.

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% descriptor coverage for all six parameters, including aliases for the main query field. The description does not add new parameter-level semantics; it only restates the natural-language query concept. It indirectly references the limit parameter through 'top-N,' but this is not a significant enhancement over the schema's own documentation.

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 'Find tools by describing the data or task,' which clearly identifies the tool as a discovery/search utility. It is immediately distinguished from sibling tools by its meta-purpose and explicitly lists many domains (SEC filings, FDA drugs, stocks, etc.) that the agent can query about.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies exclusions by saying 'not just one answer,' but does not name specific alternative tools for direct lookup scenarios.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses key behaviors: it fans out across multiple sources, soft-fails on patent API sunset, uses a GDELT→GNews fallback, and sorts fundamentals by period_end DESC. These details materially help the agent understand execution 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 a dense block but front-loaded with user-facing examples and the critical preference instruction. Every sentence adds useful context, though it could be better structured (e.g., bullet points) for readability. It is slightly long but not bloated.

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

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

Given there is no output schema, the description compensates by detailing exactly what will be returned (fields, sources, URIs), the input constraints, and failure modes (patents sunset, fallback chain). This provides a complete mental model for a complex 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?

The input schema already provides full descriptions for both parameters, including examples ('AAPL', '0000320193') and the restriction that names are not supported. The description repeats these examples but adds no new semantic information beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'full cross-source profile of a US public company in ONE parallel call' and enumerates the specific data returned (CIK, filings, fundamentals, patents, news, LEI). This is a specific verb+resource+scope that distinguishes it from sibling tools like compare_entities or resolve_entity.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides a concrete alternative: 'use resolve_entity first if you only have a name.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, so the agent knows it's a destructive, idempotent operation. The description adds context about clearing sensitive data but doesn't disclose additional behavioral traits beyond the annotations. 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 three short sentences, each earning its place: purpose, usage guidance, and relationship to sibling tools. 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?

For a simple one-parameter tool with no output schema and strong annotations, the description covers purpose, usage, and complementary tools. It is fully adequate 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?

Schema coverage is 100%, and the schema adequately describes 'key' as 'Memory key to delete'. The description only says 'by key', which adds no new semantics beyond the schema. Thus the 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 'Delete a previously stored memory by key' with a specific verb and resource. It also differentiates from siblings by framing it as the counterpart to 'remember' and 'recall', making it distinct.

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

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

The description explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember' and 'recall', giving clear context and relationships to 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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral detail by explaining it fetches the page, extracts content, and outputs a text blob, which goes beyond the annotations. This is useful context about the operation's side effects (network fetch) and output format.

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

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

The description is efficiently written in three sentences, front-loading the core purpose. The 'Useful for' list adds practical guidance without redundancy. Every sentence contributes value, making it both concise and well-structured.

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

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

For a relatively simple tool with full schema coverage and annotations, the description covers the operation, use cases, and output format. No output schema exists, but the description explicitly states the output is a single text blob ready for site-root/llms.txt, which is sufficient.

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

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

Schema coverage is 100%, so the parameters url and max_links are already well described. The description adds minimal extra meaning, only noting 'any URL' and the output location, which doesn't significantly enhance parameter understanding. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific process steps (fetch, extract, emit). It distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on generating the llms.txt file itself.

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 use cases (client site, own project, competitor audit) and implies when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds that it returns the caller's subscriptions and lists the exact fields, which is useful but does not add deeper behavioral details like pagination or rate limits.

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

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

The description is two sentences: the first states what it does and the return format, the second provides usage guidance. Every part earns its place with no redundancy or filler.

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

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

For a simple read-only list tool with one optional parameter, the description covers the purpose, return fields, and use cases. Annotations provide the safety profile, so there are no significant gaps.

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

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

Schema description coverage is 100% for the only parameter (include_inactive), with a clear description. The tool description does not add extra parameter semantics beyond reinforcing that only active subscriptions are returned by default.

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

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

The description uses the specific verb 'List' with a clear resource: "the caller's active subscriptions." It also enumerates the returned fields, and the sibling list (subscribe/unsubscribe) makes it obvious this is the read-only counterpart. This fully distinguishes it from related tools.

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

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

The description states explicit use cases: "review what you're monitoring before adding more" and "to find an id to cancel." It does not mention when not to use it or alternative tools, but the context from sibling names clarifies its role.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds only context about the data returned (name, country code, region type), but no extra behavioral disclosures such as authentication requirements or rate limits.

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 with no filler. Every word contributes: source (Clash Royale API), scope (single location), input (numeric ID), and output fields are all included.

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 lookup with a full output schema and safety annotations, the description is sufficient. It specifies the resource, input, and return fields, leaving no major gaps for an agent to 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?

With schema description coverage at 0%, the description compensates by explaining that the 'id' parameter is a numeric location ID. It adds meaning beyond the raw schema ('id' as number) by linking it to 'single location'.

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

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

The description clearly states the tool returns details for a single location by numeric ID, naming the specific fields (name, country code, country/global region). This distinguishes it from sibling tool 'locations' (plural) by emphasizing 'single location'.

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 single-location lookups via 'single location' and 'numeric ID', but does not explicitly state when to use it over alternatives like 'locations'. No when-not or alternative tool is mentioned.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context: it discloses the tool returns a list of supported IDs, covers countries and global, and identifies its relationship to ranking endpoints—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?

A single, well-structured sentence that immediately communicates the tool's purpose and scope. No filler or redundant information; every phrase 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 parameterless, read-only list tool with complete annotations and an output schema, the description covers all necessary angles: what it returns, what data it contains, and how it is used. Nothing essential is missing.

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

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

The tool has zero parameters and the schema is empty, so the description isn't required to explain params. The baseline for 0 params is 4, and the description appropriately focuses on the output semantics rather than parameter details.

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

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

The description clearly states what the tool does: returns a full list of supported location IDs (countries + global) for use with ranking endpoints. It names specific sibling tools (rankings_clans, rankings_players) that consume this data, distinguishing it from the singular 'location' tool.

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

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

The description provides clear context: this tool supplies location IDs needed by ranking endpoints. It doesn't explicitly say when not to use it or mention alternatives like the 'location' tool, so it misses the upper bound for exclusionary guidance, but the intent 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?

Despite annotations being generic (all false), the description adds meaningful behavioral context: rate limit of 5 per identifier per day, free/no quota impact, and that the team reads digests daily. This goes beyond the structured 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 four sentences, each carrying distinct value: what the tool does, when to use it, how to frame the feedback, and the rate limit. No filler, though slightly longer than necessary.

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

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

For a simple feedback tool with no output schema, the description covers all key aspects: purpose, usage triggers, content guidelines, and constraints like rate limiting. It is fully sufficient for an agent to decide when and how to invoke 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?

The input schema already fully covers all parameters with descriptions. The description adds extra guidance for the 'message' parameter (e.g., describe in terms of tools/packs, don't paste prompts), which enhances semantic 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 sends feedback to the Pipeworx team about broken, missing, or desired items. The verb 'Tell' and resource 'Pipeworx team' are specific, and the tool is distinct from all data-retrieval siblings.

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

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

Explicitly enumerates when to use: for bugs, feature requests, data gaps, or praise. It also provides guidance on what not to do (don't paste end-user prompts) and confirms there are no similar 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it explains that the data is a self-aggregating signal derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window, which helps set expectations about data recency.

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

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

The description is front-loaded with the main purpose, followed by a bulleted list of use cases and additional context. Each sentence adds value, though the use-case list is slightly verbose. It is structured and readable without being overly terse.

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

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

With no output schema, the description compensates by stating what is returned (top tools, top packs, volume) and the tuple structure (pack, tool, count). It also mentions caching and data provenance. This is sufficient for a simple read-only tool, though it could be more explicit about exact response formatting or limits.

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 parameter 'window' with a description explaining its meaning and default. The tool description adds a minor note about caching depending on window, but this is more behavioral than semantic. Since the schema already provides full clarity, a baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: it returns the top tools, top packs, and total call volume over a window. The phrase 'What other AI agents are calling on Pipeworx right now' gives a specific, distinct purpose that differentiates it from sibling tools like discover_tools or suggest_questions.

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

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

The 'Useful for' section lists three concrete use cases, such as discovering hot data sources and confirming a popular tool before asking a question. This provides clear guidance on when to use the tool, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds value by specifying the data returned and noting it's an official API, which implies potential rate limits or auth. 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?

A single, well-structured sentence that leads with the tool's purpose ('full profile') and then lists key returned data. No fluff or repetition of schema/annotations.

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 available and only one parameter, the description sufficiently covers invocation and return value scope. It's complete for a simple read-only profile 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 has zero description coverage for the 'tag' parameter, but the description explains the tag format using '#2PP…', giving the agent necessary context. This compensates for the schema gap.

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

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

The description clearly states the tool fetches a full player profile for a Clash Royale player tag, listing specific data (trophies, level, arena, clan, cards, battle stats, ranking). This differentiates it from siblings like player_battles and player_upcoming_chests.

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 is implied by 'full profile' but there is no explicit guidance on when to use this versus alternatives. It doesn't state exclusions or name other tools, so coverage of when-to-use is only implicit.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable context beyond these, including that it is from the 'official Clash Royale API', returns the 'last ~25 battles', and specifies the included data fields. No contradictions with annotations.

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

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

The description is a single, well-structured sentence that front-loads the source ('Clash Royale official API') and the core function ('recent battle log'). It conveys the key details without any wasted words, making it highly concise and readable.

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

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

Given the tool's simplicity (one parameter, read-only, with an output schema), the description covers the essential behavior and result content. It mentions the approximate count of battles and the data fields, though it does not address potential error cases or rate limits. Overall, it is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 0% (the schema only provides the parameter name and type), so the description carries the full burden. It says 'for a player tag' but does not explain the tag format, whether the '#' is required, URL-encoding needs, or any constraints. The example in the schema helps, but the description itself adds minimal semantic value beyond what the parameter name already implies.

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

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

The description clearly states the tool returns 'recent battle log for a player tag' and lists specific data fields (outcome, decks, opponent, arena, trophy change), making the purpose unambiguous. It also distinguishes itself from sibling tools like 'player' and 'player_upcoming_chests' by focusing specifically on battles.

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

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

The description implies usage when you need a player's recent battles, and the 'for a player tag' phrase suggests the input requirement. However, it provides no explicit guidance on when to use this tool over alternatives such as 'player' or 'rankings_players', nor any exclusions or prerequisites.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that this is from the official Clash Royale API and specifies the returned data (chest type and position index). It does not contradict annotations, and any additional behavioral details like rate limits are absent but not critical given the annotations.

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

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

The description is a single, concise sentence that front-loads the key context (official API) and immediately states the tool's purpose. Every word earns its place, with 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?

For a simple one-parameter read-only tool, this description is adequate. Rich annotations and an output schema cover safety, and the description clarifies the core purpose. It does not address every possible edge case, but none are critical for this level of complexity.

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

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

The only parameter, 'tag', is described as a 'player tag' in the description, but no format specifics (e.g., # prefix) are provided. The schema example includes '#2P8888R', which partially compensates, but the description itself adds minimal meaning beyond the parameter name.

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 retrieving the upcoming chest cycle for a player tag, with specific mention of chest type and position index. It distinguishes this from sibling tools by focusing exclusively on chest cycle data, though it lacks an explicit verb like 'get' or '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?

Usage is implied: use when you need a player's upcoming chest cycle given their tag. However, there is no explicit guidance on when to use this tool versus alternatives, nor any mention of alternatives 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 declare readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral detail: it explains the partition filter, placeholder-slug handling, the fill check that can veto a trade when realizable_edge_pp ≤ 0, and the skipped_low_similarity counter. This goes well 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 long but densely packed with essential information for a complex two-mode tool. It is front-loaded with purpose and uses clear uppercase markers for semantic anchors. While every sentence carries value, the length and technical density prevent a perfect score; it could be tightened without losing critical detail.

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

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

Given there is no output schema, the description fully explains the response structure, including opportunities[], partition_check fields, and the fill check results. It covers parameterless behavior, both modes, filters, and when not to trade. For a tool of this complexity, the description is complete enough for an agent to use 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?

Although the input schema already covers both parameters, the description significantly adds meaning: it provides concrete examples of event slugs ('fed-decision-may-2026'), states that full URLs are accepted, and clarifies the difference between event and topic modes. This enriched semantic context helps the agent select the right parameter and format.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This precisely states what the tool does and distinguishes it from sibling tools like polymarket_edges (single edges) or polymarket_fill_risk (fill risk), which are clearly related but different.

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 mode selection guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It recommends 'event' for a specific market and explains that cross-event mode catches patterns single-event misses. It also points to polymarket_fill_risk for custom sizing, explicitly naming an alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds substantial context that is not in the schema: caching behavior (1h KV-level cache keyed on knobs), live warning about 24h price movement, the fact that Fed bets are excluded from ranking due to unreliable signals, and diagnostic counters to explain why a segment is empty. This gives the agent a robust understanding of the tool's behavior, edge cases, and side effects.

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

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

The description is extremely dense, but it is not overly concise: nearly every sentence carries meaningful information about model families, gates, knobs, or response structure. The front-loaded first sentence gives immediate clarity, and the detailed breakdown of segments is valuable for a complex tool. It could be slightly better structured with bullet points, but the information density justifies the length.

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

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

For a tool with 9 parameters, no output schema, and multiple nested concepts (segments, Kelly fractions, filters, diagnostics), the description is remarkably complete. It explains response top-level structure, why a segment might be empty, the tradeability constraints, and the caveat about Fed bets. There is no obvious missing information that would prevent an agent from calling the tool correctly or interpreting its output.

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

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

Schema coverage is 100%, but the description goes far beyond what the schema provides. It explains the interplay between parameters (e.g., min_partition_leg_kelly compensates for partition_overround parent-level kelly_fraction_half=0), clarifies that min_edge_pp is evaluated net of slippage, and gives concrete advice for max_spread_pp and min_liquidity with example values like 2 and 5000. This semantic enrichment is exactly what parameter descriptions should add.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately conveys core function and its purpose ('what should I bet on today'), and clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by emphasizing the Pipeworx data disagreement and the suite of knobs/filters.

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

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

The description clearly states the intended use: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains which segments appear and how knobs like min_liquidity and max_spread_pp shape results. It does not explicitly name alternatives or say when not to use this tool versus siblings, but the context is clear enough for an agent to select it for opportunity discovery.

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, openWorld, idempotent, non-destructive), the description discloses detailed behaviors: the response structure (tracked/expired/snapshot_dates), the 60-day TTL limit, the fact that decay is computed from daily closes not intraday, and the meaning of gaps in snapshot_dates. This fully informs the agent about edge cases and data 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 long but well-structured with labeled sections (ARG, RESPONSE, LIMITS). Every sentence adds useful information, and the structure aids scanning. It is not as tight as a two-sentence description, but the complexity justifies the length.

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

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

Given the complexity of the tool (time-series telemetry) and lack of output schema, the description is remarkably complete. It explains what the response contains (tracked, expired, snapshot_dates), how each field is computed, and the limitations (TTL, daily closes). It fully equips the agent to use the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the schema already defines both parameters. The description adds value by clarifying 'days' as lookback with a max of 30 (not just clamp 2-30) and describing 'window' as a 'snapshot family' (24hr/1wk/1mo), which gives meaning beyond the raw schema. It does not repeat every schema detail, but adds contextual nuance.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?'), uses a specific verb (tracker/telemetry), and differentiates itself from sibling tools like polymarket_edges by focusing on temporal persistence rather than edge generation.

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 this tool by contrasting a fresh wide edge with a 3-week-old wide edge, suggesting this tool provides historical context. It also explains that snapshot gaps mean no scan happened, which helps interpret results. However, it does not explicitly name alternative tools or state when NOT to use it, 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?

The description goes far beyond the readOnlyHint/idempotentHint annotations by detailing exactly what the tool returns (top_of_book, vwap_fill_price, slippage_pp, verdict) and how it behaves (walks the ladder). It also discloses a critical risk: partial basket fills 'convert an arb into an unhedged directional position', which is precisely the behavioral context needed for safe execution.

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

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

The description is dense and long, but every sentence provides functional value for a complex dual-mode tool. It uses keywords like SINGLE-MARKET and BASKET to separate sections, though a bulleted list or headings would improve scannability. The slight lack of visual structure prevents a 5, but there is no genuinely redundant text.

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

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

Given the tool's complexity, the absence of an output schema, and the presence of four nuanced parameters, the description covers all necessary aspects: both modes, parameter interpretations, return fields, risk warnings, and usage triggers. It is fully self-contained 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?

Although the schema already describes each parameter, the description adds essential semantic nuance: `size_usd` is interpreted differently in single-market (spend/proceeds) versus basket (settlement notional per share). It also clarifies the `side` parameter's default auto behavior in basket mode, which is not inferable from the schema alone.

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

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

The description uses a specific verb 'check' against a clear resource ('live CLOB order-book depth') and identifies two explicit modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk/realizability rather than opportunity detection.

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

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

Explicitly instructs to use this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also provides clear guidance on when to use each mode (market vs event) and the side defaulting logic, leaving no ambiguity about tool selection.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive; the description adds substantial behavioral context beyond that. It discloses the compatibility_warning logic in two specific failure modes, temporal_alignment semantics, skipped_cross_type/subtype counters, and the message that pre-mapped shortcuts often yield no tradeable spread. This gives the agent rich information about what to expect and how to interpret results, far exceeding baseline 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 dense and structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS), and every sentence adds meaningful detail. It is longer than average but the complexity of the tool (cross-venue, safety warnings, temporal alignment) justifies the length. It loses one point because some parenthetical asides could be tightened without losing meaning, e.g., the repeated 'no arb exists' phrasing, but overall it is well-organized and front-loaded with the core purpose.

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

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

Even without an output schema, the description fully covers expected response structure (leg-by-leg prices, top_spreads_pp), the meaning of safety fields (compatibility_warning, temporal_alignment, skipped_cross_*), and edge cases (non-equivalent bet shapes, semantically unrelated events). Given the tool's complexity and the lack of a structured output definition, the description is remarkably complete and self-sufficient.

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

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

Schema coverage is 100% for all three optional parameters, but the description enriches them significantly. It explains the 'topic' parameter by listing all ten allowed shortcut values, describes how kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, and gives realistic format examples (e.g., 'KXFED-26OCT', 'fed-decision-in-june-825'). This goes well beyond the schema's basic descriptions and clarifies the relationship between parameters.

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

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

The description opens with a clear, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the two venues, the metric (spread), and the scope (same resolving question), immediately distinguishing it from sibling tools. It also explains the two distinct modes (topic shortcuts and explicit tickers) and what the output contains, making the tool's 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 provides clear context for when the tool is meaningful (when bet shapes are equivalent) and when it isn't (when shapes mismatch, warning fires), plus a caveat that most pre-mapped topics are not tradeable. However, it doesn't explicitly name alternative tools or state 'use this instead of X,' so it lacks the explicit when-not/alternatives guidance needed for a 5. The modes are well explained, so the user knows how to invoke it appropriately.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it is the official API and lists the returned fields (clan name, tag, score, member count, rank position), but does not disclose pagination or sorting behavior beyond 'top-ranked'. This adds moderate value but not rich behavioral context.

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

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

The description is exactly two sentences: the first delivers the primary purpose and output fields, the second provides a key parameter hint. No wasted words, and critical information is front-loaded.

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

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

This is a simple list tool with an output schema, strong annotations (read-only, idempotent, open world), and a clear one-line description of the data returned. For its complexity, the description plus structured metadata is fully sufficient — nothing necessary is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that locationId is numeric and that 'global ID' is used for worldwide rankings, which gives meaningful semantic guidance for that parameter. However, the 'limit' parameter is not addressed in the description, leaving it undocumented in both schema and description.

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

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

The description states a specific action ('top-ranked clans for a location ID') and resource (clans), and distinguishes from the sibling 'rankings_players' tool by focusing on clans. It also clarifies the numeric location ID and global ID usage, 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?

It provides clear context for when to use the tool (for location-specific top clan rankings) and gives explicit guidance to 'Use global ID for worldwide rankings'. However, it doesn't name alternative tools or explicitly state when NOT to use this tool, so it falls short of the highest 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 communicate read-only, idempotent, and non-destructive behavior. The description adds context by listing the returned data fields and noting it's the official API, which is useful but not exhaustive (e.g., no pagination behavior mentioned).

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

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

Two concise sentences deliver the essential purpose and a usage hint without redundancy. The information is front-loaded and every word serves a purpose.

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

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

For a simple read-only tool with an output schema present, the description sufficiently covers scope, fields, and location semantics. It omits limit details but that 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 description explains locationId meaning and the global ID special value, but does not describe the 'limit' parameter at all. With 0% schema coverage, this partial compensation is adequate but leaves a gap.

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

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

The description clearly states the tool returns top-ranked players for a given location, listing specific fields (name, tag, trophies, etc.). The scope is explicit and the name distinguishes it from sibling rankings_clans.

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 a usage tip ('Use global ID for worldwide rankings') but does not explicitly differentiate when to use this tool vs alternatives like rankings_clans. The guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: the dual mode (retrieve vs. list), scoping to an identifier (anonymous IP, BYO key hash, or account ID), and the relationship to previous remember calls. This goes beyond 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?

Three well-structured sentences: the first states the core action, the second explains when/why to use it, and the third covers scoping and relationship to sibling tools. No wasted words; each sentence carries distinct information and the description is front-loaded.

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

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

Given the tool's simplicity (one optional parameter), the description covers the primary behaviors (retrieve vs. list), provides real-world use cases, and explains scoping. It does not specify the return format or error behavior, but annotations and the schema cover the rest, and the absence of an output schema means some simplification is acceptable. Naming remember and forget completes the workflow context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes the schema's note about omitting the key to list all keys, and adds examples of key values ('target ticker, an address, prior research notes'), but these examples are illustrative rather than adding formal meaning beyond the schema's 'Memory key to retrieve (omit to list all keys)'.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes the tool's dual function and differentiates it from sibling tools like remember (save) and forget (delete).

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 explicit use cases: 'look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names companion tools ('Pair with remember to save, forget to delete'), but does not explicitly state when not to use it or name an alternative for lookups not stored via remember.

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, so the agent knows it's a safe read operation. The description adds extra behavioral context: the persisted feed semantics, that mark_read:true will affect future calls (consuming the events), and the citation_uri format. It also discloses that events carry source and citation_uri. This goes beyond annotations, though it doesn't detail rate limits or error behavior. No contradiction, so a 4 is appropriate.

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 purpose, and each sentence earns its place: first gives action and resource, second adds key return fields and filtering, third adds mark_read semantics and alternative access. No fluff, well-organized.

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

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

Given the tool has 5 optional parameters, full schema coverage, and no output schema, the description provides necessary context: return fields, filtering examples, mark_read behavior, and the alternative HTTP endpoint. It's complete for a read-only polling tool. It could mention pagination or limits, but the schema does cover limit. Since annotations cover safety, the description is sufficient. A 4 is justified because no output schema exists, and the description fills the gap with the return payload content.

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

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

Schema coverage is 100%, so all five parameters are documented with descriptions. The tool description itself does not repeat parameter details, but it adds meaning by mentioning example type ('sec_8k'), ISO timestamp format, and the effect of mark_read. This is baseline 3 because the schema already has full coverage; description provides some real-world context but doesn't deeply compensate for anything missing.

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: 'Pull fired events from your subscription feed.' It clearly identifies the resource (subscription feed alerts), the action (pull/return), and distinguishes it from siblings by specifying it returns alerts from the evaluator's persisted feed with details like source and citation_uri. It also mentions filtering options, setting it apart.

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 usage context: it says 'Polls work fine' and explicitly mentions the same feed is accessible at a URL for scripts/dashboards, suggesting when this tool is appropriate. It also implies when to use it (when you want the persisted feed) as opposed to the HTTP endpoint. However, it doesn't explicitly name alternative tools or scenarios where a sibling tool would be preferred, so it's clear 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?

The description richly discloses behavioral details beyond the annotations: it fans out to SEC EDGAR, GDELT→GNews fallback (with rate-limit/5xx conditions), and USPTO (including PatentsView sunset and soft-fail behavior). It also describes the return structure (changes[] grouped by source, total_changes count, citation URIs). This adds substantial value beyond the readOnlyHint/openWorldHint/idempotentHint annotations.

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

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

The description is lengthy but every sentence earns its place: opening query examples, source fan-out with fallback logic, parameter details, return format, and sibling alternative. It is front-loaded with the most useful usage examples and contains zero 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 complexity (multiple data sources, fallback behavior, date formats, custom return structure) and the lack of an output schema, the description is remarkably complete. It covers source behavior, fallback triggers, soft-fail handling, parameters, return shape (changes[], total_changes, citation URIs), and when to choose an alternative 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?

Although the schema already documents all three parameters, the description adds crucial semantic meaning: `since` supports ISO or relative shorthand with concrete examples ('2026-04-01', '7d', '30d'), plus a suggested default ('Use "30d" or "1m" for typical monitoring'). It also clarifies `value` can be a ticker or zero-padded CIK, and `type` is limited to 'company'.

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 serves as a change feed for a company over a time window, with specific verbs and scope ('what's new with X', 'changes feed for a company in the last N days'). It explicitly distinguishes itself from the sibling `entity_profile` by pointing to that tool for static profiles, 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?

Provides explicit when-to-use guidance through query paraphrases and an explicit alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This goes well beyond implied usage and directly helps an agent choose among 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 cover idempotency and non-destructiveness. The description adds meaningful context: scoping by identifier, persistence differences for authenticated vs anonymous sessions (24-hour retention), and the key-value storage model. However, it doesn't specify behavior on overwriting existing keys or any size limits, so not a 5.

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 strict conciseness but every sentence adds value: purpose, usage, storage format, persistence, and related tools. It's well-structured and front-loaded with the core function.

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 write tool, the description covers what, when, how, persistence, and related tools. No output schema is needed for a save operation, and the operational details are sufficiently complete for an agent to use it correctly.

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

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

Schema coverage is 100% with descriptions for both key and value. The description enriches this with concrete examples of keys (ticker, address, preference) and clarifies the value accepts 'any text', going beyond the schema's basic details.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' – a specific verb and resource. It distinguishes itself from siblings by explaining it stores key-value pairs for future reuse, and explicitly pairs with recall and forget.

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

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

It provides explicit usage context: 'Use when you discover something worth carrying forward' with concrete examples. It also names the companion tools for retrieval and deletion, offering clear guidance on alternatives.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns specific fields (ticker, CIK, RxCUI), includes citation URIs, auto-disambiguates input, and mentions internal cascading through multiple endpoints. This goes well beyond the annotations and informs the agent about performance and output richness.

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 well-structured with example phrasings up front, then detailed type breakdowns. Every sentence conveys useful information; it is dense but not redundant. However, it could be slightly more concise by trimming the example queries without losing clarity.

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

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

Given the tool has two entity types with distinct return payloads and no output schema, the description thoroughly covers what is returned for each type, including the exact fields and citation URIs. It also explains the internal cascade and disambiguation, making the tool's behavior fully understandable for the agent.

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

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

Schema description coverage is 100% as both 'type' and 'value' have detailed descriptions in the schema. The description adds example values and explains auto-disambiguation, but this is supplemental rather than essential to understanding the parameters. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: resolving a user-spoken NAME to a canonical/official identifier. It provides multiple example queries ('What's the ticker for...', 'find the CIK for...') and explicitly lists supported entity types with what each returns, distinguishing it from other tools that consume these identifiers.

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

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

It gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when it applies by listing supported types. It doesn't explicitly state when not to use it, but the 'use first' directive and the context that other tools require these IDs suffice as clear 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. The description adds behavioral context beyond that: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. This helps the agent anticipate the tool's multi-probe behavior and output structure, though it doesn't mention potential rate limits or API key handling (though _apiKey is in schema).

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

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

The description is three sentences, front-loaded with the core purpose, then method, use case, and return format. Every sentence contributes necessary information without repetition or fluff. The quoted user question adds practical value without bloating the 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?

With no output schema, the description states exactly what is returned (ranked list with score, confidence, signal density per entity), which is critical. It also explains the process (probing each entity, ranking) and gives a concrete scenario. The 4 parameters are covered by the schema, so the description fills the missing context for expected outputs and usage 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%, so the baseline is 3. The description reinforces the meaning of 'entities' (your brand + competitors, first as subject) but that is already in the schema. It adds minimal extra semantic value beyond the schema, primarily the note that it probes with ai_visibility_check, which slightly enriches but does not significantly compensate beyond the structured 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 the tool's purpose with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It also explains the mechanism (probes each entity with ai_visibility_check, ranks by score) and distinguishes itself from the sibling ai_visibility_check by focusing on multi-entity comparison.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' and gives an example question. It implicitly contrasts with single-entity queries by mentioning probing each entity with ai_visibility_check, but it does not explicitly state when not to use it or name alternative tools for single-entity checks.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds substantial context beyond annotations: acknowledges partial failure modes, notes bundlephobia's first measurement can take 5-30s, lists sources_failed for timeouts, and describes graceful degradation. This gives the agent an accurate mental model of runtime behavior.

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

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

The description is a dense, single paragraph but well-structured: core purpose → usage → return values → constraints → failure behavior. It is longer than minimal but every sentence earns its place for a composite tool with no output schema. Slight deduction because it could be broken into clearer sections, but it is 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?

This tool has no output schema, so the description carries full responsibility for explaining returns. It lists the summary block fields, per-advisory detail, links, and alternative versions, and also covers latency and partial failure behavior. For a composite tool with rich output, this is complete and well-rounded.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds some value by implying 'package' is an npm name and version defaults to latest, but this largely mirrors the schema. No additional syntax or format details are provided beyond what the schema states, so a baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb+resource: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It distinguishes itself from potential alternatives like validate_claim or bet_research by focusing on npm package evaluation, and explicitly scopes to NPM ecosystem.

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 given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion: NPM only in v1, with other ecosystems directed to deps.dev:version directly, which clearly separates this tool from broader dependency 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 destructiveHint=false. The description adds significant context beyond these: it discloses the embedding model (BGE-base-en), the use of 500-char overlapping windows, the 200K char cap with truncation and a flag, and that each passage includes an offset for verification. This transparency about limits and behavior is valuable and does not contradict any annotation.

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

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

The description is information-dense but not bloated. Each sentence serves a purpose: the first explains the core function, the second gives use-case context, the third details technical implementation and limits. While longer than necessary, it is well-structured and front-loaded with the primary purpose, making it easy to scan.

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

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

For a search tool with no output schema, the description thoroughly covers what the agent receives (passages with offsets and scores), how the search works (embeddings, window size), and operational constraints (char cap, truncation). It also explains why this tool is useful (context savings) and how to integrate it with other tools. This is a complete picture for an agent to select and use the tool correctly.

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

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

The schema covers all three parameters with descriptions, so baseline is 3. The description adds extra nuance, such as the text parameter accepting document text with a ~200K char limit and the query parameter being natural language with examples. It further clarifies that limit controls the number of passages returned. This enriches the schema's minimal descriptions without being redundant.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record' with a specific verb and resource. It further explains the output (top-N passages with character offsets and similarity scores) and distinguishes it from siblings by noting it pairs with ask_pipeworx_grounded, making its role unique.

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

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

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt' and 'search_within saves context, returns only the passages that matter.' It also names an alternative/companion tool (ask_pipeworx_grounded) and describes the workflow: fetch with the gateway, then ground over relevant passages. This clearly tells the agent when to use this tool vs. alternatives.

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

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

The description adds meaningful context beyond the annotations: it discloses the auth prerequisite, the always-on feed, email/SMS options with verification and caps, and the return of a subscription id. It does not contradict the annotations (readOnlyHint=false, idempotentHint=true, etc.). However, it omits webhook delivery details, which are left to the schema.

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

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

The description is dense and informative but runs as one long paragraph without structure, mixing prerequisites, types, and delivery channels. Every sentence adds value, but the lack of organization (e.g., bullets) makes it harder to scan. It is moderately concise for its complexity.

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

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

The tool is complex (5 types, 3 delivery channels, auth requirement) and there is no output schema, so the description must cover return values and key behaviors. It does mention the return id and major channels, but omits the webhook option and two subscription types (patent_grant, clinical_trial), which are only in the schema. The description plus schema is mostly complete, but the gap in the description could cause an agent to miss options.

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 provides 100% parameter coverage with per-type examples, but the description reinforces key semantics like items:['5.02'] = officer change and SMS verification/caps. It does not cover patent_grant and clinical_trial parameters in the description, though the schema covers them. Overall, the description adds extra clarity on top of a fully documented 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This specific verb+resource differentiates it from siblings like recent_alerts and unsubscribe, which are read/removal tools. The mention of 'proactive monitoring' conveys the tool's purpose unambiguously.

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 context by stating the OAuth account requirement and explaining the always-on feed with retrieval via recent_alerts. It also describes supported types and delivery channels, giving the agent a clear sense of when to use this tool. However, it does not explicitly mention alternatives or exclusions (e.g., one-time queries vs subscriptions), so a full comparison is absent.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond those: it returns example questions and tool-call patterns drawn from a live catalog, and it explicitly describes the output structure (category-bucketed). This enriches the agent's understanding without contradicting annotations.

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

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

The description is front-loaded with common user prompts, then quickly pivots to the actual functionality. It's somewhat long but every section earns its place: user intent examples, output summary, invocation syntax, and usage guidance. The structure is clear, though the initial query list could be slightly tightened.

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

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

For a simple 1-parameter, no-output-schema tool, the description covers everything: purpose, use case, return format, parameter usage, and relationship to siblings. It even lists the exact categories returned and names the meta-tools. The description is complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, but the description adds semantic value by giving concrete examples of `topic` values ("finance", "pharma", "betting") and clarifying that omitting it returns a cross-category spread. This goes beyond the schema's generic list of allowed values.

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 suggest_questions as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape for each. It distinguishes itself from siblings by emphasizing its role as the first-tool-to-try when the agent doesn't know what Pipeworx can do.

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

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

It explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides alternatives (ask_pipeworx, entity_profile, compare_entities). It also explains how to call it: with no arguments for a full spread or with a `topic` to focus, making usage conditions clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds the list of returned fields but does not disclose additional behavioral traits such as error handling, rate limits, or authentication requirements. With annotations covering the safety profile, the description adds moderate value but not rich behavioral context.

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

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

The description is a single, well-structured sentence that front-loads the source (Clash Royale official API) and the purpose. Every word earns its place, with no redundancy or filler.

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

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

The tool is simple with one parameter and has an output schema, so the description does not need to detail return values. It covers the resource and the fields contained in the result. It is slightly incomplete in that it does not mention when to use tournament_search or any error cases, but for a straightforward lookup tool, the description is adequate.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'for a tournament tag' which clarifies the sole parameter 'tag', but it does not specify the tag format (e.g., with or without '#') beyond what the example in the schema shows. The description adds some meaning but leaves details to the schema example, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool provides tournament details for a specific tournament tag, listing the exact fields returned (name, description, max capacity, creator, current members, status, game mode). It uses a specific verb+resource structure and distinguishes from the sibling 'tournament_search' by focusing on a single tag rather than searching.

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 makes clear that this tool is used with a tournament tag, which is a specific context. However, it does not explicitly state when to use this instead of alternatives like 'tournament_search', nor does it mention any exclusions. The context is clear but lacks explicit alternative guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value beyond annotations by specifying the return content ('capacity, current members, and start time') and the 'Clash Royale official API' source, which helps set expectations.

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, front-loaded sentence that concisely conveys the tool's purpose and return data. Every word earns its place with no redundancy.

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

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

With an output schema present, the description need not explain return values. The tool is simple (no required parameters) and the description covers the core functionality. However, parameter semantics are weak, slightly reducing completeness.

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

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

Schema description coverage is 0%, so the description must compensate for explaining the parameters. It only implies 'name' as the search term but does not clarify 'after', 'before', or 'limit'. This leaves three parameters unexplained.

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

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

The description clearly states the verb 'search' and resource 'open tournaments by name', distinguishing it from sibling 'tournament' which likely fetches a specific tournament. It also specifies the API source and return fields.

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

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

The description provides clear context for when to use this tool: to search open tournaments by name. It does not explicitly mention alternatives or exclusions, but the context is unambiguous enough for an agent to select it over siblings.

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

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

The description adds meaningful behavioral details beyond annotations: ownership enforcement (only your own subscriptions), and deactivation (not deletion) with historical events preserved via 'recent_alerts'. This aligns with annotations (destructiveHint false, readOnlyHint false) and provides extra context about side effects.

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

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

The description is three sentences long, each carrying distinct information: action, ownership constraint, and post-cancellation behavior. No redundant wording; the structure is easy to parse.

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

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

For a single-parameter mutation tool, the description covers the operation, constraints, and outcome (deactivation vs deletion). It also points to a related tool ('recent_alerts') for historical events. Annotations cover idempotency, so no further detail 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?

Schema coverage is 100% and the description does not add new meaning beyond what the schema already provides: 'id' is described as 'Subscription id (uuid) returned by subscribe.' The description only repeats 'by id', so no additional parameter semantics.

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

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

The description states a specific verb+resource: 'Cancel a subscription by id.' It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the action and ownership enforcement.

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: you can cancel your own subscriptions, and the row is deactivated rather than deleted, which points to 'recent_alerts' for historical events. However, it does not explicitly state when NOT to use this tool or name alternative tools for other scenarios.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive. The description adds meaningful behavioral context: the SEC EDGAR fast path with exact percent-delta math, fallback to grounded pipeline, verbatim evidence, pipeworx:// citations, and the specific verdict types returned. 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 efficiently structured, front-loaded with trigger phrases, then use cases, routing logic, and output details. Every sentence contributes value, and despite length, it remains focused and readable.

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

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

With no output schema, the description fully explains the return format: verdict, actual value with citation, and reasoning. It covers edge cases (any other factual claim), routing, and parameter behavior, making it complete for a 2-parameter read-only tool.

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

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

Schema description coverage is 100%, with both 'claim' and 'tolerance_pct' already well-defined in the schema, including examples and defaults. The description adds no new parameter-level semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with specific trigger phrases. It distinguishes from siblings by explicitly targeting factual claim checking and describing the two routing paths (SEC EDGAR/XBRL for company-financial, grounded pipeline for any other claim).

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates between company-financial claims and all other factual claims. It also notes it replaces 4–6 sequential calls, giving context for why this tool is preferred over alternatives.

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