Confluence

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 value by explaining that Anthropic probing requires a personal API key and that users pay Anthropic directly. 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 concise (two sentences plus a returns line), front-loaded with purpose, and contains no filler. Every word adds value.

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

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

Although there is no output schema, the description explains the return format (per-model {score, confidence, signals, raw_response} + combined view). Parameters are well-documented. However, it could mention pagination or rate limits if applicable.

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 meaning beyond the schema by providing examples for 'entity' and explaining the relationship between '_apiKey' and 'models'. It clarifies that 'models' is optional and defaults to workers-ai.

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

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

The description clearly states the tool probes LLMs for brand/product/topic awareness, scoring visibility (0-100). It specifies the default model and how to add Anthropic. This distinguishes it from siblings like 'ask_pipeworx' or 'scan_competitor_ai_presence', which serve different purposes.

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

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

The description explicitly states the tool is for 'AI-marketing audits, pre-launch brand checks, competitive monitoring,' providing clear use cases. However, it does not explicitly state when not to use it or compare with alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description reinforces. Beyond annotations, it reveals the internal routing mechanism ('Routes the question to the right one of 5,564 tools across 1462 verified sources') and the return format ('structured answer with stable pipeworx:// citation URIs'). This adds significant behavioral context beyond what annotations provide, though it does not detail error handling or rate limits.

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

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

The description is front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH'). It is relatively long but every sentence serves a purpose: establishing primacy, listing capabilities, providing usage triggers, giving examples, and naming alternatives. Could be slightly trimmed if the examples were shortened, but still efficient for the complexity covered.

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 large number of sibling tools (34), the description does an excellent job of positioning this tool as the default. It covers when to use, when to escalate, what domains it covers, how it works internally, and what the output looks like. The parameter documentation is thorough, and the absence of an output schema is compensated by the description of stable citation URIs. This is complete for the tool's role as a general-purpose query engine.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that aliases like query, q, prompt, text, input all work for the 'question' parameter, and provides examples of how the parameter is used (natural language questions). A 4 is warranted because it clarifies the flexible interface in a way that the schema alone does not.

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 clear, specific verb phrase ('PREFER OVER WEB SEARCH for questions about current or historical data') and enumerates a comprehensive list of domains (SEC filings, FDA data, etc.). It distinguishes itself from siblings by name (ask_pipeworx_grounded, deep_research) and states its role as the default entry point.

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

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

The description explicitly tells when to use this tool ('START HERE for most questions'), when not to ('Step up only when needed'), and names specific alternatives with reasons (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It also provides a list of example query triggers ('what is', 'look up', etc.) and concrete examples.

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, destructiveHint), the description adds critical behavioral context: it is a beta with 'candidate routing improvements' that may or may not be active, and currently matches the stable version exactly. It also discloses the fallback behavior ('falls back to nothing'), which is not in annotations.

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

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

The description is concise and front-loaded, with 3 clear sentences. The first sentence defines the tool, the second adds behavioral context about current state, and the third gives usage guidance. No wasted words.

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

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

Given the tool's complexity as a universal router with 5,564 tools, the existing schema (100% parameter coverage with aliases), and annotations (readOnly, idempotent), the description is complete. It explains what the tool does, its experimental nature, current state, use instructions, and fallback. No output schema is needed as the description implies it returns routing results.

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

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

Schema coverage is 100%, so the schema already documents all 6 parameters and their aliases. The description adds value by explaining the parameter behavior in context ('accepts query, q, prompt, text, input as aliases') and implies the question field is the main input, but does not add new meaning beyond the schema's descriptions.

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

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

The description specifies a verb ('ask'), a resource ('Pipeworx Beta'), and explicitly distinguishes it from the stable sibling 'ask_pipeworx' by noting it has 'candidate routing improvements' and is used for testing new routing strategies. It clarifies that it is identical to the stable version when no candidate is active.

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

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

The description explicitly says when to use it ('use it exactly like ask_pipeworx when you want the newest routing'), clearly contrasts it with the stable alternative, and explains the experimental context and fallback behavior ('falls back to nothing — this IS a full working router').

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 as true/false appropriately, so the bar is lower. The description adds valuable detail: the internal routing mechanism, the extraction logic ('using ONLY what the tool result contains'), the exact return shape (including refusal reasons), and the extra LLM call cost. However, it does not elaborate on what 'grounded' means in terms of quoting evidence or potential truncation behavior beyond the 'data_truncated' refusal. 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 packed with essential information in a few sentences: purpose, behavior, return structure, refusal reasons, usage guidance, and trade-offs. It front-loads the key differentiator ('Hallucination-resistant'). Two sentences are slightly dense but not excessive. Could be slightly tightened by removing 'Same routing as ask_pipeworx — picks the right tool...' which is implicit context, but overall concise and well-structured.

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

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

Given the complexity (routing among 5,564 tools, 1462 sources), the description covers purpose, behavior, return types, refusal reasons, and usage guidance comprehensively for a high-stakes read tool. No output schema exists, but the return structure is fully described in the description. Minor gap: does not mention how evidence truncation works (e.g., character limit) or whether the user can set confidence thresholds. Still, well above minimal.

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 six parameters clearly documented as aliases for 'question.' The description adds no additional meaning beyond what the schema already provides (it only mentions 'Your question in natural language'). Since coverage is high, baseline 3 is appropriate. No extra semantic value from description.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode' for high-stakes reads, specifying the verb 'EXTRACTS the answer using ONLY what the tool result contains' and distinguishing it from the sibling 'ask_pipeworx' for casual lookups. It explicitly names the return structure and refusal reasons, leaving no ambiguity about its purpose.

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

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

Description provides explicit guidance on when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also tells when NOT to use: 'prefer ask_pipeworx for casual lookups,' and mentions the cost trade-off of one extra LLM call.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral details: resolver contract, parent event extractor, news fallback, safety short-circuits, spread warnings, and resolution-rule risk. No contradiction.

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

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

Very detailed but excessively long; contains multiple paragraphs with all-caps sections. While structured, conciseness could be improved to reduce agent processing effort.

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

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

Given the tool's complexity and no output schema, the description covers fan-out examples, response shapes, resolver contract, parent event extraction, news fields, safety, spread warnings, and resolution-rule risk comprehensively.

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

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

Schema coverage is 100%, and description adds meaning: market input formats, depth options, include_raw usage guidance. Adds significant value beyond the schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, with specific input formats and output. It does not explicitly differentiate from sibling tools like polymarket_edges, but the purpose is well-defined.

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 use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Lacks explicit when-not-to-use or alternatives, but examples are clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and explains sorting by primary metric. 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 front-loaded with example triggers and structured by entity type. Every sentence contributes unique information, though slightly long. Efficient for the 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?

Despite no output schema, the description fully explains return data (paired data + citation URIs) and behavior per type. With 2 well-documented parameters, this is complete for an AI agent to invoke correctly.

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

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

Schema coverage is 100%. The description adds examples of parameter values (tickers/CIKs for company, names for drug) and max count (5), but this is largely redundant with the schema. The added context is helpful but baseline is 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 does side-by-side comparison of 2–5 companies or drugs, with explicit verb phrases like 'compare', 'vs', 'rank'. It distinguishes from sibling tools like entity_profile by stating 'ALWAYS PREFER over sequential single-pack 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?

The description provides clear when-to-use guidance ('ALWAYS PREFER over sequential lookups') and includes natural language triggers. It doesn't explicitly exclude alternatives but implies this is best for 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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's mention of 'Create' aligns but adds no new behavioral insights. The idempotentHint=true is noted but not elaborated. The description adds value by mentioning the return format but does not address potential side effects or error conditions.

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 long, front-loads the core action, and contains no extraneous information. Every word serves a purpose.

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

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

The description is brief but sufficient for a creation tool, especially given that an output schema exists (as per context signals). It covers the essential input (title, content, location) and output (page ID, URL). Minor gaps like error handling or idempotency are not critical for this tool type.

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 mentions 'title and content' and 'parent page ID or space key', which slightly augments the schema's parameter descriptions but does not add significant new meaning beyond what the schema provides.

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

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

The description explicitly states 'Create a new Confluence page with title and content', using a specific verb and resource. It also mentions return values ('Returns page ID and URL') and distinguishes from sibling tools like confluence_get_page and confluence_list_pages.

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 by saying 'Specify parent page ID or space key (e.g., "ENG")', which guides the user on required identifiers. However, it does not explicitly state when not to use this tool versus alternatives like searching or listing pages.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that the tool returns page content but does not disclose additional behavioral traits (e.g., whether the page must exist, error handling, or rate limits). Since annotations cover the safety profile, the description provides minimal extra value.

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 is front-loaded and clear. While concise, it could be slightly more structured (e.g., listing parameters explicitly), but it remains efficient and easy to parse.

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

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

Given the tool's simplicity (read-only, 2 parameters, output schema exists), the description adequately covers what the tool does and returns. It omits details about page existence or error scenarios, but for a straightforward read operation, the 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?

Schema description coverage is 100%, so both parameters (page_id, body_format) are well-described in the schema. The description mentions 'by ID' but adds no further semantic detail beyond what the schema provides. At baseline 3, no additional parameter context is contributed.

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 gets full content of a Confluence page by ID and returns specific fields (title, body, status, version, space info). It uses a specific verb and resource, and the return details distinguish it from sibling tools like confluence_create_page or confluence_search.

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

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

No explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites (e.g., obtaining page ID from list/search) nor exclusions. Context is implied but not directly stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds minor value by listing the returned fields, but does not provide significant behavioral context beyond the annotations.

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

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

The description is extremely concise at two sentences, with the purpose front-loaded. Every word adds value and there is no wasted text.

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

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

Given the existence of an output schema, the description appropriately focuses on the essential input (space_id) and return fields. It is complete for a list tool with well-documented parameters and annotations.

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 on all three parameters. The description does not add extra meaning beyond what the schema already provides, so it meets the baseline expectation.

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 'List', the resource 'pages in a Confluence space', and specifies the returned fields (page ID, title, status, version). It effectively distinguishes from siblings like confluence_get_page (single page) and confluence_search (search).

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

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

The description provides clear context on when to use the tool: to list all pages in a space by specifying the space key. However, it does not explicitly mention when not to use it or suggest alternatives like confluence_search for more targeted queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds the return fields but no additional behavioral traits beyond what annotations provide. With rich annotations, the description adds marginal value.

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 action, no wasted words. Every sentence adds value.

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

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

The tool has an output schema, so return values are documented. The description mentions key fields. It lacks pagination or ordering details, but for a simple list tool with 0 required params, it is mostly 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%, and both parameters have descriptions in the schema. The description does not add new parameter information beyond stating return fields. Baseline 3 is appropriate.

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

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

The description clearly states it lists all Confluence spaces, specifies the returned fields (ID, key, name, type, status), and gives a usage hint ('discover documentation areas'). This distinguishes it from sibling tools like confluence_list_pages and confluence_search.

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

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

The description clearly states the tool lists all spaces and gives a usage hint. It does not explicitly mention when not to use it or name alternatives, but the context of sibling tools provides implicit differentiation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering core behavioral traits. The description adds that the tool returns an excerpt, which is useful but not transformative. No contradictions.

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

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

Two sentences: first defines action and method, second specifies return fields. No filler or repetition. Information is front-loaded and efficiently conveyed.

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

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

Given the presence of an output schema and the tool's low complexity (2 parameters), the description adequately covers what the tool does and what it returns. No missing context needed 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?

Schema coverage is 100% with descriptions for both parameters. The description reiterates the concept of keyword or CQL query but does not add new semantics beyond the schema examples. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Search'), resource ('Confluence pages'), and method ('by keyword or CQL query'). It distinguishes from sibling Confluence tools (create, get, list) and other search tools, making the tool's purpose unambiguous.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives (e.g., when to use confluence_get_page vs this search). No conditions, prerequisites, or exclusions are mentioned, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond this: account requirement details, parallel decomposition mechanism, gap recovery behavior per depth, contradictions[] for standard/thorough, semantic excerpting of large records, citation_uri fetchability guarantee, and expected latency ranges (15-90s). 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 reasonably concise for the amount of critical information it conveys, and it front-loads the most important constraint (account required). However, it could be trimmed – some details about contradictions and citation behavior are repeated or could be more tightly phrased. Every sentence earns its place but some are verbose.

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

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

Given the tool's high complexity (parallel research over 1462 sources, 5564 tools, call decomposition) and the presence of 2 parameters with 100% schema coverage and rich annotations, the description is complete. It explains behavior across depth levels, gap recovery, contradictions, citations, error cases (gaps[], empty results for non-structural topics), latency expectations, and auth requirements. No output schema exists, so the description rightly covers return value shape (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]).

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 both parameters (depth, question) are fully documented in the schema. The description adds useful extra semantics: clarifies what depth values do (quick=3 facets single hop, standard=3+gap recovery+contradictions, thorough=6+iterative+contradictions) and clarifies question accepts broad/multi-part queries. However, it doesn't add info about question length limits or formatting expectations.

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 verb ('Grounded multi-source research'), resource ('Pipeworx's 1462 STRUCTURED data sources'), and unique scope ('in ONE call — this is NOT open-web search'). It also explicitly distinguishes itself from siblings like ask_pipeworx.

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

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

The description provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING... prefer ask_pipeworx'), and named alternatives ('use ask_pipeworx instead – it works on every tier').

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results include curated schemas and are ready to call directly, enhancing transparency about what the tool returns without contradicting annotations.

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

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

Description is about 3-4 sentences, front-loaded with purpose and specific examples. Efficient but could be slightly tighter; no unnecessary words.

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

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

Given the tool's complexity (6 parameters, no output schema), the description fully explains the return value: top-N tools with names, descriptions, and full schemas, ready to call. Covers key aspects like limit and return format.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. Description provides examples for query but does not add significant meaning beyond the schema's own descriptions. 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?

Clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, FDA drugs, etc.). Distinguishes from sibling tools by positioning itself as a discovery tool to be called first.

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

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

Explicitly instructs when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for usage vs. alternatives.

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

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

Adds behavioral details beyond annotations: fans out across multiple sources, returns specific fields, notes USPTO PatentsView API sunset and soft-fail behavior, and states it's a parallel call. Annotations (readOnlyHint, idempotentHint) are consistent.

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

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

The description is dense but well-organized: starts with example intents, states preference, lists sources and return fields, includes soft-fail note, and ends with input constraints. Every sentence adds value.

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

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

Without output schema, the description fully explains return values (cik, filings, fundamentals, patents, news, LEI) including format for filing URIs. Covers multi-source aggregation and limitations, making it complete for a complex tool.

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

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

Schema coverage is 100% with clear descriptions for both parameters (type enum, value ticker/CIK). The description reinforces the name limitation and suggests resolve_entity, but adds limited new semantic information 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 specific verbs (profile, tell me about, research) and resources (US public company) and explicitly distinguishes from sibling tools like resolve_entity and chaining single-pack lookups. It lists example intents and states 'ALWAYS PREFER over chaining'.

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

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

Provides explicit when-to-use: 'when the user asks for a holistic view' and what to avoid: 'over chaining single-pack lookups'. Also directs to resolve_entity for names, which is a specific alternative.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds 'Delete' which is consistent but does not offer additional behavioral context beyond the annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly concise and 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?

For a simple delete operation with one parameter and no output schema, the description is sufficient. It includes usage context and references sibling tools, making it 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% with description 'Memory key to delete.' The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the action, resource, and method. It distinguishes itself from siblings 'remember' and 'recall' by focusing on deletion.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also references sibling tools for pairing, providing clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool fetches the page and extracts specific elements, which aligns with the read-only nature. It does not contradict annotations. It could mention that it does not modify the source, but the annotations already cover that.

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 short sentences with zero waste. The first sentence covers what, how, and output. The second lists use cases. It is front-loaded and every phrase earns its place.

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

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

Given the low complexity (2 params, 100% schema coverage, no output schema), the description fully explains the tool's behavior, output format, and use cases. Annotations cover safety. No gaps for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, with clear descriptions for both 'url' and 'max_links'. The description reiterates the default and maximum for max_links but adds no new meaning beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt', and explains the process: fetches page, extracts title/description/key links, emits standard markdown. It also mentions AI crawlers and the single-text-blob output format. The purpose is distinct from sibling tools like 'scan_competitor_ai_presence' or 'deep_research', as none focus on llms.txt generation.

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

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

The description provides explicit use cases: indexing a client's site, drafting for your own project, auditing competitors. It implies when to use by stating 'useful for'. However, it does not specify when not to use or mention alternative tools, which would elevate it to 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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds scope (caller's subscriptions) and return fields, but no critical behavioral traits 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?

Two sentences with no fluff: first states purpose and return fields, second gives usage guidance. Every word earns its place.

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

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

For a simple tool with one optional boolean and no output schema, the description covers purpose, return fields, and usage context adequately. No gaps remain.

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

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

Schema coverage is 100% and the schema describes the parameter well, but the tool description does not mention the include_inactive parameter or add any nuance. The baseline is 3, but lack of description support reduces usefulness.

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 (list) and resource (the caller's active subscriptions), and mentions the return fields. It distinguishes from siblings like subscribe and unsubscribe, which handle creation and removal.

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 advises when to use: 'before adding more' subscriptions or 'to find an id to cancel'. This provides clear context, though it doesn't explicitly state when not to use.

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

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

Annotations are all false, so the description carries the full burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), the claim_token mechanism, and what happens without an account. It even notes that the team reads digests daily, giving the agent insight into response expectations.

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

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

Although the description is long, every sentence provides distinct value: purpose, use cases, exclusions, claim_token mechanics, rate limits, and quota impact. It is front-loaded with the core purpose and maintains a logical flow, making the length justified and each sentence purposeful.

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 moderate complexity (nested context object, optional parameters, no output schema), the description is remarkably complete. It covers what the tool does, when to use it, what not to do, how follow-up works, rate limits, and the fact that it is free. There are no significant gaps left for the agent to wonder about.

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 each parameter is well documented in the schema. The description adds additional semantic guidance beyond the schema by explaining the claim_token flow in context and instructing agents not to paste end-user prompts, which enriches parameter understanding beyond the raw schema.

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

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

The first sentence states a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the tool from sibling tools like ask_pipeworx or discover_tools, making its unique purpose unmistakable.

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

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

The description explicitly enumerates when to use the tool (bug, feature, data_gap, praise) and, crucially, when not to: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is a model of clear usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by disclosing data source (CF analytics-engine), no PII, and caching window (5min-1h). No contradictions.

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

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

Three sentences and a bullet list, all front-loaded with the core purpose. Every sentence adds value—no filler or redundancy.

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

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

Despite no output schema, the description explains return format (top tools, packs, volume), caching, and data derivation. Sufficient for an agent to understand what the tool provides.

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 the window parameter with enum and description. Description adds: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides meaningful selection guidance 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 returns top tools, top packs, and call volume over a recent window. It uses specific verbs ('returns') and specifies the resource ('what other AI agents are calling'). No sibling tool has a similar purpose, so differentiation is 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?

Explicitly lists three use cases (discovering hot data, confirming popular tool, aligning use case). Does not explicitly exclude scenarios or name alternatives, but the context is sufficient for an agent to decide when to use.

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

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

Annotations already show readOnly, openWorld, idempotent, non-destructive. Description adds substantial behavioral details: semantic anchor (0.30 Jaccard), partition filter (placeholder slugs, >20% placeholder fraction returns null), fill check (realizable edge vs theoretical, thin_legs), and signals for deviations >3pp. 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?

Description is detailed and well-structured: opens with purpose, then mode breakdown, then technical details (semantic anchor, partition filter, fill check). However, it is relatively long and could be slightly more concise while retaining key information.

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

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

Given the tool's complexity (three modes, multiple checks, fill risk reference) and lack of output schema, the description is remarkably complete. It explains the response structure, mentions related tool polymarket_fill_risk, and covers all necessary operational details.

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

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

Schema coverage is 100% with parameter descriptions, but the tool description adds extensive context: explains event slug format, topic as seed question, and the internal logic for each mode (monotonicity checks, partition sum, cross-event scanning). This goes far beyond the schema alone.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and the description differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Recommends event mode for specific market. Lacks explicit when-not-to-use but context is clear.

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

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

The description provides extensive behavioral details beyond the annotations (readOnlyHint, etc.), such as caching ('Cached 1h at the KV level'), response structure (by_segment, diagnostics), and internal model logic. It does not contradict the annotations. While very detailed, it adds significant transparency.

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

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

The description is excessively long (nearly 600 words) and unstructured as a single paragraph. While detailed, it could be significantly condensed and organized into sections (e.g., purpose, usage, filtering, output) to improve scannability for an AI agent. The 'front-loaded' principle is only partially followed.

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 (9 parameters, no output schema), the description is highly complete. It explains the response structure (by_segment, diagnostics), output fields (e.g., edge_pp_net, kelly_fraction), caching behavior, and even internal model details. An agent would have sufficient context to understand the tool's full behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'tradeable-edge knobs' and provides context for parameters like min_liquidity and max_spread_pp, but does not add new parameter information beyond what the schema already provides. The schema descriptions are already thorough.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan') and resource ('Polymarket markets'), and the purpose is distinct from sibling tools like polymarket_arbitrage. The description goes further to explain the three model segments, making the tool's function unambiguous.

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

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

The description explicitly states when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides guidance on filtering via tradeable-edge knobs (min_liquidity, max_spread_pp, etc.). However, it does not explicitly mention when NOT to use this tool or compare it to alternatives like polymarket_arbitrage, which would have warranted 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent with description. Description adds extensive behavioral details: snapshot TTL (60 days), decay computation from daily closes not intraday, response structure for tracked vs expired opportunities.

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?

Well-structured with clear sections (RESPONSE, LIMITS). Front-loaded with core purpose. Every sentence contributes meaningful 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 no output schema, description thoroughly explains response fields (tracked, expired, snapshot_dates) with details on trend, decay, lifespan. Covers limits and assumptions completely for a tracking 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% with descriptions, but description adds context: default/max days, window family meanings, and explanation of gaps due to cache-miss. Adds value beyond schema.

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

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

Description explicitly states it provides edge persistence and decay telemetry, answering a specific question about edge duration. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on time-series tracking.

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?

Explanation of when to use is clear (understand edge persistence vs decay). Implicitly suggests when not to use (for single snapshot edges, use polymarket_edges), but lacks explicit alternatives or exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it walks the order ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), and discloses risks like thin_legs, forced_directional_risk, and max_clean_notional. 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 thorough but slightly lengthy. However, it is well-structured with keywords in caps and bullet points, and each sentence adds value. It front-loads the core purpose and requirements, making it efficient for an agent to parse.

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

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

Despite no output schema, the description details return values for both modes, including error conditions and risk indicators. It covers edge cases (thin books, partial fills) and provides sufficient context for an agent to understand inputs, outputs, and failure modes.

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

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

Schema description coverage is 100% for all 4 parameters. The description enhances understanding by explaining default behaviors (e.g., side auto-detection in basket mode, size_usd interpretation as settlement notional for basket) and providing examples. While schema already covers basics, the description adds meaningful context beyond schema.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes with specific example outputs, and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool instead.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the rationale—theoretical overround on thin books is not capturable and partial basket fills convert arb into unhedged directional position.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description goes far beyond by detailing response fields (leg-by-leg prices, matched spreads, compatibility warnings, temporal alignment) and edge cases (skipped cross-types/subtypes). No contradictions.

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

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

The description is comprehensive and well-structured with sections for modes, response, and safety fields. Though lengthy, it is front-loaded and each sentence provides value. Could be slightly more concise but remains effective.

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

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

For a tool with 3 parameters and no output schema, the description covers response format, error conditions (compatibility_warning, temporal alignment), and usage modes. It is complete and leaves no critical gaps.

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

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

Schema coverage is 100% and descriptions are good. The tool description adds context about mode interaction (explicit overrides topic) and the meaning of each parameter beyond the schema. This adds value on top of the baseline 3.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by specifying the multi-venue scope. The two modes (topic and explicit) are explicitly described.

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

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

The description explains when to use the tool (to compare spreads) and provides caution that real spreads are rare and pre-mapped topics often yield warnings. It does not explicitly list sibling alternatives but implies usage context well.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds transparency about scoping ('Scoped to your identifier...'), which is not in annotations. No contradictions.

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

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

Three sentences, each serving a distinct purpose: defining action, providing use cases, and noting scope. No redundancy or fluff.

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

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

For a simple tool with one optional parameter, no output schema, and comprehensive annotations, the description fully covers purpose, usage scope, and pairing with siblings, leaving no gaps.

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

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

Schema coverage is 100% with a clear description. The description adds value by explaining the behavior of omitting the parameter ('list all saved keys') and providing usage context (examples), going beyond just the schema.

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

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

The description clearly states the verb ('Retrieve' or 'list') and resource ('value previously saved via remember' or 'all saved keys'), and distinguishes from siblings by naming 'remember' and 'forget' as paired tools.

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

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

Explicitly states when to use the tool ('to look up context the agent stored earlier') with concrete examples (ticker, address, notes), and provides alternative actions ('Pair with remember to save, forget to delete').

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds details: mark_read effect (flags read so next call shows newer ones), fields returned (source, citation_uri, payload), and alternative access method. No contradiction with annotations.

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

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

Three well-structured sentences. First sentence states purpose and output fields. Second explains filtering. Third covers mark_read and alternative URL. No wasted words, front-loaded with key info.

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

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

Covers purpose, filtering, mark_read behavior, and alternative URL. Missing explicit mention of 'unread_only' parameter behavior (though implied) and possible 'type' values beyond example. Given no output schema, sufficiently complete for a read-only list 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 basic descriptions. The tool description adds value by providing examples (type 'sec_8k') and explaining behavior (ISO timestamp for since, mark_read flag). This goes beyond the schema's parameter descriptions.

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

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

The description clearly states it pulls fired events from the subscription feed, with specific verb 'Pull' and resource 'subscription feed'. It distinguishes from siblings like 'list_subscriptions' by focusing on alerts from the evaluator's persisted feed.

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

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

Provides clear context: mentions polling works fine and gives alternative URL for scripts/dashboards. Implicitly contrasts with direct HTTP access. Does not explicitly compare to sibling tools like 'subscribe' or 'list_subscriptions', but the purpose is distinct.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: it fans out to multiple sources (SEC, GDELT, GNews, USPTO), explains fallback logic (GDELT preferred, GNews on rate-limit/5xx), and notes the USPTO API sunset soft-fail. 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 longer but well-structured: starts with usage examples, then explains functionality, sources, parameter details, and alternative tool. Every sentence adds value, though it could be slightly more compact. Still, it avoids redundancy and is easy to parse.

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

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

Given no output schema, the description compensates by specifying the return structure: 'Structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers purpose, parameters, behavior, and alternatives comprehensively. No gaps identified.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by clarifying accepted formats for `since` (ISO or relative), suggesting '30d' for typical monitoring, confirming `type` only supports 'company', and giving examples for `value`. This provides meaningful extra guidance.

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

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

The description explicitly states the tool's purpose: 'change feed for a company in the last N days/weeks/months'. It provides numerous query examples ('What's new with X', 'latest on Y') that make the tool's intent immediately clear. It also distinguishes itself from the sibling 'entity_profile' by specifying when to use each.

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 offers clear usage guidance through example queries and explicitly states when not to use the tool: 'Use entity_profile instead when you want the static profile'. This direct alternative reference helps the agent choose correctly.

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 behavioral context beyond annotations: persistence duration for anonymous sessions (24 hours) and key-value scope. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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 informative but somewhat lengthy. However, every sentence is purposeful, and it is well-structured. Minor reduction could improve conciseness without losing clarity.

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

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

Given no output schema and simple key-value input, the description is complete. It covers purpose, usage, persistence, and associated tools, leaving no significant gaps.

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

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

Schema coverage is 100%, but the description adds meaningful examples (e.g., 'subject_property', 'target_ticker') and clarifies value can be 'any text'. This enhances understanding beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It uses specific verbs and resources (key-value pair) and distinguishes from siblings like recall and forget.

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

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

The description provides explicit guidance on when to use ('when you discover something worth carrying forward'), when not to use implicitly, and pairs with recall and forget. It also differentiates between authenticated and anonymous sessions.

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 safety (readOnly, idempotent, non-destructive). The description adds significant behavioral context: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of identifier sources, and the handling of unresolved identifiers. This goes well beyond annotations and clarifies expected 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 quite long and dense, with many sentences covering edge cases and optional enrichments. While the information is valuable for a complex tool, it could be more succinct without losing essential guidance. It is well-front-loaded with examples and the core purpose, but the length reduces overall conciseness.

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

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

Given the tool's complexity (multiple entity types, multiple identifier sources, flexible input formats, no output schema), the description thoroughly covers what the agent needs to know: supported types, input flexibility, resolution behavior, source labeling, unresolved handling, and internal cascading. It is complete enough for accurate tool selection and invocation.

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

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

Schema coverage is 100%, but the description adds substantial semantic detail: for company type it specifies accepted input forms (ticker, CIK, ISIN, name) and explains the ISIN-to-LEI mapping; for drug type it clarifies brand/generic acceptance. This enriches the schema's basic descriptions, which only give one field-specific example.

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 names to canonical/official identifiers with a specific verb and resource ('resolve a user-spoken NAME to the canonical/official identifiers'). Examples ('ticker for...') and the explicit 'Use FIRST whenever you have a name but need an ID' distinguish it from sibling tools like entity_profile.

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

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

Provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and contextual examples that imply the appropriate use case. However, it does not explicitly name alternative tools (e.g., entity_profile) or state when not to use this tool, 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 provide idempotentHint, readOnlyHint, etc. Description adds behavioral details beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific metrics (score, confidence, signal density). No contradictions.

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

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

Two sentences: first sentence defines core function, second provides use case and details. Every sentence is informative and concise with no wasted words.

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

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

Despite lacking an output schema, the description clearly states what is returned ('ranked list with score, confidence, signal density per entity'). Combined with rich annotations and clear parameter docs, the description fully covers the tool's purpose, behavior, and usage context.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds minor context (e.g., 'First entry treated as subject') but does not significantly extend parameter meaning beyond what the schema provides.

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

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

The description uses specific verbs and nouns: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling 'ai_visibility_check' by focusing on multi-entity comparison and ranking.

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

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

Explicitly states 'Useful for competitive AI-marketing audits' with an example query, giving clear context. Does not explicitly mention when not to use or alternatives, but the sibling 'ai_visibility_check' is implied for single-entity checks.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds behavioral details beyond annotations: it fans out across two services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30 seconds. This provides useful context for the agent.

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 dense paragraph that packs substantial information without unnecessary words. It could benefit from slight structuring (e.g., bullet points), but it remains concise 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?

Despite no output schema, the description thoroughly lists return fields (summary block, per-advisory detail, links, alternative versions) and explains error handling. Given the tool's complexity (two sources, partial failures), the description is complete and leaves no critical gaps.

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

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

Schema description coverage is 100% — both 'package' and 'version' have descriptions in the schema. The description adds minor context (defaults to latest version, scoped packages accepted), but does not significantly go beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it's a composite check for npm packages, combining deps.dev (license, advisories, version history) and bundlephobia (bundle size, dependencies, ESM support). It distinguishes from siblings like 'deep_research' or 'scan_competitor_ai_presence' by being specific to npm dependency evaluation.

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

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

Explicitly says 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also notes limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding when not to use this tool.

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

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

Adds significant behavioral details beyond annotations: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, caps at 200K chars with truncation and flagging. 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?

Single paragraph with clear front-loading of purpose. Every sentence adds value: usage context, pairing, technical details. No wasted words.

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

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

Given 3 parameters and no output schema, description explains return format (passages with offsets and similarity scores), truncation behavior, and pairing with sibling tool. Complete for complexity.

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

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

Schema coverage is 100%, and description adds meaning: clarifies text max size, gives limit range and default, provides query examples. This fully compensates for schema descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific verb 'search' and resource 'fetched record'. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining its role as a retrieval step.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Mentions alternative pairing with ask_pipeworx_grounded and explains benefit: 'saves context, returns only the passages that matter'.

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 (idempotent, not destructive), description adds key behaviors: OAuth requirement, phone verification, SMS cap, webhook auto-disable, and one-time secret delivery.

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?

Well-organized with clear progression (purpose, prerequisites, types, channels), though slightly dense; every sentence earns its place.

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

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

Given no output schema and complex configuration, description covers all essential aspects: return value, prerequisites, type-specific params, delivery options, and limitations.

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

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

Schema has 100% coverage, but description adds value with concrete examples for each type's params and detailed explanation of delivery options, including HMAC verification.

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 specific verb 'Create' and resource 'proactive monitoring subscription', clearly distinguishing from sibling tools like list_subscriptions and unsubscribe.

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

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

The description states prerequisites (Pipeworx OAuth account) and provides context for when to use, but lacks explicit exclusion criteria for when not to use.

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

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

Builds on annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by describing the returned content structure: category-bucketed examples with exact tool+argument shape. Adds behavioral context beyond annotations.

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

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

Description is informative and front-loaded with alternative phrasings, but slightly verbose. Could be trimmed while retaining key info. Still clearly structured with purpose, usage, and parameter details.

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 explains what is returned (category-bucketed example questions with tool+argument shape) and lists topics. Lacks mention of limits per category but sufficient for onboarding.

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 100% schema coverage, the description adds semantic value by explaining the topic parameter's effect (focus area vs. cross-category) and listing possible values: finance, pharma, economics, etc.

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: an onboarding entry point returning category-bucketed example questions. It uses specific verbs like 'returns' and distinct resource description, differentiating it from tools like ask_pipeworx or discover_tools.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides guidance on using with/without topic, but lacks explicit exclusion of 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?

Adds significant value beyond annotations: explains that the row is deactivated (not deleted), which aligns with destructiveHint=false, and mentions ownership enforcement. No contradictions with annotations (idempotentHint=true is not contradicted). Provides concrete behavioral details.

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

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

Extremely concise: two sentences that front-load the action and then add key details. No superfluous information, each sentence earns its place.

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

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

For a simple tool with one required parameter, no output schema, and good annotations, the description provides all necessary context: purpose, behavior, ownership, and parameter source. Fully complete.

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

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

Schema coverage is 100% and the parameter description in the schema ('Subscription id (uuid) returned by subscribe') is clear. The tool description does not add extra semantic meaning beyond that, so baseline 3 is appropriate.

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

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

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

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

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

The description provides clear context: ownership is enforced, so users can only cancel their own subscriptions. It also explains the row is deactivated, not deleted. It does not explicitly mention when not to use or alternatives, but the context is sufficient for most cases.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds critical behavioral semantics: the distinction between could_not_verify (check did not happen, must not be used as evidence) and unsupported (no source), the verdict set, and the pipeline routing (SEC EDGAR + XBRL with exact math vs grounded pipeline). This goes far beyond annotation and prevents dangerous misuse.

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

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

The description is long but front-loaded: it begins with purpose and trigger examples, then dives into routing, output, and a high-importance caller warning before ending with an efficiency note. Every section adds necessary information; the formatting with line breaks and 'IMPORTANT for callers' helps scanning. Though verbose, the complexity of the tool justifies the length.

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

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

Given the tool has no output schema, the description must explain return values—it does, listing the possible verdicts, the inclusion of a grounded/structured actual value with citation, and reasoning. It also covers error semantics (verification_error with stage/detail) and what unsupported means. The main gap is lack of explicit instructions on when not to use (e.g., subjective questions), but for a claim-verification tool the core cases are covered.

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 structural meaning is already documented. The description enriches tolerance_pct with tactical guidance ('set 1–2 for hallucination detection where any material error must be refuted') and explains how default tolerance is implied by wording and capped at 5. It also gives concrete examples of claim input, adding practical semantics beyond schema.

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

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

The description opens with natural-language trigger phrases and explicitly states 'natural-language claim verification against authoritative sources,' clearly distinguishing it from sibling QA tools by naming the verdict output and the two processing paths (SEC EDGAR fast path vs grounded pipeline). This gives a specific verb+resource with strong differentiation.

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

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

It says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving an explicit usage context. It also explains the two routing branches and notes that it replaces 4–6 sequential calls, implying efficiency vs alternative multi-step approaches. It does not name specific sibling tools, so it lacks explicit exclusions, but the guidance is clear.

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