Datagov Au

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds cost detail ('BYO key — you pay Anthropic directly'), default model, and return structure, but doesn't discuss rate limits or data handling, which is acceptable given annotation coverage.

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

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

Three sentences, front-loaded with primary action, then key details, then use cases. No wasted words.

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

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

No output schema, but description clearly lists return payload shape. With strong annotations and schema coverage, the description covers context and 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%, so baseline is 3. Description adds extra meaning by specifying the default model (Llama-3.3-70b) and cost implications of using _apiKey, going 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?

Description uses specific verb 'Probe' and identifies resource 'one or more LLMs' and outcome 'score visibility (0-100) per model'. However, it doesn't name sibling tools like 'scan_competitor_ai_presence', so some ambiguity remains about how it differs.

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?

States clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Provides context on when to use, but doesn't specify exclusions or alternatives, so not a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: it routes to many tools, fills arguments, returns stable citation URIs, works on every tier, and makes one fast call. It also clarifies that even breaking-news queries are handled. 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?

Although long, every sentence earns its place: primary directive is front-loaded, followed by domain examples, usage triggers, examples, and step-up guidance. The structure is logical and dense with actionable information, not filler.

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

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

Without an output schema, the description still explains that the return is a structured answer with pipeworx:// citation URIs. It covers purpose, usage, examples, alternatives, and performance characteristics, making it fully contextual for a tool of this complexity.

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

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

Schema coverage is 100% with all parameters being aliases for the single 'question' parameter, so the baseline is 3. The description adds meaning by providing concrete example questions and explaining when to use the tool (e.g., 'what is', 'look up', 'current'), which goes beyond the schema's simple alias explanation.

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 questions to the right one of 5,529 tools and returns structured answers with citation URIs, covering a specific verb (routes, answers) and resource (factual questions). It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit 'PREFER OVER WEB SEARCH' guidance with a comprehensive list of domains, followed by 'START HERE for most questions' and then 'Step up only when needed' with exact alternatives (ask_pipeworx_grounded, deep_research) and when each applies. This is strong when/when-not guidance with named alternatives.

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

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

The description goes beyond annotations by disclosing the beta nature, live candidate routing improvements, current equivalence to ask_pipeworx, and the fact that it is a fully working router with no fallback. This gives the agent full awareness of the tool's experimental and dynamic behavior.

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

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

The description is well-structured and front-loaded, starting with the key beta designation. Every sentence adds value—defining the tool, clarifying current status, giving usage direction, and affirming it is a full router—with no filler or repetition.

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

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

Given the tool's complexity as a universal router with many underlying tools, the description fully equips an agent to decide when and how to invoke it. It specifies the same response shape as ask_pipeworx, which suffices in the absence of an output schema, and covers the current operational state.

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

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

The input schema covers all six parameters with 100% coverage, including aliases for 'question'. The description adds no parameter-specific details beyond stating it shares the same arguments as ask_pipeworx, which is redundant given the schema already fully documents each field.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from ask_pipeworx and ask_pipeworx_grounded by being the experimental edge, making its purpose unmistakable.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing clear when-to-use guidance. It also notes results are compared against the stable router, implying when to choose this over the stable version, though it could more explicitly state when NOT to use it.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical behavioral details: it returns evidence as a verbatim quote, provides a 'refusal_reason' enum for non-answer cases, guarantees 'using ONLY what the tool result contains', and notes the cost of one extra LLM call. These behaviors are not inferable from annotations alone.

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

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

The description is a bit long but well-structured: it opens with the main purpose, then details the process, output format, refusal reasons, use cases, and cost tradeoff. Each sentence adds necessary information. The length is justified by the tool's complexity, but it could be tightened slightly with fewer examples.

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

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

The description fully compensates for the absence of an output schema by specifying the exact return structure, including the evidence field, confidence, and refusal_reason enum. It also covers the tool's internal routing and argument-filling behavior, making it clear what the tool does and when it fails. No major gaps remain.

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

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

The input schema covers 100% of parameters, with each parameter having a description explaining it as an alias for 'question'. The description does not add any further parameter-level semantics, which is acceptable because the schema is already informative. 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the full pipeline (routes, fetches, extracts using only tool result). It clearly differentiates from sibling ask_pipeworx by framing it as the grounded variant, and describes the two output modes (success vs. refusal).

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 whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also tells when NOT to use: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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

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

The description goes far beyond the annotations' readOnly/idempotent hints. It discloses detailed behavioral traits: fan-out parallelism, response shapes, news fallback logic, status short-circuits (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and cancellation-rule risk quantification. It even warns about pure-rules losses from 50¢ void settlements. This is rich, non-obvious context that materially affects agent decision-making.

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 highly structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the primary purpose and input expectations. While no sentence is wasted, the sheer volume of sections makes it dense; it is concise for its complexity but not a model of brevity.

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

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

Given there is no output schema, the description takes full responsibility for explaining return values and edge-case behavior. It covers response shapes, resolver confidence fields, parent_event extraction, news metadata, blocking statuses, and cancellation-rule risk. For a tool with 3 parameters and complex expected output, this description is exceptionally complete.

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

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

The schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds tangible value by explaining how the depth parameter translates into fan-out breadth (e.g., BTC bet → coingecko + fred + gdelt+gnews) and by elaborating on include_raw size tradeoffs (≈20KB vs 50KB-500KB). These examples clarify parameter semantics beyond the schema entries.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies supported input forms (slug, URL, question text) and describes the pipeline (resolve, classify, fan-out, return evidence packet + comparison). This clearly distinguishes it from siblings like polymarket_arbitrage or validate_claim by emphasizing research and data synthesis rather than pure arbitrage or claim validation.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives behavioral guardrails (e.g., inspect market_match_confidence before trusting analysis, check cancellation rule before sizing). However, it does not explicitly list when not to use it or name alternative sibling tools, so it falls short of the highest bar.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds rich context: data sources (SEC EDGAR/XBRL, FAERS), special handling of off-calendar fiscal years, sorting by primary metric, and the return of citation URIs. This goes well beyond the structured annotations.

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

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

The description is dense but well-structured, starting with trigger phrases then explaining behavior, type-specific data, sorting, and output. Slightly long as a block of text, but every sentence contributes useful information without redundancy.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (paired data + pipeworx:// citation URIs) and how results are ordered. It covers both entity types, data sources, and expected response format, making it complete for the tool's complexity.

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

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

Although schema coverage is 100%, the description adds significant meaning by explaining what metrics each 'type' pulls (e.g., latest 10-K revenue for companies; adverse-event counts for drugs). It also clarifies the 'values' format with concrete examples, such as tickers for companies.

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: side-by-side comparison of 2–5 companies or drugs in a single call. It includes multiple trigger examples ("X vs Y", "rank these companies") and explicitly distinguishes from alternatives by noting it replaces 8–15 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?

It explicitly instructs "ALWAYS PREFER over sequential single-pack lookups when comparing entities," providing a direct when-to-use directive. It also differentiates behavior based on the 'type' parameter (company vs. drug), giving clear context for when each mode is appropriate.

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/open/idempotent hints, and the description adds extensive behavioral context beyond that: account/paywall requirements, output packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[] to avoid invention, contradictions[], second-hop iteration, semantic excerpting, citation_uri resolvability, and latency expectations. No contradiction with annotations.

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

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

The description is long (~300 words) but densely packed with unique operational details; it is front-loaded with the critical account caveat. Every sentence conveys a distinct spec or constraint, though the length is near the upper limit for quick 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?

With no output schema, the description fully covers return values (findings packet with evidence, confidence, source, fetched_at, citation; gaps[]; contradictions[]; hop field), latency expectations, limitations (returns empty gaps for non-catalog current news), and operational nuances. The agent has enough information to select and invoke the tool correctly.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaningful extra semantics for the depth parameter (gap recovery for standard, lead-chasing and paid plan for thorough, contradiction scans) and clarifies that question is natural language and tolerates multi-part queries, going beyond the schema's basic descriptions.

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

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

The description opens with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call.' It distinguishes itself from sibling tools by explicitly stating it is NOT open-web search and contrasts its use case with ask_pipeworx.

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

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

Provides direct when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicit exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' Also covers account-level fallback: 'If you are not signed in, use ask_pipeworx instead.'

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe/read-only nature is covered. The description adds valuable behavioral context about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations by clarifying what the agent receives and that no further schema lookup is required.

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 4 sentences and front-loaded with the core purpose ('Find tools by describing the data or task'). The domain list is long but functional, and each sentence earns its place: purpose, usage, output details, and a 'call first' heuristic. It is slightly verbose but well-structured and not redundant.

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

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

Although there is no output schema, the description explicitly states what the tool returns (names, descriptions, full input schemas with curated examples). Combined with the thorough parameter schema and safety annotations, the description fully covers purpose, usage, return value, and behavioral expectations. No significant gaps remain for this type of discovery tool.

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

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

Schema description coverage is 100%, with all parameters (query, q, task, limit, search, description) individually documented, including aliases and examples. The description adds limited extra meaning beyond the schema—only 'top-N' loosely maps to the 'limit' parameter. Since the schema carries the full burden, a baseline 3 is appropriate.

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

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

The description uses a specific verb ('Find') and clearly states the tool's purpose: to discover tools by describing a data or task. It lists numerous domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes itself from siblings with 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This makes the purpose unambiguous and well-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 when to use ('Use when you need to browse, search, look up, or discover what tools exist') and gives a strong heuristic ('Call this FIRST'). It implies when not to use by contrasting with 'not just one answer,' but it does not name alternative tools explicitly. Still, the guidance is clear and actionable.

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

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

Beyond annotations, the description richly details behavior: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specifies return fields (cik, recent_filings with URIs, fundamentals sorted by period_end DESC, patents soft-fail, GDELT→GNews fallback). It also notes the USPTO API sunset, adding valuable operational 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 justifiably so given the tool's complexity. It is front-loaded with example queries, then purpose, behavior, and parameter guidance. While slightly verbose, every part serves a purpose, with a structured list of outputs.

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 multi-source tool with no output schema, the description fully compensates by enumerating return fields, sources, fallbacks, and limitations. It also includes the required parameter format and a pointer to resolve_entity for names, making it operationally complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful clarity with concrete examples ('ticker "AAPL" or zero-padded CIK "0000320193"'), explicitly stating that names are not supported and directing to resolve_entity. This enhances comprehension beyond the schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It includes specific example queries and explicitly distinguishes itself from chaining single-pack lookups, making it unambiguous and 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?

It provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use it ('names not supported') and advises using resolve_entity first, giving clear exclusions 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, so the description's 'Delete' aligns but adds little extra beyond the reasoning for deletion (clear sensitive data). It does not elaborate on failure modes or permanence, but the existing annotations provide a solid safety profile. 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 compact, consisting of three clear sentences: purpose, usage conditions, and relation to siblings. It is front-loaded and every sentence contributes meaningfully, with no fluff or redundancy.

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

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

For a simple single-parameter tool with no output schema, the description covers the core functionality, use cases, and tool relationships. It lacks detail on return values or error handling, but given the tool's simplicity and the annotations covering safety, the context is reasonably complete.

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

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

The input schema covers the parameter 'key' completely with 'Memory key to delete', and the description reinforces the role of the key but adds no new details. With 100% schema coverage, the description provides marginal added value.

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

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

The description begins with 'Delete a previously stored memory by key,' using a specific verb (delete), resource (memory), and mechanism (key). This clearly distinguishes it from sibling tools like 'remember' and 'recall', which store and retrieve memories respectively.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also directly references related tools with 'Pair with remember and recall', providing context for 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 this as a safe, read-only, idempotent operation. The description adds valuable behavioral context by explaining the process ('Fetches the page, extracts title/description/key links') and the output format ('standard llms.txt markdown format... drop at site-root/llms.txt'). This goes beyond the annotations, though it does not cover edge cases like rate limits or authentication, which is acceptable given the low risk 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 compact and every sentence carries purpose: what it does, how it works, what the output is, and when to use it. No filler or repetition; it is well-structured and front-loaded with the most critical information.

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

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

Given the simplicity of the tool (2 parameters, no output schema), the description fully covers the essential aspects: purpose, behavior, output format, and use cases. Annotations handle safety constraints. Nothing critical is missing for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage for both parameters: 'url' and 'max_links' are each explained with types and defaults. The description does not add any additional meaning to the parameters beyond what the schema already provides. With perfect schema coverage, a baseline score of 3 is appropriate.

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

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

The description opens with a specific action ('Generate a production-ready llms.txt file for any URL') and clearly identifies the resource and goal (helping AI crawlers index the site). It distinguishes itself from sibling tools by focusing on a concrete deliverable (llms.txt) rather than general visibility or research.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which tells the agent when to use it. However, it does not mention when not to use it or point to alternative tools, so it falls short of the full 'when/when-not/alternatives' ideal.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful context about the resource and output fields (names and slugs), but does not detail behavior like pagination or response structure. With annotations covering safety, this is adequate but not rich.

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

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

The description is a single sentence that front-loads the action ('List all') and includes the resource, output fields, and a practical use case. No unnecessary words or repetition.

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

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

Given the presence of an output schema and strong annotations, the description covers the core purpose and output contents. However, it omits an explanation of the 'limit' parameter and does not reference sibling tools like 'tags' or 'organizations' for alternative facets, leaving minor gaps.

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

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

The only parameter, 'limit', is not explained in the description, and the schema has 0% description coverage. The description does not compensate by clarifying how the limit affects results, leaving the agent without explicit guidance on this parameter.

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

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

The description clearly states a specific verb ('List') and resource ('thematic groups in the data.gov.au CKAN catalogue'), and specifies the output (names and slugs). It also distinguishes from sibling tools like 'tags' and 'organizations' by describing groups as topic categories and subject-area filters.

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

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

The description provides clear context on when to use the tool ('useful for discovering available subject-area filters'), but it does not explicitly mention alternatives or exclude cases. This aligns with 'clear context, no exclusions'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds value by listing return fields and providing practical usage context, but it doesn't mention potential behavioral details like pagination or batching, which might be expected for a list operation.

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, containing only two sentences that convey the action, return fields, and usage scenarios. There is no redundant or filler content, and key information is front-loaded.

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

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

For a simple read-only list tool with one optional parameter, the description provides adequate completeness: it specifies the return fields, the effect of the optional parameter, and practical use cases. No output schema is required given the field list is stated.

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 include_inactive is fully documented in the schema with a clear description and default value. The tool description does not add additional meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions, and it distinguishes itself from related sibling tools like subscribe and unsubscribe by referencing 'before adding more' and 'to find an id to cancel'.

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

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

The description explicitly indicates when to use this tool: to review what you're monitoring before adding more or to find an id to cancel. This gives clear context and implicitly suggests it as a precursor to subscription modification tools.

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

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

Annotations already cover the safety profile (read-only, open-world, idempotent, non-destructive). The description adds the data source, specific output fields (slug, title, description, dataset count), and the slug's downstream use in search, going beyond annotation basics without contradiction.

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

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

Two sentences, front-loaded with the source and action. Every clause adds value: the output fields, the slug's purpose, and the question it answers. No fluff or redundancy.

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

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

With one well-documented parameter, rich annotations, and an output schema present, the description covers the tool's scope and use case. It explains what to expect and how to use the results, making it complete for a list-resource tool.

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

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

Schema coverage is 100% and the only parameter 'limit' is fully described in the schema. The description does not add parameter-specific details, which is acceptable because the schema already carries the burden.

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

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

The description clearly identifies the tool as listing publishing organizations on data.gov.au, using the verb 'list' and naming the specific resource (Australian government agencies/departments). It also mentions the slug's role for search, which distinguishes this tool from catalog siblings like 'groups' or 'package'.

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 states the use case: answering which Australian agencies publish open data and how many datasets each has. It also implies usage before search filtering by organization via the slug, providing clear context even though it doesn't explicitly compare with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds minimal behavioral context beyond stating that it returns a single package; it does not disclose error behavior, response format, or how name lookup works, so it adds little value 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 short sentence, which is concise, but it is under-specified. It omits a verb and provides minimal detail, so while it is brief, it does not earn its place with useful information.

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

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

Despite having an output schema and annotations, the description lacks context about what constitutes a 'package', how the id maps to a dataset, and the intended usage scenario. A complete description for this simple tool would need to explicitly state 'Retrieve a package by its id or name' and clarify the parameter semantics.

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

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

Schema description coverage is 0%, so the description must compensate. It only says 'by id or name', but the schema has a single 'id' parameter with no explanation of whether 'name' is accepted or how it resolves. This is confusing and adds no meaningful parameter semantics.

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

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

The description identifies the resource as a 'package (dataset)' and mentions lookup by id or name, but lacks an explicit verb (e.g., 'get', 'retrieve'), making it unclear whether this is a read or write operation. It also vaguely distinguishes from siblings and conflicts with the schema, which only accepts an 'id' parameter despite the description claiming 'by name'.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention any selection criteria, alternatives, or exclusions, leaving the agent to infer usage from the name and description 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?

Discloses rate limiting (5/day), cost (free, no quota), response behavior (returns claim_token without account, can be reused later to check status), and that feedback affects roadmap. Minor gap: behavior when an account does exist is not specified, but overall strong disclosure beyond the sparse annotations.

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

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

The description is long but every sentence adds value: purpose, use cases, exclusions, claim_token usage, rate limit, and cost. It is front-loaded with the core purpose. Slightly verbose near the end ('The team reads digests daily...') but not wasteful.

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

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

Given the tool's moderate complexity and lack of output schema, the description explains enough: what happens after filing, how to follow up, and constraints. It does not specify the exact return format or what happens with an account, but these are not critical for the 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?

While schema descriptions cover 100% of parameters, the tool description adds crucial usage context: how to use claim_token to read replies, and instruction not to paste end-user prompts. This goes beyond just enumerating fields, especially for claim_token and message.

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 uses a specific verb ('Tell') and resource ('Pipeworx team'), and distinguishes itself from siblings by focusing on feedback rather than searching or asking questions.

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

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

Explicitly lists when to use ('bug', 'feature/data_gap', 'praise') and when not to (tools from other MCP servers, directing users to file with that server instead). Also clarifies what counts as a Pipeworx tool. This is clear, actionable guidance with 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 readOnly and idempotent, but the description adds valuable behavioral context: data is 'derived from CF analytics-engine,' contains 'no PII,' and is 'Cached 5min-1h depending on window.' This goes beyond structured fields and informs the agent of freshness and privacy characteristics.

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

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

The description is well-structured and front-loaded: the first sentence states the core function, followed by return details, a numbered list of use cases, and additional data source/caching notes. Every sentence adds information and no filler is present.

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

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

Despite having no output schema, the description specifies the return contents ('top tools, top packs, and total call volume') and covers purpose, use cases, data source, privacy, and caching. For a simple one-parameter tool, this provides complete context for an agent to decide when and how to invoke it.

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

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

The input schema has 100% coverage and already explains the window parameter: '24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.' The main description merely restates '24h, 7d, or 30d' without adding new meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' The verb 'Returns' with specific result types makes the purpose unambiguous and distinguishes it from sibling tools like discover_tools or search, which focus on different actions.

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: 'discovering what data sources are hot for current events,' 'confirming a popular tool is the canonical choice,' and 'seeing whether your use case aligns with what most agents need.' However, it does not mention when not to use the tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: the 3pp threshold for partition_check signals, the 0.30 Jaccard similarity requirement, the placeholder filter, and the fill check caveat about book depth. It discloses the exact response fields and the meaning of skipped_low_similarity. No contradictions with annotations.

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

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

The description is long but well-structured: it opens with a clear one-sentence purpose, then breaks into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that each convey essential operational details. Every sentence carries information; there is no filler or redundancy. The structure aids an agent in parsing key constraints 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?

Even without an output schema, the description fully specifies the response structure (opportunities[], partition_check, fill_check) and covers edge cases such as weak book depth, placeholder slugs, and low similarity pairs. It also references a related tool and explains what the tool does not do. This is comprehensive for a complex multi-mode tool with 0 required parameters.

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

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

Schema coverage is 100%, and the description further enriches the two parameters with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifies that full URLs are accepted for event, and explains the behavioral difference between event and topic modes. It goes far beyond the schema's brief 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 states exactly what the tool does: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names the specific verb (Find), resource (Polymarket arbitrage), and methodology, clearly distinguishing it from sibling tools like polymarket_edges. It also mentions a related sibling (polymarket_fill_risk) for a different use case, further clarifying its own scope.

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

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

The description explicitly explains when to use each mode: no args for trending_scan, 'event' for a specific market, and 'topic' for cross-event scanning. It even gives a recommendation ('event (recommended for a specific market)') and provides concrete examples. It also warns against trading when realizable_edge_pp ≤ 0, and points to polymarket_fill_risk for custom sizing. This is exemplary usage guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes far beyond with details on model families, edge_pp_net calculation, Kelly caps, the 24h-move warning, why partition parent Kelly is zero, diagnostics for empty segments, and caching behavior. This fully discloses the tool's internal decision-making and edge cases.

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

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

The description is long but well-structured with uppercase section headers and a clear first-sentence purpose. Every section contributes necessary algorithm or response details, but the overall length is dense and might be overwhelming, preventing a perfect score.

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?

Since there is no output schema, the description fully explains the response structure including by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It also covers all parameters, algorithm variants, filtering semantics, and caching. For a highly complex tool, the description is exceptionally complete.

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

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

The schema already covers 100% of parameters with descriptions. The description adds extra semantic context for tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly), explains why min_kelly doesn't filter partition arbs, and contextualizes slippage defaults. However, it doesn't add meaning for all 9 parameters (e.g., limit, window), so it earns a 4 rather than a 5.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' — a specific verb and resource. It clearly distinguishes itself from generic search tools by focusing on 'what should I bet on today' and mentions not paging hundreds of markets, which differentiates it from broader scanning 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 gives a clear use case ('what should I bet on today') and provides guidance on when to adjust knobs like min_liquidity and max_spread_pp to ensure tradeable edges. It implicitly excludes certain cases through placeholder filters and the Fed note, but does not explicitly name alternative sibling tools, so it falls short of a 5.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds substantial behavioral context beyond these: snapshot writing occurs on cache-miss (gaps mean no scan), history is bounded by a 60-day TTL, decay is based on daily closes (not intraday), and the response includes expired opportunities and median lifespan. This is far more than annotations provide.

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

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

Although lengthy, every sentence earns its place. The description is front-loaded with the core purpose, then systematically covers args with defaults, response fields (tracked/expired/snapshot_dates), and limitations. The use of uppercase field names and sections makes it scannable for an AI agent without waste.

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

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

The tool is complex (time-series decay, expiration tracking, snapshot gaps) and there is no output schema, so the description carries full burden. It thoroughly explains the response structure, field semantics, measurement methodology, and data freshness limitations. This is complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal additional meaning beyond the schema: it repeats the defaults and adds the phrase 'snapshot family' for window, which lightly enriches semantics. However, it does not significantly compensate for any schema gap, 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 clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges (which likely provides current edges) by focusing on temporal persistence and decay.

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

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

The description provides strong contextual guidance, explaining that a fresh wide edge vs. a 3-week-old wide edge are different trades, implying when this tool should be used. It does not explicitly name alternatives or state 'use this when X', but the use case is clearly implied through the telemetry and expiration analysis.

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

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

Annotations already mark this as read-only and non-destructive, but the description adds substantial behavioral detail: it walks the order-book ladder, returns partial-fill information, flags thin legs, and warns about forced directional risk. It also explains the interaction between modes and parameters, which is not derivable from annotations.

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

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

The description is long but densely packed and well-structured, using capitalized mode labels and flow. It front-loads the core concept and then details both modes. While every sentence adds value, the length requires careful parsing, so a perfect score is not warranted.

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

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

With no output schema, the description fully enumerates all return fields for both single-market and basket modes, including edge-case indicators like thin_legs[] and forced_directional_risk. It also covers limitations (partial fills, thin books) and provides safety guidance, making it complete for practical use.

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

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

Schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds meaning by clarifying size_usd's dual interpretation ('max spend on buys, target proceeds on sells' vs 'settlement notional' in basket mode) and explains the side parameter's default behavior in each mode, which goes beyond the schema text.

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

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

The description starts with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as the pre-trade risk 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?

Explicit guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also contrasts single-market vs basket modes and explains when each is appropriate, making the usage conditions unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes well beyond this. It discloses detailed behavioral traits: two modes, the response structure (leg-by-leg prices, matched spread, top_spreads_pp), and critical safety fields including compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs 0), temporal_alignment (aligned:false means spreads are meaningless), and skipped_cross_type/subtype counters. It also reveals that real cross-venue spreads are rare and cautions against assuming tradeability. No contradiction with annotations.

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

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

The description is long (approx 230 words) but densely packed with essential information for a complex cross-venue comparison tool. It is front-loaded with the core purpose and modes, then response fields, then safety warnings. However, it is presented as walls of text with heavy use of CAPS and dashes, lacking bullet points or subheadings that would improve scanability. Every sentence contributes value, but the structure could be more digestible.

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

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

Given the tool's complexity (cross-venue matching, multiple modes, compatibility warnings, temporal alignment) and the absence of an output schema, the description is exceptionally complete. It explains the response format (leg-by-leg prices, matched spread, top_spreads_pp), the safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), edge cases (non-equivalent bet shapes, unrelated events), and limitations. It covers all necessary context for an agent to decide when to invoke and how to 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?

Although the input schema already documents all three parameters with examples and descriptions (100% coverage), the description adds significant semantic context. It explains the two modes: topic as a pre-mapped shortcut list with 10 named examples, and explicit kalshi_event_ticker + polymarket_event_slug as overrides for custom pairings. This goes beyond the schema's static descriptions and clarifies how parameters interact (override behavior) and what values are valid for topic.

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

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

The description opens with a clear, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It explicitly names the two venues and the comparison metric (spread), and further details the two operating modes (topic vs explicit ticker/slug) and what output is produced. This distinguishes it from siblings like polymarket_arbitrage or polymarket_edges by focusing on cross-venue spread with compatibility warnings.

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 strong contextual usage guidance: it explains when to use topic mode vs explicit pairings, and explicitly cautions that most pre-mapped topics return compatibility_warning, warning that 'pre-mapped ≠ tradeable.' It gives implicit when-not scenarios (e.g., compatibility_warning means no arb exists). However, it does not name specific alternative tools for cases where this tool is inappropriate, so it lacks explicit alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context beyond annotations: it explains the scoping (anonymous IP, BYO key hash, or account ID) and the dual behavior (retrieve vs list). It does not detail return format, but that is acceptable given the simple nature and lack of output schema.

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

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

The description is concise and well-structured: three sentences, front-loaded with the core action, followed by use case, scope, and pairing. Every sentence adds value, and there is no wasted wording.

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

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

For a simple tool with one optional parameter and rich annotations, the description covers all essential aspects: purpose, usage context, scope, and related tools. It effectively tells the agent when and how to use it, and the lack of an output schema is mitigated by the inherent clarity of the promised return (value or list).

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 parameter 'key' is already described in the schema as 'Memory key to retrieve (omit to list all keys).' The description largely restates this information without adding new semantics. It does provide examples of key content (target ticker, address), but that is more about usage than parameter format, 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 explicitly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly identifies the resource (previously saved memories) and the two modes of operation. It also distinguishes from sibling tools by mentioning 'remember' and 'forget' as paired operations.

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

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

The description provides explicit guidance on when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and complements: 'Pair with remember to save, forget to delete.' This gives clear context for selection among sibling tools.

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

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

Annotations declare readOnlyHint=true, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state mutation. This directly contradicts the read-only annotation, warranting a score of 1 per the contradiction rule.

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

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

Three dense sentences cover purpose, payload, filtering, side effects, polling, and an alternative endpoint. It is front-loaded and efficient, though the second sentence is long and packs several ideas together.

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 5 parameters and no output schema, the description fully explains what events are returned (source, citation_uri, payload), how to filter, the mark_read behavior, and even provides a public mirror endpoint. This is excellent coverage for a read-like 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 already documents all parameters (100% coverage), but the description adds practical examples ('type (e.g. "sec_8k")', 'since (ISO timestamp)') and clarifies the side-effect of mark_read, enhancing schema semantics. It doesn't cover limit/unread_only, but baseline is already 3 with full 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 opens with a specific verb-resource pairing ('Pull fired events from your subscription feed') and clarifies persistence ('most recent alerts the evaluator has written to your persisted feed'). This distinguishes it from sibling tools like list_subscriptions or subscribe.

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 usage context ('Polls work fine') and points to an alternative HTTP endpoint for scripts/dashboards, but it never names alternative tools or states when to prefer this tool over search or list_subscriptions. Guidance is implied, not explicit.

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

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

The description adds substantial behavior beyond annotations: it discloses fan-out to multiple external APIs, the GDELT→GNews fallback logic, and the PatentsView API sunset causing soft-fail. It also states the return structure (changes[] grouped by source, total_changes count, citation URIs), providing a clear model of tool behavior.

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

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

The description is front-loaded with the core purpose and common query phrasings, then efficiently covers sources, fallback, parameter semantics, return structure, and the alternative tool. Every sentence contributes unique value, and despite its length, none feels 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?

The description covers the core functionality, sources, fallback logic, parameter formats, and return structure sufficiently for a tool with no output schema. It does not enumerate the exact fields within each change object, which would make it more complete, but overall it provides enough context for correct selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance on using the 'since' parameter ('Use "30d" or "1m" for typical monitoring') and gives examples for 'value' (ticker or CIK), which helps the agent select proper inputs beyond the schema descriptions.

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

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

The description explicitly states the tool is a 'change feed for a company in the last N days/weeks/months' and lists the sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from entity_profile by explicitly saying to use that instead for static profiles, making the purpose and scope clear.

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 on when to use this vs. alternatives: 'Use entity_profile instead when you want the static profile...'. It also explains fallback behavior between GDELT and GNews (e.g., GNews when rate-limited or 5xx), which helps the agent anticipate results.

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

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

Annotations already cover read/write/destructive/idempotent hints. The description adds valuable behavioral context beyond annotations: persistence scope ('scoped by your identifier'), retention differences ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and the key-value storage model. No contradiction with annotations found.

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

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

The description is four sentences and every sentence contributes: purpose, when to use, storage details, and companion tools. It is slightly longer than the exemplary two-sentence case but remains 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?

For a simple key-value write tool with no output schema, the description covers the essential context: what it does, when to use it, persistence semantics, and relationship to recall/forget. Minor gaps like overwrite behavior or size limits are not material for typical 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 documentation covers 100% of parameters with clear descriptions and examples. The description adds conceptual framing (key-value pair, scoping) and example use contexts, but does not meaningfully extend the parameter-level semantics already 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 states the tool's function: 'Save data the agent will need to reuse later' with a specific resource (key-value pair). It distinguishes itself from sibling tools like recall and forget by explicitly referencing them as complementary operations.

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 concrete use cases ('a resolved ticker, a target address, a user preference, a research subject') and guidance to use it when avoiding re-lookup is important. It mentions pairing with recall and forget, but does not explicitly state when not 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?

The description adds rich behavioral context beyond the annotations: it discloses graceful degradation of LEI/FIGI enrichment if external sources are unavailable, explains unresolved identifiers are explicitly stated, and notes that each call cascades through multiple endpoints. This goes well beyond the simple readOnly/idempotent hints.

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

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

The description is long but efficiently structured: starts with example queries, then a clear purpose statement, then detailed type breakdowns. Every sentence adds value, but some repetition (e.g., multiple examples of the same phrasing) could be trimmed. Still, it is well-organized and front-loaded.

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

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

Given the tool's complexity (multiple entity types, external data sources, cascading lookups) and lack of output schema, the description is remarkably complete. It covers return values (canonical identifiers, parent/ultimate-parent relationships, unresolved list), behavior on partial failures, and what each type returns. The agent has all necessary context 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 coverage is 100%, and the description enriches both parameters substantially. For 'type' it explains the two enum values and their expected data behaviors. For 'value' it provides concrete examples for each entity type (ticker, CIK, name, brand/generic drug), adding meaning beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific verbs like 'resolve' and a defined resource (entities). It distinguishes itself from sibling tools like entity_profile or compare_entities by focusing on identifier lookup. Examples of supported queries make the purpose unmistakable.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID' and details supported entity types. It also mentions that using this tool replaces 2-3 manual lookups, implying when to prefer it. This provides clear context for tool selection.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the resource is a downloadable file, but no further behavioral details such as error handling or response format are given.

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

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

The description is a single, front-loaded sentence with no wasted words, effectively communicating the tool's essence.

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

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

For a simple single-parameter tool with output schema and safety annotations, the description is largely sufficient. It lacks guidance on when to use versus alternatives, but the tool's simplicity lowers the need for extensive detail.

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

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

With 0% schema description coverage, the description compensates minimally by stating 'by id', clarifying the purpose of the id parameter. The schema example provides a UUID format, but the description does not elaborate on id format or constraints beyond that.

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

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

The description 'Single resource (downloadable file) by id' clearly identifies the tool as fetching a single resource by its identifier, distinguishing it from search/list tools. However, it lacks an explicit verb like 'get' or 'retrieve', making it slightly indirect but still specific.

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

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

The description implies usage when a known resource ID exists, but does not explicitly state when to use it over siblings like 'search' or 'recall'. No alternatives or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond annotations: it internally calls ai_visibility_check per entity, ranks by score, surfaces most/least recognized, and returns a ranked list with specific fields. 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 four tightly focused sentences, front-loaded with the core purpose. It includes a process overview, use case, and output details, with no filler or repetition. Every sentence earns its place, keeping it compact yet informative.

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 (multi-entity comparison, delegation to ai_visibility_check), the description covers the purpose, process, and return fields. Since there is no output schema, the explicit mention of output fields (score, confidence, signal density) is helpful. It could note limits like the 2-8 entity cap, but that exists in the schema, so completeness is sufficient.

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

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

The input schema provides 100% coverage for all parameters, including detailed descriptions for entities (first is subject, rest competitors), models, _apiKey, and context. The description echoes the entities semantics ('your brand + N competitors') but adds no new parameter information beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Compare AI visibility across multiple entities side-by-side'), then details the process (probes with ai_visibility_check, ranks by score) and output (ranked list with score, confidence, signal density). This clearly distinguishes it from the sibling ai_visibility_check, which is implied to probe a single entity, and from generic 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?

It provides a concrete use case ('competitive AI-marketing audits') and an illustrative question ('does Claude know about us as well as our competitors?'). It implicitly contrasts with ai_visibility_check by stating it probes each entity with that tool, suggesting this is the multi-entity wrapper. However, it does not explicitly mention when not to use it or name alternative tools for non-AI comparisons.

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, openWorldHint, idempotentHint), the description adds valuable behavioral traits: it is a composite fan-out operation, the first measurement on a new version can take 5-30s, and partial failures degrade gracefully with a 'sources_failed' field. This goes well beyond what annotations structurally provide.

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

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

The description is moderately long but every sentence provides distinct value: purpose, usage, return fields, limitations, and failure behavior. It is front-loaded with the main purpose and uses punctuation effectively, though it could be trimmed slightly without losing information.

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

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

Since no output schema exists, the description compensates by listing precise return fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and recent alternative versions. It also covers partial failures and latency, making the tool highly self-sufficient for correct invocation.

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

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

The schema already documents both parameters with 100% coverage, but the description adds a key restriction ('NPM ecosystem only in v1') and gives a concrete usage example ('what does adding lodash cost me') that clarifies the intended query for the package parameter. This slightly enriches 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 uses a specific verb and resource: a composite 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It clearly states the tool's scope (NPM only) and differentiates it from siblings by focusing on package evaluation and aggregation.

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

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

Explicit when-to-use guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a when-not-to-use instruction and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which names the alternative approach.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds value by disclosing the return type ('dataset metadata including resource URLs') and optional behaviors (filter, sort, pagination). This goes beyond the structured annotations and helps the agent understand what to expect.

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

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

The description is a single, well-structured sentence that front-loads the main action and resource, then lists optional capabilities and output. Every phrase earns its place, with no redundancy or filler.

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

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

With an output schema present and annotation coverage, the description sufficiently covers the tool's purpose, key options, and return type. It doesn't dive into result shape, but that is handled by the output schema. It is complete for a search tool of this complexity.

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

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

Schema coverage is 100%, so all five parameters have descriptions and examples. The description adds a high-level mapping (keyword, filter, sort, pagination) but does not provide additional detail beyond what the schema already offers. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description states a specific verb ('Search') and resource ('data.gov.au CKAN catalogue for Australian open datasets'), and clarifies scope ('by keyword') and output ('returns dataset metadata including resource URLs'). This clearly differentiates from siblings like search_within or package, which target different resources.

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

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

The description gives clear context: it's for keyword-based searching in the CKAN catalogue with optional Solr filter, sort, and pagination. While it doesn't explicitly mention alternatives or exclusions, the scoping to keyword search on data.gov.au is sufficient for an agent to infer when to use this tool versus more specialized siblings.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals technical implementation (BGE-base-en embeddings, cosine, 500-char overlapping windows) and a critical behavioral trait: inputs over 200K chars are truncated and flagged. It also describes that outputs include character offsets for verification, which helps the agent interpret results.

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 about 100 words and each sentence carries information: purpose, usage, pairing, technical details. It is dense but not redundant, and front-loaded with the core purpose.

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

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

For a tool with three params and no output schema, the description covers the input expectations, output format (passages with offsets and scores), truncation limit, and integration with a related tool. This is complete enough for an agent to select and invoke correctly.

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

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

The input schema already covers 100% of parameters, so the baseline is 3. The description adds practical meaning by explaining that 'text' should be an already-fetched document (e.g., SEC 10-K body) and gives concrete query examples, which enriches the schema's generic descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record', using a specific verb and scope that clearly distinguishes it from a general search or Q&A tool. It further elaborates with the input types and return values (top-N passages with offsets and scores), making the purpose unambiguous.

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

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

It explicitly states when to use: 'Use when the record is too big to cram into the prompt' and gives a concrete pairing with ask_pipeworx_grounded, explaining how to fetch and ground over passages. It also provides examples of suitable inputs, which serves as practical 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 readOnly=false, idempotentHint=true, and destructive=false. The description adds meaningful context beyond these: requires OAuth authentication, returns the subscription id, feed is always on, and SMS has a 10/day cap with phone verification. No contradiction with annotations. It could mention idempotency behavior explicitly, but it doesn't have to.

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 each sentence earns its place: purpose/return value, prerequisites, subscription types with examples, delivery channels. It is front-loaded with the most critical information and avoids fluff. Length is justified by the tool's complexity.

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

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

The description is generally thorough but omits two subscription types that appear in the schema enum: patent_grant and clinical_trial. It says 'Supported types:' and lists only three, which could mislead. However, the schema's params description fully documents these types, so the gap is mitigated by the rich schema coverage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining what 'items:["5.02"]' means (officer change) and explicitly states delivery channel behavior (email/sms/feed). These enrich the understanding beyond the schema's enumerations and examples.

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 ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying exactly what kind of subscription is created and what it returns (the new subscription 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 provides explicit context: it requires a Pipeworx OAuth account and excludes anonymous/BYO users ('cannot persist subscriptions'). It also clarifies delivery channels and how to pull alerts (via recent_alerts or a public endpoint). However, it doesn't explicitly name alternative tools for other use cases, so it's not a perfect 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable context beyond annotations: it reveals the output structure (category-bucketed example questions with tool + argument shape), the 'live catalog' aspect, and the behavior with and without the `topic` parameter. This exceeds the baseline for annotation-covered tools without being overly detailed.

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

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

The description is front-loaded with the tool's purpose and usage directive, but it is longer than the minimal ideal—it includes example queries and a parenthetical list of categories. Each sentence contributes useful information, and the structure is logical, but it could be trimmed slightly without losing 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 tool with one optional parameter and no output schema, the description is complete. It explains what the tool returns (category-bucketed examples with tool + argument shape), how to invoke it (with or without `topic`), when to use it (FIRST, for onboarding), and even notes the live catalog source. There are no significant gaps in the information an agent needs.

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

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

Schema description coverage is 100%, so the schema already handles the parameter well. The description adds a few usage examples ('finance', 'pharma', 'betting') and clarifies the no-argument behavior, but it largely restates what the schema already says ('Omit for a cross-category spread'). This is a standard case where the schema does the heavy lifting, meriting the baseline score 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's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shape. It distinguishes itself from siblings by explicitly saying 'Use this FIRST' and explaining its role in learning meta-tools, which sets it apart from search, discover_tools, and ask_pipeworx.

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

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

The description gives explicit guidance on when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional `topic` parameter and the effect of omitting it. However, it does not explicitly name alternative tools or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds that it returns tag names and supports keyword search, providing context beyond the annotations. It does not contradict the safety profile, and additional behavioral details like pagination are not necessary given the low complexity.

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

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

The description is a single concise sentence that front-loads the core purpose (list/search tags) and immediately notes the practical use case. Every word earns its place, with no redundancy.

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

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

Given the tool's simplicity (two optional parameters), the presence of an output schema, and annotations covering safety, the description provides sufficient context. It also adds the valuable integration hint about filtering `search` results, making it practically complete. It does not mention pagination or sorting, but these are not critical for a basic tag listing tool.

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

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

The schema has 0% description coverage, so the description must compensate. It mentions 'keyword-search' which implies the `query` parameter, but it does not explicitly explain either `query` or `limit`. The examples in the schema offer some help, but the description itself lacks parameter-level detail, leaving significant ambiguity about how to use the parameters.

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

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

The description clearly states the tool lists or keyword-searches tags in the data.gov.au CKAN catalogue, with a specific resource and action. It also distinguishes its purpose by mentioning that returned tag names are useful as filters in `search`, connecting it to a sibling 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 implies usage context by noting the results are useful as filters in `search`, which suggests when an agent might want to call this tool. However, it does not explicitly state when not to use it or name alternative tools for similar purposes, so it falls short of a full 5.

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

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

The description goes beyond annotations by disclosing that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. This adds meaningful behavioral context beyond the idempotentHint and destructiveHint annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence contributes useful information without redundancy or filler.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers the action, ownership constraint, deactivation behavior, and historical availability. It gives an agent sufficient information 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?

The schema fully describes the single parameter 'id' as a uuid returned by subscribe, so schema coverage is 100% and the baseline is 3. The description adds ownership context but no additional parameter-specific format or syntax details.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource, and it is distinct from sibling tools like subscribe and list_subscriptions. The ownership enforcement detail further clarifies the scope.

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

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

The description provides clear context: use this to cancel your own subscription, with ownership enforced. It also references recent_alerts for historical events, implying alternative context. However, it does not explicitly name alternative tools like list_subscriptions, so it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes well beyond that by explaining the meaning of 'could_not_verify' (distinct from 'unsupported'), emphasizing it is not evidence for/against, and describing the return structure (verdict, actual value with citation, reasoning). It also notes the tool replaces multiple sequential calls, giving insight into its performance characteristics.

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

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

The description is dense and long, but each sentence carries important information: usage scenarios, routing rules, return values, error semantics, and efficiency gains. It is not terse, but it earns its length by covering critical nuances. The structure is a single flowing paragraph, which could be improved with bullets, but overall it is efficient.

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

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

Given there is no output schema, the description comprehensively explains the possible verdicts (including the edge case of 'could_not_verify'), how the tool sources data, and what 'unsupported' means. It also notes the efficiency benefit over multiple calls. For an agent evaluating this tool, the description leaves little ambiguity about expected behavior and return values.

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

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

The input schema already provides detailed descriptions for both parameters, including an example for 'claim' and the meaning and constraints for 'tolerance_pct' (range, default, purpose). The description reinforces the tolerance semantics but does not add meaningful information beyond the schema, so it stays at the baseline for 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 identifies the tool as a natural-language claim verification tool with specific examples of user intents ('Is it true that…', 'fact check'). It distinguishes itself from siblings by being the only verification-focused tool among the provided list, and it specifies exactly what it does: verifies factual claims against authoritative sources and returns a verdict.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and outlines routing logic (SEC EDGAR for company-financial claims, fallback for other claims). However, it does not explicitly mention alternative tools or when not to use this tool, so it stops short of full exclusions.

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