Wynncraft

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

Annotations indicate read-only and idempotent behavior, which the description does not contradict. Beyond annotations, the description adds key details: default free model, BYO key for Anthropic, return structure (score, confidence, signals, raw_response), and combined view.

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

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

The description is two sentences with no wasted words. The first sentence front-loads the core purpose and output; the second covers key parameters and return format. Every sentence is essential.

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

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

Given the tool's moderate complexity (4 params, rich annotations, no output schema), the description fully explains behavior, usage, and return format. It leaves no critical gaps for an agent to invoke correctly.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining the default model, when the API key is needed, and how context helps disambiguation, exceeding the baseline of 3.

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

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

The description clearly states the tool probes LLMs for brand/product visibility and returns a score. It uses specific verbs ('probe', 'score') and distinguishes itself from siblings like 'ask_pipeworx' and 'compare_entities' by targeting AI visibility audits.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default vs. BYO model, but does not explicitly state when not to use or list alternative tools.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds that it routes to the right tool, fills arguments, and returns answers with stable pipeworx:// citation URIs, plus notes it works on every tier. This goes beyond the annotations by revealing internal routing and output structure, 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 longer than average, but every sentence carries purpose: it leads with the strongest guidance ('PREFER OVER WEB SEARCH'), lists use cases and examples, and ends with escalation paths. It is well-structured and front-loaded with the most important information, despite being thorough.

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 fully covers the tool's function, usage context, alternatives, and output format (structured answer with citations). Since there is no output schema, this return-value disclosure is essential and done clearly. The guidance on when to step up to related tools makes the description complete for a routing 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 fully documents the single meaningful parameter ('question') and its aliases, and the description's examples align with the schema. While the description reinforces that the input is a natural-language question, it adds no semantic information beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool routes user questions to one of 5,562 tools across 1462 sources and returns structured answers with citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique purpose unmistakable.

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

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

The description explicitly says to prefer this over web search, provides trigger phrases like 'what is' and 'get the latest', and gives concrete examples. It also explains when to use alternatives ('hallucination-resistant single answer' -> ask_pipeworx_grounded; 'broad/multi-part question' -> deep_research), giving clear when-to and when-not-to 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 provide readOnlyHint=true and idempotentHint=true, indicating safe read-only and idempotent behavior. The description adds context about experimental status, live candidate testing being inactive, and that it falls back to nothing (functional router). This complements annotations without contradiction.

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

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

The description is a single paragraph that efficiently conveys the key facts: beta status, identical semantics, current state, and usage guidance. It is slightly longer than necessary but every sentence adds value regarding the tool's experimental nature.

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 router with a single required question parameter and no output schema, the description is complete. It explains the relationship to ask_pipeworx, current behavior (matches stable), and purpose (comparison). No significant gaps; siblings are differentiated.

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%, and the description mentions 'same arguments' as ask_pipeworx but does not add parameter-level meaning beyond the schema. The schema already describes question and its aliases, so the description adds minimal value here. Baseline 3 is appropriate due to high schema coverage.

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

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

The description clearly states that this is a beta variant of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by mentioning candidate routing improvements and comparing results, which differentiates it from sibling tools.

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

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

The description explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes it currently matches ask_pipeworx exactly. It does not explicitly contrast with alternatives like ask_pipeworx_grounded, but provides clear context for when to choose this beta version.

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 non-destructive, read-only, open-world, idempotent behavior. The description adds important behavioral context: refusal reasons, response shape on success and failure, and that it uses only the tool result content to avoid hallucinations. It does not contradict annotations.

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

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

The description is dense but well-structured, front-loading the core purpose and then expanding with return format, usage guidance, and cost comparison. A few details like '5,562 across 1462 sources' could be trimmed, but overall every sentence contributes.

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

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

For a tool with no output schema and complex routing/refusal behavior, the description is comprehensive. It explains success and failure output shapes, gives clear use cases, and leverages annotations for safety. The lack of output schema is compensated by the detailed response format.

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

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

Schema description coverage is 100% with all parameters mapped to aliases for the same natural-language question. The description adds no parameter-specific detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function as a hallucination-resistant answer mode that extracts answers only from tool results, with explicit refusal behavior. It distinguishes itself from the sibling ask_pipeworx by highlighting the grounded extraction and high-stakes focus.

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

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

Explicitly tells when to use (answers will be quoted, cited, or acted on; high-stakes domains) and when not to (casual lookups), with a direct recommendation to prefer ask_pipeworx for those cases. Also notes the cost tradeoff of one extra LLM call.

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 true and destructiveHint false. The description goes far beyond these by detailing resolution matching (with confidence levels), fan-out examples per category, response shapes, safety mechanisms (low-confidence short-circuit, closed markets, wide spreads), and resolution-rule risk. 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 lengthy but well-structured with labeled sections (e.g., RESPONSE SHAPES, RESOLVER CONTRACT). However, it contains extensive detail that could be condensed without losing critical information. It is dense but not optimally concise.

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

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

Despite no output schema, the description comprehensively covers all major aspects: classification, fan-out patterns, evidence structure, safety checks, resolution rules, and response fields. It anticipates edge cases (low confidence, closed markets, wide spreads) and provides actionable guidance on inspecting match confidence.

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 3 parameters. The description adds value by explaining the 'market' parameter's accepted formats (slug, URL, question text) and clarifying 'depth' (quick vs thorough) and 'include_raw' behavior. This goes beyond the schema's concise descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research) and resource (Polymarket bet via Pipeworx data). It distinguishes from sibling tools like ask_pipeworx by being specifically for Polymarket bets and providing structured evidence packets.

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 gives usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear context for when to use. While it doesn't directly compare to siblings or say when not to use, the specificity is sufficient.

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

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

Annotations already indicate read-only, idempotent behavior. Description adds data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, and output format (paired data + citation URIs). 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?

Front-loaded with common query patterns, then specifics. Each sentence adds value; no redundancy.

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

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

No output schema, but description explains return format (paired data + URIs) and sorting. Covers all necessary context for a comparison tool.

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

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

Schema coverage is 100% and description adds meaning: explains what each type retrieves, gives examples of values, and clarifies min/max items.

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

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

Description begins with concrete user intents and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.', clearly defining the tool's purpose and differentiating it from sequential lookups.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also notes efficiency gains by replacing 8–15 sequential calls.

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, and the description adds substantial behavioral context: citations are always fetchable (citation_uri only present when resolvable), gaps[] are never invented, records are semantically excerpted rather than head-truncated, and latency expectations (15-60s, up to 90s). 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?

Very dense at ~250 words, but nearly every sentence carries operational guidance (auth, alternatives, exclusions, output shape, latency). The structure is a single wall of text, starting with account requirements before the core purpose, so it loses a point for front-loading and organization, though no content is wasted.

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 shape: findings packet with confidence/source/fetched_at, hop field, contradictions[], gaps[], citation_uri resolvability, and time expectations. Combined with auth prerequisites, depth tier implications, and clear alternatives, the tool is completely self-contained for an agent to use correctly.

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

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

Schema covers both params at 100%, but the description adds major semantic value: 'depth' behavior beyond the enum (standard re-angles gaps, thorough chases leads, thorough needs paid plan) and 'question' guidance with broad/multi-part examples and news-pitfall warning. This goes well above the schema baseline.

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

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

Specifically describes multi-source structured research across Pipeworx's 1,462 structured data sources, decomposing questions into facets and routing them to 5,562 tools in parallel. Explicitly contrasts with open-web search and distinguishes itself from ask_pipeworx (single lookup), giving a clear verb, resource, and scope.

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

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

Provides explicit when/when-not conditions: best for broad/multi-part questions over structured data (with concrete examples), use ask_pipeworx for single lookups or breaking/current news, and use ask_pipeworx if not signed in. Depth parameter is detailed with 'standard' gap recovery and 'thorough' iterative lead-chasing, giving the agent clear routing criteria.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description does not need to re-state safety. The description adds value by describing the return format: 'names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations to explain behavioral traits of the output.

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

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

The description is front-loaded with purpose, lists examples of domains, and includes usage guidance. While it is somewhat lengthy, every sentence adds value—no fluff or redundancy. It could be slightly more concise but remains efficient.

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

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

Given the absence of an output schema and the tool's role as a discovery layer, the description covers purpose, usage, result format, and examples. It does not specify exact data structures or error handling, but for a read-only discovery tool, the level of detail 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 100%, so baseline is 3. The description mentions that query accepts aliases (task, q, description, search) and limit default/max, which is already in the schema descriptions. It adds no new semantic meaning beyond what the schema provides, 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 starts with 'Find tools by describing the data or task', a clear verb+resource statement. It lists many supported domains and explains the tool returns top-N relevant tools with schemas and examples, distinguishing it from sibling tools that perform specific tasks (e.g., deep_research, bet_research) by positioning itself as a first-step discovery tool.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides strong usage guidance, including context for when not to use (when you already know the tool).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by detailing cross-source fan-out, return fields, soft-fail for patents, and fallback mechanisms. No contradictions, but could be more explicit about US-only scope beyond title.

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

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

Front-loaded with example queries for instant understanding. Lists sources and return fields in a structured manner. Slightly dense but every sentence provides essential information.

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

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

No output schema exists, so description must explain return values. It does so comprehensively: CIK, company_name, recent_filings with URIs, fundamentals, patents, news, LEI. Lacks detail on response format or pagination, but acceptable for 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?

Input schema covers 100% of parameters with detailed descriptions. The tool description repeats some schema info but doesn't add new constraints or syntax. Baseline 3 is appropriate since schema already does the work.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' Example queries like 'tell me about X' and 'company profile for Microsoft' make the purpose immediately obvious. It distinguishes from sibling tools like compare_entities, news, and 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?

Explicitly advises to 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also instructs to use resolve_entity first if only a name exists, providing clear when-to-use guidance and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing 'sensitive data' but doesn't reveal new behavioral traits 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?

Two sentences, no wasted words. Front-loaded with action and resource. Every sentence adds value.

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

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

Given one required parameter, no output schema, and full annotations, the description fully covers purpose, usage, and context. No gaps.

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

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

Schema coverage is 100% with a clear 'key' parameter description. The description adds no additional parameter 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 'Delete a previously stored memory by key,' specifying the verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by implication.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with 'remember' and 'recall,' guiding against misuse.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds process details (fetches, extracts, emits) and output format (single text blob), enriching beyond annotations without contradiction.

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

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

Four sentences with clear front-loading: purpose, process, output, use cases. No wasted words, though slightly longer than minimal. Each sentence contributes meaning.

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

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

For a simple tool with complete annotations and schema, the description covers purpose, process, output, and use cases. No output schema needed as output is described as single text blob. Fully 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 coverage is 100%, but description adds default (25) and max (50) for max_links parameter, which are not in schema. URL parameter is not further detailed, but overall adds value.

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

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

Description states 'Generate a production-ready llms.txt file for any URL' with specific verbs (generate, fetches, extracts, emits). Clearly identifies the resource and distinguishes from sibling tools (no other file-generation tools).

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

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

Explicitly lists three use cases: indexing a client's site, drafting for own project, auditing competitor. Does not mention exclusions or alternative tools, but the specific contexts provide 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by listing returned data (member list, level, XP, territories, seasonal rating) 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 a single, well-structured sentence that front-loads the main action and parameter flexibility. Every part 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, return values are documented. The description mentions specific return fields for context. Two parameters with one required and examples provided; this is comprehensive for a fetch tool.

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

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

Schema description coverage is 50% (only 'by' has a description). The description adds that 'by' can be 'name' or 'prefix', but 'name_or_prefix' lacks description in both schema and description. The examples in schema partially compensate.

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

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

The description clearly specifies the tool's action ('Fetch') and resource ('Wynncraft guild details'), with methods for lookup by name or prefix. This distinguishes it from sibling tools like 'guild_list' which lists guilds.

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

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

The description provides explicit guidance on using the 'by' parameter with values 'name' or 'prefix' for tag lookup. While it doesn't explicitly state when not to use this tool, the context of siblings like 'guild_list' offers implicit differentiation.

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 comprehensive behavioral hints (readOnly, idempotent, non-destructive). The description adds no additional behavioral context beyond restating the basic operation. No contradictions.

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

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

Extremely concise: two words. No wasted sentences. Front-loaded with the core action and resource.

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 (no parameters, no nested objects, output schema present), the description is minimally complete. However, it lacks usage context like when to prefer this over sibling tools.

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

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

Input schema has zero parameters with 100% schema description coverage. Baseline for zero parameters is 4; description does not need to add parameter information.

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

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

The description 'List all guilds' uses a specific verb and resource, clearly distinguishing from the sibling tool 'guild' which likely targets a single guild.

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

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

No guidance on when to use this tool versus alternatives, such as 'guild' for a specific guild. The description does not mention prerequisites or context.

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

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

Annotations declare safe read behavior, but the description adds no value. It fails to confirm the operation (e.g., 'returns all items') or clarify any behavioral traits beyond annotations.

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

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

The description is extremely concise (4 words) but at the cost of informativeness. It is not wasteful, but it is under-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?

Despite no parameters and annotations, the context is insufficient given many sibling tools. It does not clarify what 'full item database' entails or how the output relates to other tools.

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?

No parameters exist, and schema coverage is 100%, so there is little to explain. The description could hint at output but is not required due to output schema. Baseline 4 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 'Full item database.' is vague; it does not specify the tool's action (e.g., list, retrieve) or distinguish it from sibling tools like 'item_search' which likely also deals with items.

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

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

No guidance is provided on when to use this tool versus alternatives, such as 'item_search' or other database-related tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and non-destructive behavior. However, the description adds no extra behavioral context (e.g., return format, result limits, or side effects), missing an opportunity to enhance transparency.

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

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

The description is extremely concise at four words, with no extraneous content. While front-loaded, it sacrifices completeness for brevity, earning a middling score for being minimally adequate.

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

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

Despite an available output schema and rich annotations, the description fails to explain expected results or search behavior. With only one parameter and no param descriptions, the description is too sparse to fully inform usage, leaving gaps in completeness.

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

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

The schema has one parameter 'query' with 0% description coverage. The description adds that the query is by name, but it does not explain format, case sensitivity, partial matching, or valid inputs. The description partially compensates but is insufficient for complete understanding.

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 'Item search by name' clearly states the verb (search) and resource (Item) with a specific filter (by name). However, it does not differentiate from sibling tools like 'search_within' or 'deep_research', limiting its distinctiveness.

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

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

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

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds that it returns ranked entries, but does not disclose further behavioral traits like pagination or error handling.

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 immediately identifies the verb ('Fetch'), resource ('Wynncraft leaderboard'), and parameters. Every word adds value, with no wasted 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 presence of an output schema and rich annotations, the description provides sufficient context for the tool's purpose and parameters. It could optionally mention pagination or default behavior, but it is adequate 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?

Schema description coverage is 0%, so the description adds critical meaning: it explains the 'type' parameter with concrete examples and clarifies that 'resultLimit' controls the number of returned entries. This compensates well for the lack of schema descriptions.

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

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

The description clearly states the tool fetches a Wynncraft leaderboard by type, with specific examples like 'combatGlobalLevel', 'guildLevel', and 'warsCompletion'. It distinguishes itself from sibling tools as the only leaderboard-related 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 explains when to use (to fetch leaderboards by type) and mentions the resultLimit parameter, but lacks explicit guidance on when not to use or alternatives. Since no sibling is a leaderboard tool, the context is clear but not fully elaborated.

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

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

Annotations already declare safe operations (readOnlyHint, idempotentHint, destructiveHint false). Description adds return fields and activation context, complementing 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: first states purpose and output, second gives usage guidance. Front-loaded, no redundant information.

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

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

For a simple list tool with one optional param and no output schema, description covers purpose, output, and usage guidance completely.

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

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

Schema coverage is 100%, so the single parameter is fully documented. Description adds no extra meaning beyond schema.

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

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

Clearly states verb 'List', resource 'subscriptions', and scope 'caller's active'. Distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Provides clear context and alternative actions.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds no additional behavioral context beyond 'official news feed', which is adequate but not enriching.

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?

Extremely concise at three words. Efficient but could benefit from slight expansion for completeness.

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

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

Given simple tool with no params and good annotations, the description is minimal. Output schema exists but description doesn't hint at content. Could be more complete.

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

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

No parameters exist, and schema coverage is 100%. Baseline of 4 applies; no additional parameter info needed.

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

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

The description 'Official news feed' indicates it provides news but lacks specificity about scope, format, or update frequency. It is distinct from siblings but could be clearer.

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

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

No guidance on when to use this tool versus alternatives. Does not mention context 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds no behavioral details beyond what annotations provide, such as rate limits, data freshness, or the meaning of 'by server'.

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 with no wasted words. It is appropriately concise for a simple tool with no parameters and clear 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?

While annotations and output schema exist, the description is minimally adequate. It does not clarify whether 'by server' means a grouped list or a filter input, nor does it mention the output format. For a straightforward read tool, it is acceptable but lacks depth.

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

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

The input schema has zero parameters, so schema coverage is 100% by default. With no parameters, the description does not need to provide additional semantics; baseline for 0 parameters is 4.

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

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

The description 'Currently online players by server' clearly states the tool returns online players grouped by server. The name 'online_players' matches, and among siblings like 'player' and 'player_characters', it is distinct and unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or compare to sibling tools like 'player' or 'entity_profile'. An agent would have to infer usage from context.

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

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

Annotations only show false flags, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the account/claim_token flow, that it's free and doesn't count against quota, and that the team reads digests daily. No contradiction with annotations.

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

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

The description is a dense paragraph but front-loaded with purpose and usage, then flows into constraints and mechanics. Every sentence earns its place, though it is slightly long and could be broken into bullet points for even faster scanning.

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

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

Despite no output schema, the description explains what happens upon filing (claim_token returned, later status reads), rate limits, scope restrictions, and expected message content. It fully equips an agent to use the tool correctly in varied scenarios.

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 rich descriptions for each parameter. The description adds extra value by explicitly telling users not to paste end-user prompts and by demonstrating the claim_token usage syntax ('pipeworx_feedback({claim_token:"pwfb_…"})'). This goes beyond the schema's baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling research/query tools by being the dedicated feedback channel, and the opening sentence establishes a specific verb + resource.

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

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

Provides explicit when-to-use guidance for bug, feature/data_gap, praise, and 'other' categories. It also gives a clear when-not-to-use rule: only for tools served by this Pipeworx connection, and directs users to file with other MCP servers instead. This is exemplary alternative/context guidance.

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

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

The description adds valuable behavioral context beyond annotations: it explains the data source (CF analytics-engine), confirms no PII, notes caching behavior (5min-1h), and characterizes the output as a 'self-aggregating signal'. 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 concise (three sentences) with a clear front-loaded purpose statement and structured use cases. Every sentence adds value without redundancy or fluff.

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

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

For a simple read-only tool with one parameter and rich annotations, the description is complete. It covers purpose, use cases, behavioral traits, and data origin. No output schema is needed given the simple return structure implied.

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

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

The single parameter 'window' has a complete enum description in the schema. The description reinforces the short vs. long window semantics, but since schema coverage is 100%, the baseline is 3. The added context is helpful but not essential.

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: 'What other AI agents are calling on Pipeworx right now' and lists specific outputs (top tools, top packs, call volume). It distinguishes itself from siblings like 'discover_tools' by focusing on trending usage and agent-derived signals.

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

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

Three concrete use cases are provided (discovering hot sources, confirming canonical tool, aligning use case) along with guidance on window selection. The description lacks explicit when-not-to-use instructions but covers primary use cases well.

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 provided. The description adds that it fetches stats and lists what stats, which is consistent with annotations. No contradictions, but minimal extra behavioral context beyond the annotations.

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

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

The description is a single, well-structured sentence that clearly and concisely conveys the purpose. No unnecessary words.

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

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

Given the tool's simplicity (one parameter, no nested objects), the presence of an output schema to document return values, and the annotations covering read-only, idempotent behavior, the description is complete enough for an AI agent to understand and invoke the tool correctly.

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

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

The schema has 0% description coverage for the parameter, but the description clarifies that 'uuid_or_username' accepts either a UUID or a username. This adds meaning beyond the bare schema type definition.

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 Wynncraft player's stats by UUID or username, listing specific data fields (playtime, XP, guild, ranking, veteran status, per-class totals). This verb+resource+scope is specific and distinguishes it from sibling tools that fetch other entities like guild or items.

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

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

The description implies the tool is for retrieving player stats, providing clear context. However, it does not explicitly state when to use this over siblings like 'guild' or 'player_characters', nor does it provide exclusions or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds no extra behavioral context. It does not contradict annotations, but provides no additional transparency.

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

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

The description is very short but lacks necessary detail; it is underspecified rather than concise. Every sentence should add value, but this one fails to do so.

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

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

Given the presence of an output schema and the need to clarify what is listed, the description is completely inadequate. It does not explain whether the list is for the given player or all characters, nor its relationship to sibling tools.

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% and the description does not explain the single parameter 'uuid_or_username'. The description 'Character list' gives no hint about the parameter's purpose.

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 'Character list' is vague. It does not specify a verb or resource scope, and fails to distinguish from sibling tools like 'player' or 'online_players'.

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

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

No usage guidance is provided. The description lacks any indication of when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the agent knows it's safe. The description adds rich behavioral context: explains monotonicity checks, partition-sum checks, semantic anchor (Jaccard ≥0.30), partition filter (placeholder slugs >20% yield null), and fill check against CLOB depth with realizable_edge_pp ≤ 0 meaning no trade. 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 well-structured (one-liner followed by mode breakdown, then technical details), but it is quite long. Some specifics like threshold 0.30 and placeholder fraction details could be condensed. However, the structure is logical and front-loaded, making it still effective for an AI agent.

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

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

The description is extremely complete given the tool's complexity. It covers all parameters, explains three usage modes, details algorithmic checks, describes the response structure (opportunities[], partition_check, fill check output), and even warns about realizable edge conditions. Since there is no output schema, the description compensates by listing response fields. It also references related sibling tool for custom sizing.

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

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

Schema coverage is 100% (both event and topic have descriptions). The description goes far beyond by detailing each mode: event mode expects a Polymarket event slug and walks child markets for partition_check; topic mode uses a seed question to search related events and checks cross-event monotonicity. It provides examples and explains the internal logic, vastly enriching the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from siblings like polymarket_edges and polymarket_fill_risk by explaining its unique algorithmic approach and providing specific usage modes (trending_scan, event, topic).

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: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for specific markets and topic mode for cross-event scanning, and even mentions when to use sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description greatly enriches this with detailed behavior: explanation of three response segments, model families (crypto_price, news_momentum, partition_overround), edge computation (net of slippage, Kelly fractions), tradeable-edge knobs, caching at KV level for 1 hour, and _diagnostics for empty segments. It also warns about Fed bet unreliability. 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 verbose (>500 words) and includes extensive technical details (model formulas, knob behaviors). While well-structured (purpose, then segments, knobs, response), it could be more concise. The purpose is front-loaded, but the density of information may challenge quick parsing. Some sentences could be merged or omitted without loss.

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

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

Given the complexity (9 parameters, no output schema, 3 response segments, 5 model families), the description is exceptionally complete. It explains every segment's logic, all knob functions, response structure including diagnostics, caching, and even caveats (Fed signal unreliability). No gaps left for an agent to guess.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing practical guidance beyond schema descriptions, e.g., for max_spread_pp: 'Set to 2 to require tight books — anything wider eats most plausible edges.' and for min_partition_leg_kelly: 'Use to suppress thin partitions...' It also explains defaults and usage context, elevating clarity above 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 first sentence clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb 'scan', the resource 'Polymarket markets', and the outcome 'opportunities where data disagrees'. The description also includes the specific model families and segments, making the scope distinct from siblings though not explicitly differentiated.

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 the intended use case: 'Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets.' This provides clear context for when to use the tool. However, it does not explicitly list alternative sibling tools or conditions for not using this tool, so it lacks exclusions. Still, the context is clear and practical.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals significant behavioral details: return structure (tracked, expired, snapshot_dates), computation of trend and decay, reliance on daily closes, and snapshot gap interpretation. 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 well-structured with a one-line summary, then detailed explanation of outputs and limitations. It is somewhat lengthy but appropriate for the complexity. Every section 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?

With no output schema, the description fully explains all return fields (tracked[], expired[], snapshot_dates[]) and their meanings. It also covers limitations and data sources, making it complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100% with concise descriptions. The tool description repeats the parameter names and defaults but adds no new semantic details beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge age and shrinking, and distinguishes itself from the sibling polymarket_edges by focusing on time-series behavior rather than current edges.

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

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

The description explains when to use the tool (to differentiate fresh vs. aged edges) and provides limits (60-day TTL, snapshot gaps). However, it does not explicitly name alternatives or state when not to use it, leaving some guidance implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds rich behavioral context: walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict (clean|degraded|cannot_fill). It also warns about forced_directional_risk in basket mode, going well beyond annotations.

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

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

The description is well-structured with clear sections for single-market and basket modes. It front-loads the purpose and requirements. While slightly verbose, every sentence adds value. Minor redundancy could be trimmed, but overall effective.

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

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

Despite no output schema, the description thoroughly explains return values for both modes, including edge cases like thin legs and forced directional risk. It provides the rationale for checking (dominant loss mode). Tool complexity is high (CLOB depth, basket partitions), and the description covers all critical aspects for correct usage.

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

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

Schema coverage is 100%, baseline 3. But the description adds significant value: explains size_usd differently for single-market vs basket (max spend vs target proceeds vs settlement notional), default values, and side defaults. It also clarifies auto side calculation from partition sum. This extra context raises the score.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and lists return fields. It also differentiates from sibling tools polymarket_arbitrage and polymarket_edges by indicating when to use this tool before acting on their signals or trades above ~$500.

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 requires one of 'market' or 'event'. Provides separate usage details for single-market and basket modes. Gives specific trigger: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable, partial basket fills convert arb into unhedged position).

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?

Exceeds annotations by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) and explaining when spreads are not meaningful. No contradiction with annotations (readOnlyHint, idempotentHint are consistent).

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

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

The description is verbose and could benefit from more conciseness. Some points are repeated (e.g., compatibility_warning is explained twice). However, it is well-structured with sections and front-loaded with 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?

Given the complexity (two modes, safety fields, output structure) and lack of output schema, the description is extremely complete. It covers inputs, outputs, edge cases, and warnings thoroughly.

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 context beyond the schema: lists topic shortcuts, explains overriding behavior, and provides examples. This adds meaning beyond the parameter descriptions alone.

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

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

The description clearly states it is a cross-venue spread tool between Kalshi and Polymarket for the same resolving question. It explains two modes (topic shortcuts and explicit tickers) and distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue 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?

Explicitly describes when to use each mode (topic vs explicit) and warns about compatibility issues and the fact that pre-mapped topics are often not tradeable. Could be improved by contrasting with other polymarket tools, but overall 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the tool is clearly read-only and safe. The description adds useful behavioral context beyond annotations: the ability to both retrieve a specific value and list all keys, and that the scope is tied to the caller's identifier. No contradictions with annotations. It does not detail rate limits or error handling, but the annotations cover the safety profile.

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

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

The description is three sentences long, front-loaded with the core purpose. Each sentence adds value: the first defines the action, the second gives examples and motivation, the third adds scoping and pairing. There is no redundant or extraneous information. Could be slightly more concise by combining scoping with the first sentence, but overall efficient 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?

Given the tool's simplicity (one optional parameter, no output schema, annotations present), the description covers the essential aspects: what it does, how to use it (with and without key), the scope, and its relationship to remember and forget. It does not explain return values or error handling, but that is acceptable for a straightforward retrieval tool. The descriptions of sibling tools (remember, forget) provide complementary context. Overall complete enough for an agent to use correctly.

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

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

Schema description coverage is 100% — the single optional parameter 'key' has a clear description: 'Memory key to retrieve (omit to list all keys).' The description reinforces this by stating 'list all saved keys (omit the key argument)', but adds no new details about the parameter's format or constraints beyond what the schema provides. Baseline is 3 due to high coverage, and the description adequately complements the schema without adding significant new info.

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

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

The description clearly states the verb ('retrieve' or 'list') and the resource (memory values saved via remember). It specifies two modes: retrieving a value by key, or listing all keys by omitting the argument. It also gives concrete examples of what the stored context might be, such as 'user's target ticker, an address, prior research notes', distinguishing it from sibling tools like remember and forget.

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

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

The description provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier ... without re-deriving it from scratch.' It implicitly tells when not to use (for saving or deleting) by pairing with remember and forget. It also explains scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' However, it does not explicitly mention alternative tools or situations where a different retrieval method might be preferable, but overall it's clear for a simple memory tool.

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

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

Description describes mark_read:true as a side effect that flags events as read, mutating state. However, annotations declare readOnlyHint=true, indicating no side effects. This is a clear contradiction.

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

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

Concise, front-loaded, each sentence adds value. No redundancy.

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

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

No output schema, but description explains return fields (source, citation_uri, payload) and alternative access method. Lacks details on error responses or pagination, but sufficient for the tool's simplicity.

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

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

Schema coverage is 100% with good parameter descriptions. The tool description adds context about mark_read behavior and provides an example value for type, but does not significantly enhance parameter understanding beyond the schema.

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

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

Clearly states it pulls fired events from subscription feed, specifying return fields and filtering options. Distinct from siblings like list_subscriptions.

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

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

Provides guidance on filtering by type and since, and mentions polling works fine. Also notes alternative access via HTTP endpoint for scripts/dashboards, but lacks explicit differentiation from other sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds parallel API calls, fallback logic, and USAPTO sunset context, which exceed annotation requirements. No contradictions.

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

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

The description is well-structured, starting with examples and clear function. Every sentence serves a purpose, though slightly verbose. Could be tightened but still effective.

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

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

For a complex multi-source tool with no output schema, the description adequately covers return structure (grouped changes, total count, citation URIs) and important limitations (USPTO sunset, fallback). No missing critical context.

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

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

Schema coverage is 100% with good descriptions. The tool description adds examples and clarifies acceptable formats for 'since', and notes 'type' is currently limited to 'company', adding value beyond schema.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, listing sources (SEC EDGAR, GDELT/GNews, USPTO) and inputs. It distinguishes from sibling tool 'entity_profile' by specifying when to use each, making 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?

The description explicitly tells when to use this tool vs 'entity_profile' and explains fallback behavior (GDELT to GNews, USPTO soft-fail). It also provides guidance on 'since' format, including typical monitoring usage ('30d' or '1m').

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

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

Adds behavioral context beyond annotations: scope by identifier, persistence differences between authenticated (permanent) and anonymous (24 hours) users, and storage as key-value pairs. No contradiction with annotations.

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

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

Three sentences, purpose first, then usage, then technical details. No superfluous words.

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

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

For a simple storage tool with no output schema, description covers purpose, usage, behavior, and parameter context completely.

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

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

Schema covers parameters fully, and description adds examples of key patterns and value types, enhancing meaning beyond schema 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?

Clearly states the tool saves data for reuse across conversations/sessions, with specific examples (ticker, address, preference) and distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use (discover something worth carrying forward) and pairs with recall/forget for retrieval and deletion.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints. The description goes far beyond these by explaining internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of unresolved identifiers, and source attribution for each ID. It also documents edge cases like ISIN-to-LEI mapping for non-US issuers, which is valuable 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 long but information-dense, with the most critical usage guidance ('Use FIRST...') placed near the beginning. Some sections, like the parenthetical 'pipeworx://rxnorm/concept/{rxcui} citation', are arguably unnecessary for an agent deciding whether to invoke the tool, but they do no harm. Overall, the structure is logical and each sentence serves a purpose, though a more scannable layout would improve readability.

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 thoroughly explains what the tool returns: canonical identifiers, source labels, unresolved identifiers, and ownership data (parent/ultimate-parent/children). It also covers failure behavior (graceful degradation) and multi-endpoint cascades. For a tool with two entity types and multiple identifier sources, this is highly complete.

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

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

Although the input schema already describes both parameters at 100% coverage, the description adds substantial meaning. For 'type', it elaborates on the two enum values (company vs. drug) with associated data sources. For 'value', it provides concrete input formats, examples (AAPL, 0000320193, ozempic), and explains how ISINs resolve to legal entities—level of detail not present in the schema.

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

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

The description clearly defines the tool's purpose: resolving user-spoken names to canonical/official identifiers needed by other tools. It provides a specific verb ('resolve'), a distinct resource (entity names to IDs), and explicitly distinguishes itself from siblings by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies when alternatives are appropriate by describing what other tools require as input, and it lists supported entity types with examples. The note about replacing 2-3 manual lookups further contextualizes when this tool is the right choice.

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, etc. The description adds that it internally probes each entity with ai_visibility_check, requires an API key for certain models, and returns a ranked list with score/confidence/signal density. 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 concise paragraph (3 sentences) with front-loaded purpose. Every sentence adds essential information: main action, internal operation with use case, and output expectation. No redundant words.

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

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

Given no output schema and 4 parameters (1 required), the description fully explains the tool's functionality, how it works, what output to expect, and usage context. It covers constraints implicitly (entities array of 2-8).

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 significant value: it explains that the first entity is treated as the 'subject for narrative', clarifies model options (free default vs anthropic requiring key), and describes the output format 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 verb 'Compare AI visibility across multiple entities side-by-side' and specifies the resource (AI visibility). It distinguishes from siblings like ai_visibility_check and compare_entities by describing its multi-entity ranked output. An example use case is provided.

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 it is 'Useful for competitive AI-marketing audits' and gives a concrete example scenario. It does not explicitly state when not to use it or compare directly to sibling tools, but the context is clear.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint are true, and destructiveHint is false. The description adds value by detailing return fields, partial failure handling (sources_failed), and timing behavior for first bundlephobia measurement, 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 a single paragraph of moderate length, front-loaded with purpose and usage. It is well-structured but slightly verbose, with multiple clauses in one sentence. Still concise enough for an AI agent to parse quickly.

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

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

Despite lacking an output schema, the description lists all return fields (summary block, per-advisory detail, links, alternative versions) and covers partial failure behavior. It also addresses ecosystem limitations and timing, providing complete context for agent selection.

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

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

Input schema has 100% coverage with clear descriptions for both package and version parameters. The description reinforces the version default and scoped package acceptance but does not add new parameter information beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states the tool performs a composite check for adding npm packages by aggregating deps.dev and bundlephobia data. It clearly distinguishes its scope (NPM only in v1) from sibling tools, and uses specific verbs like 'scan dependency' and 'composite check'.

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

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

The description provides explicit usage scenarios: 'whenever an agent asks is X safe/popular/small or what does adding lodash cost me'. It also notes limitations (NPM only, first bundlephobia measurement can take 5-30s) and suggests alternatives for other ecosystems (deps.dev:version directly).

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

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

Annotation-wise, the tool is readOnly, idempotent, openWorld, and non-destructive. The description adds substantial behavioral context: embedding model (BGE-base-en), chunking (500-char overlapping windows), max input size (200K chars with truncation and flag), and output details (offsets, similarity scores). 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 concise, well-structured, and front-loaded with the primary purpose. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (3 parameters, no output schema, but with embedding and chunking behavior), the description covers all essential aspects: how it works, constraints (200K chars), return format (passages with offsets and scores), and integration with sibling tools. No missing 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%, but the description adds value beyond the schema by providing example queries for the 'query' parameter and explaining the purpose of 'text' and 'limit' in the context of semantic search. This enriches understanding.

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 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by mentioning how it pairs with ask_pipeworx_grounded, and the sibling list includes that 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. Also mentions pairing with ask_pipeworx_grounded, providing a clear 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?

The description adds significant behavioral context beyond annotations: it returns a subscription id, requires OAuth, details type-specific parameters, delivery nuances (SMS cap, email, webhook signing), and idempotency hints. No contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the main purpose and then breaking down types, channels, and constraints. It is slightly long but each sentence adds value.

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

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

Given the tool's complexity (multiple types, delivery options, prerequisites) and no output schema, the description covers authentication, return value, type-specific params, delivery limitations, and error conditions comprehensively.

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

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

Schema coverage is 100%, and the description enriches every parameter with concrete examples, constraints (e.g., SMS 10/day cap, phone verification), and format specifications (E.164, webhook signing). This goes well beyond the schema's 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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. It lists supported types and delivery channels, providing clear context. However, it does not explicitly state when to use this tool versus alternatives like list_subscriptions.

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 tool's safety profile is clear. The description adds useful context about the return format (category-bucketed examples with tool+argument shape) and that it draws from a live catalog, which provides behavioral insight beyond the annotations.

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

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

Description is informative and well-structured, starting with the core purpose, then explaining return format, and ending with usage guidance. Slightly verbose but not excessive.

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

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

Despite no output schema, the description fully explains what is returned (category-bucketed example questions with exact tool+argument shape). The single optional parameter is thoroughly described. No gaps remain.

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

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

Schema coverage is 100% and the schema already lists valid topic values. The description reiterates these values and adds the concept of 'full spread' vs focused query, but this adds marginal value. Baseline 3 is appropriate.

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

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

The description clearly states it is the onboarding entry point for learning what Pipeworx can do, explicitly listing example questions and distinguishing it from siblings like ask_pipeworx, entity_profile, and compare_entities.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions alternatives: 'to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. Also explains how to call with or without the topic parameter.

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

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

Adds key behavioral details beyond annotations: ownership enforcement, soft deactivation (not deletion), and impact on historical data via recent_alerts. Annotations already indicate non-destructive and idempotent, and the description aligns well.

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

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

Three concise sentences, front-loaded with the action. No wasted words; every sentence adds value.

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

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

For a simple single-param tool with no output schema, the description fully explains behavior, constraints, and consequences. Complete for agent decision-making.

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 description for 'id'. Description only restates what schema says (uuid from subscribe), adding no new semantic value. 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?

Clear verb+resource: 'Cancel a subscription by id.' It directly states what the tool does and implicitly distinguishes it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Mentions ownership enforcement and side effect (deactivation vs deletion), which guides appropriate usage. Does not explicitly compare with alternatives but provides sufficient context for when to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, but the description adds crucial behavioral nuance far beyond those. It defines the could_not_verify verdict as indicating the check did not happen, attaches verification_error{stage,detail}, and warns it 'must not be shown as one' (i.e., not as evidence). It also clarifies unsupported as 'we looked and cover no source for it,' and explains the two internal pipelines (SEC EDGAR+XBRL fast path vs grounded pipeline).

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?

Although the description is long, every sentence contributes: query patterns, use-case trigger, routing logic, return contract, edge-case warnings, and the replacement note. It is front-loaded with purpose and structured coherently, making the length justified for the tool's complexity.

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

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

With only 2 parameters and no output schema, the description nevertheless fully specifies the verdict enum (confirmed / approximately_correct / refuted / inconclusive / unsupported / could_not_verify), the actual value with pipeworx:// citation, reasoning, and the special meanings of could_not_verify and unsupported. The routing behavior and error handling are also thoroughly described, leaving no obvious 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?

Input schema already covers both parameters (claim, tolerance_pct) with descriptions, but the description adds substantial meaning. It explains tolerance_pct 'Overrides the tolerance implied by the claim wording,' specifies the 0.5–50 range, and gives use-case guidance for hallucination detection (set 1–2 to refute any material error). It also clarifies the default (implied by wording, capped at 5) and provides real examples for claim.

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

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

The description opens with concrete query patterns ('Is it true that…', 'fact check', 'verify the claim that…') and defines the tool as 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from siblings by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison) and by describing the two routing paths (SEC EDGAR+XBRL vs grounded pipeline).

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 whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition and even differentiating between financial and non-financial claims. However, it does not mention any exclusions or alternative tools (e.g., ask_pipeworx_grounded or deep_research), so it falls short of fully explicit when-not/alternatives guidance.

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