Dane Gov Pl

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

Annotations (readOnlyHint, idempotentHint) indicate safe read operations. The description adds behavioral context: probed models, scoring range, return structure, and cost implications (free vs BYO key). 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 efficient, front-loading the core function and then detailing optional parameters and return structure. Every sentence adds value with no redundancy or fluff.

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

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

Given no output schema, the description adequately covers return format per model and combined view. It mentions scoring range (0-100) and components (score, confidence, signals, raw_response). It does not specify limitations like rate limits, but is sufficient for typical use.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema: default model, examples for 'entity', explanation that '_apiKey' is passed through to Anthropic, and return format hints. This enriches the agent's understanding of parameter usage.

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 ('probe', 'score') and clearly identifies the resource ('LLMs', 'business/brand/product/topic'). It distinguishes from sibling tools like ask_pipeworx by focusing on visibility scoring rather than general Q&A or research.

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

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

The description explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass an API key for Anthropic. It does not explicitly exclude alternatives, but the context of sibling tools implies when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so the safety and predictability profile is clear. The description adds valuable behavioral context: it routes to one of 5,564 tools, fills arguments, returns structured answers with stable citation URIs, and works on all tiers. It does not contradict annotations. A slight deduction because it doesn't mention rate limits or call cost, but highly transparent overall.

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 key guidance ('PREFER OVER WEB SEARCH') and is well-structured. It is somewhat long but warrants the length given the number of competitors and use cases. A slight deduction for redundancy in listing many example questions and data domains, but generally efficient.

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

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

Given the tool's complexity (routing to thousands of sub-tools) and the lack of an output schema, the description is remarkably complete. It covers purpose, usage guidance, behavior, parameter semantics, and examples. No significant gaps remain for an agent to misinterpret or misuse the tool.

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

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

Schema coverage is 100% with all six parameters described as aliases for 'question'. The description adds meaningful usage context beyond the schema, such as the types of questions that work and examples. However, since the schema already adequately documents the parameters, the description adds moderate value. The alias list is comprehensive but repetitive, slightly reducing the score from 5.

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

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

The description clearly states the tool's purpose: answering factual questions by routing to authoritative structured data sources. It lists specific domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes itself from web search, making the verb+resource+scope very precise.

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 (e.g., 'PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-not-to-use alternatives (step up to ask_pipeworx_grounded for verbatim evidence or deep_research for broad questions). It also specifies query cues like 'what is', 'look up', etc. This is comprehensive usage direction.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the tool's safe, read-only, idempotent behavior is covered. The description adds useful context about the fallback behavior (falls back to nothing—this IS a full working router) and the experimental lifecycle, but doesn't detail what happens during a test (e.g., error handling results comparison latency). With good annotations, this is adequate but not enhanced.

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 key information (beta version, identical router) and keeps sentences focused. It is slightly verbose in explaining the candidate testing history and fallback mechanics, but the extra detail is justified for transparency. A minor trim could improve conciseness without losing meaning.

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

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

Given the tool's complexity (a beta router for thousands of sub-tools) and the fact that annotations and schema cover read-only, idempotent behavior and parameter details, the description covers all necessary aspects: purpose, current state, usage instructions, and lifecycle. No output schema exists, but the description accurately notes the response shape is identical to ask_pipeworx, so completeness is high.

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 itself provides detailed descriptions for each parameter, including aliases. The description does not add any semantics beyond what the schema already offers—there is no mention of parameter usage, formatting, or constraints. Baseline 3 is appropriate since schema does the full job, but the description adds no value in this dimension.

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

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

The description clearly states this is a 'beta version of ask_pipeworx' that is an 'identical universal router' with the same tools and arguments. It distinguishes itself from the main tool by explaining it contains candidate routing improvements under test, and explicitly notes that no candidate is currently active so it matches ask_pipeworx exactly. This makes the purpose and current behavior 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 explains to 'use it exactly like ask_pipeworx when you want the newest routing,' providing clear context for when to select this tool versus the stable version. However, it doesn't explicitly say when NOT to use it or mention alternatives like ask_pipeworx_grounded, which is a sibling. The guidance is strong but could be more comprehensive about exclusions.

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

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

The description thoroughly discloses behavioral traits beyond what annotations provide. It explains the internal routing and extraction process, the return structure including refusal reasons, and the explicit refusal scenarios (not_in_source, no_tool_match, etc.). The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds rich context about how the tool operates and what to expect on failure.

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

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

The description is well-structured and front-loaded with the most important info (purpose and alternative). It covers behavioral transparency and usage guidelines efficiently in ~5 sentences. One could argue that listing all refusal reasons inline is slightly verbose but justifiable given the tool's high-stakes domain. Overall, it earns its 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's moderate complexity (1 required param, 6 optional aliases, no output schema, no nested objects), the description is entirely complete. It explains the return format, refusal scenarios, and when to use alternatives. No gaps remain for an agent to misunderstand usage or 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 schema already documents all parameters. The description does not need to add much parameter-level detail. It mentions that the tool accepts a natural language question, which aligns with the schema. However, it does not add extra meaning beyond what the parameter descriptions provide (e.g., it doesn't clarify that multiple aliases exist). Baseline 3 is appropriate given high coverage.

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

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

The description begins with a specific, high-value purpose statement: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from sibling ask_pipeworx by highlighting the extraction-only behavior and explicit refusal mechanism. The verb 'ask' is contextualized with the key differentiator of groundedness.

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 this tool (high-stakes reads, when answer will be quoted/cited/acted on, specific domains like financial verdicts, legal claims) and when not to ('prefer ask_pipeworx for casual lookups'). It also notes the cost trade-off (one extra LLM call). This is exemplary usage guidance.

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

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

Description adds extensive behavioral context beyond annotations: resolver contract with confidence levels, parent event extractor, news fields with fallback handling, safety mechanisms for low-confidence and closed markets, tradeability notes, and cancellation rule parsing. 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 very long and dense, covering many details and edge cases. While thorough, it is not concise or front-loaded; the second sentence is the purpose, but later sections are exhaustive. Every sentence is valuable but could be more structured for quick scanning.

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

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

Without an output schema, the description fully explains return shapes, resolver contract, parent events, news fields, safety flags, tradeability, and cancellation rules. It covers all expected outputs and edge cases 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%, baseline is 3. Description adds value by explaining the market parameter accepts slug, URL, or question text; depth enum defaults to thorough; include_raw defaults to false with recommendation. Provides meaningful extra context.

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 researches a Polymarket bet by pulling Pipeworx data, specifying inputs (slug, URL, question text) and outputs (evidence packet + comparison). It is specific but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Explicitly provides usage scenarios: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Does not mention when not to use or alternatives, but the 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?

The description adds significant behavioral context beyond annotations: it explains how off-calendar fiscal years are handled, that results are sorted by primary metric for easy reading, and that it replaces 8–15 sequential lookups. Annotations already indicate read-only, open-world, idempotent, and non-destructive, and the description is 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 front-loaded with common query patterns and is well-organized, but it is slightly verbose. Every sentence provides value, but some minor trimming could improve 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 no output schema, the description fully explains return values: paired data plus citation URIs. It covers both entity types, data sources, sorting behavior, and replaces many sequential lookups. Nothing essential is missing.

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

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

Although schema coverage is 100%, the description adds essential meaning: it details that for type='company' it pulls latest 10-K revenue, net income, cash, long-term debt, and for type='drug' it pulls FAERS counts, FDA approvals, etc. It also clarifies that values should be tickers/CIKs for companies and drug names.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2–5 companies or drugs, pulling specific financial or adverse-event data. It distinguishes itself from sibling tools like entity_profile, which does single entity 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 explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, providing example queries like 'compare X and Y' or 'rank these companies'. However, it does not explicitly mention when not to use it, such as when only a single entity is needed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying the return format (JSON:API dataset object) and listing included fields. 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, no wasted words, front-loaded with key information. 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 the tool's simplicity (2 params, no nested objects, no output schema), the description is fairly complete. It covers what, how, and what to expect. Could mention optional lang effect but schema covers it.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'numeric id' but does not add significant meaning beyond the schema. The 'lang' parameter is not addressed in the description.

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

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

The description clearly states the action ('Get full metadata'), resource ('single dataset'), and identifier ('by numeric id from search_datasets'), distinguishing it from sibling tools like search_datasets and other read-only tools.

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

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

The description implies the tool should be used after search_datasets to retrieve full details, providing clear context. It could be more explicit about when not to use it, but the guidance is sufficient for an AI agent.

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

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

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds extensive behavioral context beyond annotations: the research process (parallel decomposition, routing to 5,564 tools), return format (findings packet with evidence, confidence, gaps[], contradictions[], hop field), depth mode behaviors (gap recovery, lead chasing), timing expectations (15-90s), and source citation details. 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 lengthy but every sentence adds necessary information. It front-loads critical preconditions (account requirement, alternative tool) and organizes information logically: core capability, depth modes, limitations, return details. A slight restructuring could improve readability, but it avoids redundancy and remains efficient for its breadth.

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 thoroughly explains what the tool returns (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field). It covers edge cases (breaking news → empty gaps), depth mode differences, timing, and semantic excerpting. With only two well-documented parameters, the description fully equips an agent to understand inputs, outputs, and behaviors.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the enum values for 'depth' (quick=3 facets, standard=3 with gap recovery+contradictions, thorough=6 with iterative hop) and clarifying that 'question' accepts broad/natural language queries. This extra detail improves parameter understanding beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources in one call. It distinguishes itself from sibling tools like ask_pipeworx by emphasizing broad, multi-part questions vs. single lookups, and explicitly notes it is not open-web search.

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

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

The description provides clear guidance on when to use this tool vs alternatives. It explicitly says to use ask_pipeworx for single lookups and for breaking/news topics, and mentions an account requirement with a fallback (ask_pipeworx) for non-signed-in users. It also explains when deep_research returns empty results, helping the agent avoid inappropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns top-N results ready to call directly with full schemas, enhancing transparency 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?

Single paragraph, front-loaded with purpose, lists use cases efficiently, and ends with actionable output description. Every sentence adds value.

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

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

For a discovery tool, the description covers what it does, when to use it, and what it returns (names, descriptions, schemas, examples). No output schema exists, but the description adequately sets expectations.

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 3 is appropriate. The description mentions the limit parameter's defaults and aliases for query, but this info is already in the schema; no significant extra semantics added.

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 finds tools by describing data or task, provides concrete use cases (SEC filings, financials, etc.), and distinguishes it 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?

Clear guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It explains when to use (browsing/searching) and implicitly when not (when you know the exact tool).

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

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

Annotations already indicate safety (readOnlyHint, idempotentHint, destructiveHint=false). The description adds context: it fans out across multiple sources, returns specific fields, notes that patents soft-fail, and that it makes a parallel call. 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 somewhat long. It front-loads with example queries, which is good. Every sentence adds value, but could be slightly more structured (e.g., bullet points for returned fields). Still, it's efficient given 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?

Given the tool's complexity, the description fully explains what the tool does, what it returns, its limitations, and when to use alternatives. No output schema exists, so the description must carry the burden, and it does so completely.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains that 'type' only supports 'company' for now, and that 'value' can be a ticker or zero-padded CIK, and clarifies that names are not supported. This goes beyond the schema descriptions.

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

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

The description clearly states the tool returns a 'full cross-source profile of a US public company', using specific verbs like 'brief me on' and 'research'. It distinguishes itself from siblings like 'resolve_entity' and 'compare_entities' by noting that for names one should use 'resolve_entity' first, and for holistic view this is preferred over chaining single-source 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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides clear when-not-to-use: 'names not supported (use resolve_entity first if you only have a name).' This gives strong guidance on alternatives.

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

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

Annotations already declare destructiveHint: true and idempotentHint: true. The description adds that it deletes by key but doesn't introduce new behavioral details beyond annotations. No contradiction.

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

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

Extremely concise: two sentences that cover purpose, usage guidance, and sibling tools. No redundant information.

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

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

For a simple deletion tool with one required parameter and no output schema, the description fully addresses purpose, usage, and behavioral context. Suitable for accurate tool selection.

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

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

Schema coverage is 100% and the schema description for 'key' is sufficient. The description does not add param-level details, which is acceptable given full schema coverage.

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

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

The description clearly states the action (delete), the resource (previously stored memory), and the identifier (by key). It distinguishes from siblings like 'remember' and 'recall' by specifying 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 provides when to use the tool: stale context, task completion, clearing sensitive data. Also suggests pairing with 'remember' and 'recall', giving clear alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds process details (fetching, extracting title/description/key links, emitting markdown) that align with annotations and provide additional transparency.

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

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

Three sentences: purpose, process, use cases. Front-loaded with key information. No filler; 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?

No output schema, but description states output is a 'single text blob' ready for deployment. Lacks error handling or edge cases, but for a simple generation tool, this is adequate.

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

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

Schema coverage is 100% so base is 3. Description implies the role of max_links but does not add significant meaning beyond the schema. Example values are omitted, but overall sufficient.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying the action, resource, and context (AI crawlers). It distinguishes from siblings like 'ai_visibility_check' by focusing on the llms.txt format.

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 use cases: client indexing, personal drafting, competitor auditing. Does not include when not to use, but the given cases are clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by specifying the returned fields and the tabular_data relationship, providing context beyond safety annotations. No contradiction found.

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

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

The description is concise with two sentences, front-loaded with the main purpose, and includes specific details without unnecessary words. Every sentence adds value.

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

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

For a simple list operation with complete schema and annotations, the description covers purpose, return structure, and hints at related tool usage. It is complete enough given the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description does not add significant meaning beyond the schema, such as constraints or format. Baseline score 3 is appropriate.

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

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

The description uses specific verb 'list' and resource 'resources', clearly distinguishing from sibling tools like 'resource_data'. It specifies the return format with key fields, 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 implies usage by stating what it does and mentions that resources with tabular_data can be read by 'resource_data', offering a hint about alternatives. However, it does not explicitly state when not to use this tool or list other 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 value beyond annotations by specifying returned fields and default behavior (active only), and aligns with readOnlyHint and 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?

Two concise sentences front-load purpose and usage, with zero 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 simple tool with one optional param and no output schema, description adequately covers return fields, usage, and safety (annotations handle rest).

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 does not significantly add meaning beyond the schema's include_inactive description, so 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?

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe by naming returned fields.

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

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

Explicitly advises using to review monitoring or find an id to cancel, providing clear context, but lacks explicit when-not alternatives.

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

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

The description discloses substantial behavior beyond the annotations: it's rate-limited to 5/day, doesn't count against quota, returns a claim_token for anonymous filing, and supports a later read-back through the same tool. It also notes team reading cadence and roadmap impact. The annotations are all false hints, so they provide no safety signals, but the description compensates fully.

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

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

The description is long but every sentence earns its place: purpose, exclusions, token workflow, rate limit, quota, and team cadence. Front-loaded with a crisp one-line purpose. No filler.

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

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

Given its dual submit/read-back behavior and the lack of an output schema, the description fully covers when, how, and why to use the tool, including constraints, token handling, and the team's response process. Nothing important is missing.

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

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

Schema coverage is 100% with detailed descriptions for each parameter, including the claim_token workflow and message constraints. The description reinforces these semantics but adds little beyond what the schema already explains; the only slight addition is contextualizing the token as a 'pwfb_…' format, which the schema already includes. Baseline 3 applies due to full schema coverage.

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

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

The description opens with a clear imperative—'Tell the Pipeworx team something is broken, missing, or needs to exist'—and then enumerates the exact categories (bug, feature/data_gap, praise). It distinguishes itself from all sibling tools by being the sole feedback/reporting tool.

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

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

Explicitly states when to use it: for issues with tools served by this Pipeworx connection. Provides an exclusion: if the tool came from a different MCP server, file with that server instead. Also clarifies not to paste end-user prompts and how to check status via claim_token.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by noting data source (CF analytics-engine), no PII, and caching behavior (5min-1h).

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 plus a bulleted list. Every sentence earns its place. Front-loaded with what it returns. No filler.

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

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

No output schema, but description adequately explains return values (top tools, packs, call volume). Covers caching and privacy. Could specify format but sufficient for selection.

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

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

Schema already fully describes the enum parameter with 100% coverage. Description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Clearly states it returns top tools, top packs, and total call volume over windows. Provides specific use cases distinguishing it from sibling tools like discover_tools or 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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tool, checking alignment). Does not explicitly state when not to use, but the context is clear from the description.

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

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

The description adds substantial behavioral context beyond the annotations. Annotations indicate read-only, idempotent, non-destructive. The description details the partition check, semantic anchor (0.30 Jaccard similarity), partition filter (placeholder slugs), and fill check (realizable_edge_pp ≤ 0 means not tradeable). No contradictions with annotations exist.

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

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

The description is well-structured with sections for modes, semantic anchor, partition filter, fill check, and response. It is front-loaded with the main purpose. However, it is slightly verbose; some parameter details could be relegated to the schema. Overall, it is informative without being overly wordy.

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 modes, checks, and response structure), the description is thorough. It covers all important aspects: input types, behavioral constraints (similarity threshold, placeholder filter), fill check logic, and response fields (opportunities[], partition_check). No output schema is provided, but the description adequately explains the return structure.

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

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

Schema coverage is 100% (both parameters described in schema). The description adds value by explaining behavior: no args for trending_scan, event slug for specific event, topic for cross-event scanning. It provides examples and clarifies that Full Polymarket URLs are accepted for event. This enriches the schema definition.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It provides a specific verb ('Find'), resource ('arbitrage opportunities on Polymarket'), and method. It distinguishes from siblings by detailing different modes (trending_scan, event, topic) and referencing related tools like 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 usage guidance is provided: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for specific markets and describes when cross-event mode is beneficial. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_edges or polymarket_fill_risk, though it does mention fill risk at the end.

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. The description adds caching behavior, response segmentation, and diagnostic information, providing rich 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?

The description is well-structured with clear sections, but somewhat verbose with detailed model family explanations. It is front-loaded with purpose but could be slightly more concise.

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

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

With no output schema, the description thoroughly explains the response structure, including segments, opportunity fields, and diagnostics. All parameters are covered, and caching is mentioned.

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 extensive context for many parameters, such as slippage_pp explaining Polymarket fees and min_partition_leg_kelly explaining why min_kelly does not apply to partition arbs.

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 scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, with a specific use-case 'what should I bet on today'. It distinguishes from siblings by detailing model families and the 'edge' concept.

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 discovering opportunities without paging hundreds of markets, and notes that Fed bets are excluded from ranking. However, it does not explicitly mention when to use alternatives like polymarket_edge_tracker.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds value beyond annotations by detailing the response structure (tracked, expired, snapshot_dates), limitations (60-day TTL, decay calculations), and the meaning of negative edge_pp_net. 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 comprehensive but somewhat verbose. It front-loads the core purpose and uses structured lists (RESPONSE: tracked[], expired[], snapshot_dates[]). Most sentences provide necessary detail, but some repetition of schema info could be trimmed.

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

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

No output schema, but the description thoroughly explains the response fields. Given the tool's complexity (time-series, trends, decay), the description covers key elements like first_seen, trend, decay_pp_per_day, and limitations. It is complete enough for an agent to understand usage.

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

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

The input schema covers both parameters with descriptions. The description reinforces these by restating defaults and allowed values ('days: default 14, max 30; window: default 1wk') and adds context about snapshot families. Schema coverage is 100%, so the description provides marginal added meaning.

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

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

The description clearly states the tool's purpose: answering how long an edge has existed and whether it is shrinking. It specifies the verb ('tracker'), resource ('edge persistence and decay telemetry'), and distinguishes from siblings like 'polymarket_edges' by focusing on time-series and trend analysis.

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

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

The description implies when to use this tool via the example contrasting a fresh wide edge with a 3-week-old one. It provides context about the lookback window and snapshot families. However, it does not explicitly state when not to use or list alternative tools.

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

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

The description adds significant behavioral context beyond annotations: it explains real-time nature (live CLOB), mode-specific behavior (single-market vs basket), risk of partial fills, and the verdict system (clean|degraded|cannot_fill). Annotations already indicate read-only and idempotent, which align with the description's check-only purpose.

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

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

The description is well-organized with clear sections for single-market and basket, and every sentence adds value. However, it is somewhat lengthy; condensing some repetitive phrasing could improve conciseness without losing information.

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

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

Given the lack of an output schema, the description fully explains return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, etc.) and the distinctive risk of basket fills (thin_legs, forced_directional_risk). This makes the tool self-contained 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 description coverage is 100%, but the description adds meaningful semantic context for each parameter: e.g., explains that size_usd for single-market is 'max spend on buys, target proceeds on sells' and for basket is 'settlement notional — shares per leg, each paying $1 at resolution'. This deepens understanding beyond the schema.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth, distinguishing between single-market and basket modes. It explicitly lists the returned fields, leaving no ambiguity about its function.

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

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

The description explicitly instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns that 'partial basket fills convert an arb into an unhedged directional position', providing clear when-to-use guidance and a key reason to use this tool.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral details: two modes, response fields (leg prices, spread, safety fields like compatibility_warning, temporal_alignment), and explains why certain comparisons are skipped (cross-type/subtype mismatches). 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 relatively long but every sentence serves a purpose. It is front-loaded with the core purpose, then details modes, response, and safety fields. The structure is logical, though slightly 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?

Despite no output schema, the description thoroughly explains the response structure and safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). Covers edge cases like mismatched bet shapes and temporal gaps, making it complete for an AI agent.

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

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

Schema coverage is 100% and each parameter has a description. The description adds value by listing the exact topic enum values (fed, btc, etc.), explaining that explicit tickers override topic mapping, and providing examples. This goes well 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?

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket. It distinguishes two modes (topic shortcuts vs explicit tickers) and describes the output structure. This distinctly differentiates it from siblings like polymarket_arbitrage.

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

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

Guidance is provided on when to use each mode and the caveat that most pre-mapped topics return compatibility_warning, nudging toward explicit tickers for real spreads. No explicit exclusion list, but the context implicitly suggests alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping details (anonymous IP, BYO key hash, account ID) and listing behavior when key omitted, enhancing 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?

Three sentences, front-loaded with primary action. Every sentence provides unique information: core function, use cases, scoping and pairing. 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 simple tool (1 optional param, no output schema, annotations cover safety), description covers purpose, usage, scoping, and pairing completely. 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 has 100% coverage with description for key parameter. Description adds value by explaining the omit-key listing behavior and pairing with remember/forget, going beyond schema.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys' with specific verb and resource. Distinguishes from sibling tools remember and forget by naming them.

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

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

Explicitly says 'Use to look up context the agent stored earlier' and pairs with remember/forget. Provides clear context but does not explicitly state when not to use it.

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

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

The annotations declare readOnlyHint=true, indicating a read-only operation, but the description explicitly describes a mutating side effect: 'Set mark_read:true to flag returned events read'. This contradicts the readOnlyHint annotation, making the description misleading. The additional behavioral context about the feed is overshadowed by this contradiction.

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

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

The description is well-structured: it starts with the main purpose, then details return fields, parameters, and usage notes. It is front-loaded and informative, but slightly longer than necessary. Every sentence adds value except for some redundancy in parameter descriptions.

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 adequately explains the return values (source, citation_uri, raw event payload). It covers all key parameters, mentions alternative access via URL, and addresses polling behavior. The context is complete for a tool with five optional parameters.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by providing examples (e.g., 'sec_8k' for type), explaining the effect of mark_read on future calls, and clarifying the meaning of unread_only. This goes beyond the schema's short 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 pulls fired events from a subscription feed, specifying return fields like source, citation_uri, and raw payload. It defines the verb 'Pull' and the resource 'fired events', but does not explicitly differentiate from sibling tools such as list_subscriptions, so it lacks sibling distinction.

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

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

The description implies usage for reading recent alerts with filters and mark_read. It mentions that polling works and provides an alternative URL for scripts/dashboards. However, it does not explicitly state when to use this tool versus alternatives (e.g., list_subscriptions) or when not to use it.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are supplemented with rich behavioral details: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-failure, return structure with grouped changes and citation URIs. 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?

Description is a single paragraph that front-loads examples but packs in sources, fallback, parameter details, and sibling reference. All sentences are informative, though slightly dense.

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 outlines the return structure (changes[] grouped by source, total_changes, citation URIs) and covers every essential aspect: purpose, sources, parameters, fallback, and sibling distinction. Fully adequate for an agent.

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

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

Schema coverage is 100%, but description adds extra context: 'type' limited to company, 'since' format and recommendation ('30d' or '1m'), 'value' as ticker or CIK. This aids correct usage 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 provides a 'change feed for a company in the last N days/weeks/months' and gives numerous example queries. It distinguishes from sibling 'entity_profile' by contrasting dynamic vs static 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 usage examples and tells when to use 'entity_profile' instead. Does not exhaustively list when not to use, but the alternative is clearly named.

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 idempotentHint=true and destructiveHint=false, but the description adds crucial behavioral context: scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions, and the pairing with recall/forget. This goes beyond annotations.

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

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

The description is a single paragraph but well-structured: first sentence states purpose, then usage guidance, then technical details. It is front-loaded, every sentence 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 tool's simplicity (2 params, no output schema), the description covers all relevant aspects: purpose, usage, behavior, parameters, and relationships to sibling tools. No missing information.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of key-value pairs, giving examples like 'subject_property', and describing the value as 'any text — findings, addresses, preferences, notes'. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the verb (save), resource (data), and context (across conversations/sessions). It also distinguishes from sibling tools 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 explicitly says when to use: 'when you discover something worth carrying forward', with examples like resolved ticker, target address. It also mentions pairing with recall and forget. It lacks explicit 'when not to use' but the guidance is strong.

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 (readOnlyHint, idempotentHint), the description reveals important behavior: it cascades through multiple lookup endpoints, labels every identifier with its source, explicitly reports unresolved identifiers under `unresolved`, and degrades gracefully if GLEIF/OpenFIGI are unavailable, still returning EDGAR identifiers. This adds significant context beyond structured annotations.

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

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

The description is long but efficiently packed with useful information, starting with relatable query examples and structured supported types. While every sentence adds value, it is denser than necessary, using long phrases like 'cross-source identity spine' that could be simplified.

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

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

Given there is no output schema, the description thoroughly covers return values for both entity types, including the `unresolved` field behavior and fallback strategy. It also covers acceptable input formats, making the tool's behavior predictable and complete for a two-parameter tool.

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

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

The schema already fully describes both parameters (type enum and value formats), but the description enriches meaning by explaining the expected output for each type: for company, the CIK/ticker/LEI/FIGI and ownership details; for drug, RxCUI, ingredient, brand, and citation. It also explains special input handling like ISIN resolving to the legal entity via GLEIF.

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

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

The description clearly identifies the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It gives concrete query examples and distinguishes it by stating 'Use FIRST whenever you have a name but need an ID,' setting it apart from sibling tools that consume identifiers.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing a strong when-to-use. It implies when not to use (when an ID is already available) and highlights efficiency ('replaces 2-3 manual lookups'), but it does not name alternative sibling tools or give explicit when-not conditions.

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 value beyond annotations by detailing the return format (JSON:API 'row' objects with {repr, val} pairs mapped from column names) and mentioning support for paging and filtering. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description does not contradict them.

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

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

The description is two sentences long, with the first sentence directly stating the purpose and the second adding return format details and usage guidance. It is front-loaded with the core action and contains no extraneous 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 has 4 parameters all documented in the schema, no output schema, and clear annotations, the description adequately covers the return format and prerequisite usage. It is complete for a read-only, filtered-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?

The input schema has 100% description coverage, with each parameter already described (e.g., 'q' as full-text filter, 'page' and 'per_page' for paging, 'resource_id' as numeric id). The description paraphrases these details and provides a usage example, but adds minimal new semantic meaning beyond the schema.

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

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

The description clearly states the tool reads row-level data from a tabular resource, specifying the required 'tabular_data' relationship. It distinguishes itself from sibling tools like 'list_resources' by indicating that one must use that tool first to find the resource id.

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

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

The description explicitly instructs users to call 'list_resources' first to obtain a valid 'resource_id', and notes that the tool supports paging and full-text filtering via the 'q' parameter. While it does not list alternative tools or explicitly state when not to use the tool, the prerequisite is clearly 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, idempotentHint, and non-destructive behavior. The description adds probed mechanism (calls ai_visibility_check per entity), ranking logic, and output structure (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 defines core action, second adds context, example, and output summary. No unnecessary words, well front-loaded.

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

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

Given no output schema but good annotations, the description covers purpose, usage context, parameters, and output format adequately. Agent can confidently select and invoke this 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 covers all 4 parameters with descriptions (100% coverage). The description adds context: entities array treats first entry as subject, models defaults to workers-ai, and context is shared. This extra info clarifies usage 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 compares AI visibility across multiple entities side-by-side, with specific verbs (compare, probe, ranks) and resources (AI visibility across entities). It distinguishes from sibling ai_visibility_check by focusing on multiple entities. The example question reinforces purpose.

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

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

The description explicitly says it is useful for competitive AI-marketing audits and provides an example use case. It implies use for multi-entity comparison vs. single-entity checks (sibling ai_visibility_check), but does not explicitly state when not to use it or name alternatives.

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

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

Annotations already mark it read-only, idempotent, non-destructive. Description adds valuable behavioral details: fans out to two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists failures. No contradiction with annotations.

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

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

Single paragraph but well-organized: starts with purpose, then usage, then technical details about partial failures. Efficiently conveys necessary information without excess. Could be slightly more structured (e.g., bullet points) but still good.

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 moderate complexity, description covers: what is returned (summary fields, advisories, links, versions), error handling (partial failures, timing), and ecosystem limitation. Sufficient for an AI agent to use correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. Description enriches by noting scoped packages are accepted, version defaults to latest, and lists output fields (summary block, per-advisory detail, links, alternative versions). 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 begins with 'Composite "should I add this npm package to my project" check in ONE call', clearly stating the verb (check/scan), resource (npm package), and outcome (safety, size, etc.). It explicitly distinguishes from sibling tools by focusing on npm dependencies and combining deps.dev and bundlephobia.

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"', and notes limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive; description adds value by specifying return format (JSON:API list), language hints, and linkage to other tools.

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 and output, followed by 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?

Description compensates for missing output schema by listing return fields; covers pagination and sorting implicitly through parameters; adequate for a simple search 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 has 100% coverage with detailed descriptions; description adds minimal extra meaning beyond mentioning portal context and language acceptance.

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 it searches/lists datasets on Poland's national open data portal, returns specific fields, and distinguishes from sibling tools like dataset_details and list_resources.

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

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

Provides context on language (Polish/English), portal origin, and links to related tools for specific dataset details, but doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds that returns JSON:API objects with specific fields and 'mostly Polish content', which enriches 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?

Two concise sentences, front-loaded with purpose and result. Every sentence adds value with no redundancy or fluff.

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

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

Given rich annotations and full schema coverage, description fully informs about purpose, return type, and content context (Polish). Pagination details are in schema, so completeness is high.

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 all 4 parameters with descriptions (100% coverage). Description adds no per-parameter meaning beyond noting q accepts Polish or English, already in schema. 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?

Description clearly states verb 'search/list' and resource 'institutions' with specific example types (ministries, agencies, etc.). Distinguishes from sibling tools like search_datasets indirectly, but lacks explicit 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?

Implies usage for searching Polish institutions with language hint, but no explicit when-not-to-use or alternatives like search_datasets. Guidance is minimal.

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

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

Discloses embedding model (BGE-base-en), algorithm (cosine), window size (500-char overlapping), character cap (200K) with truncation/flagging. These details go beyond annotations (readOnly, etc.) to fully inform 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?

Very concise and front-loaded: starts with purpose, then use case, then technical details. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description explains return format (passages with offsets and scores), embedding mechanism, and limitations. This is complete for an agent to invoke correctly without guessing about 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 coverage is 100%, so the description adds minimal new info beyond reinforcing usage (e.g., 'text you already pulled'). The baseline of 3 is appropriate as the schema already documents parameters well.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verbs and examples (SEC 10-K, article). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining how they pair.

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') and suggests pairing with another tool. Does not provide explicit negative guidance, but the positive 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?

Discloses behavioral traits beyond annotations: returns subscription id, requires OAuth, delivery channel constraints (email validation, phone verification, webhook signing, rate limits). 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?

Well-structured with bullet points and examples, front-loaded with main purpose. Slightly lengthy but 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?

Covers prerequisites, type-specific parameters, delivery channels, and limitations comprehensively. Even without an output schema, it states the return value (subscription id).

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

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

Schema coverage is 100%, but description significantly adds meaning with type-specific parameter examples, delivery channel details, and constraints like phone verification and webhook signing. Goes beyond the schema's property 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?

Clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. Distinguishes from siblings 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?

Specifies when to use the tool, including the requirement for a Pipeworx OAuth account. Does not explicitly state when not to use, but the context implies it's for creating new subscriptions only.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: the tool returns category-bucketed examples, each with exact tool+argument shape, and mentions that calling with no arguments gives the full spread. This goes well beyond what annotations provide.

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

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

The description is well-structured with a front-loaded purpose, clear examples, and logical flow. It is slightly long but every sentence adds value, covering use cases, output structure, and parameter usage. 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 role as an onboarding entry point with no output schema, the description is remarkably complete. It explains what the output contains (categorized examples with tool shapes), how to use the optional parameter, and when to invoke the tool. It addresses multiple user intents (getting started, ideas, meta-tools) 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?

The input schema has one optional parameter (`topic`) with a basic description. The description expands on it by listing specific topic values (finance, pharma, etc.) and explaining that omitting it yields a cross-category spread. Since schema coverage is 100%, baseline is 3, but the description adds meaningful extra context, raising the score.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns categorized example questions with exact tool+argument shapes. It lists alternative phrasings and use cases, distinguishing it from siblings like ask_pipeworx and discover_tools. The verb 'suggest' and resource 'questions' are specific and unambiguous.

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

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

The description explicitly advises to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional `topic` parameter for focusing queries. While it doesn't explicitly state when not to use it, the context is very clear and provides strong guidance.

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

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

The description adds significant behavioral context beyond the annotations: it explains that ownership is enforced, that the row is deactivated (not deleted) to preserve history, and that historical events are accessible via 'recent_alerts'. This aligns with the annotations (idempotentHint=true, destructiveHint=false) and provides 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 two sentences long, front-loading the action in the first sentence and adding constraints and behavior in the second. Every word is purposeful; 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?

While the description is clear about the action and side effects, it does not mention the return value or output of the tool. Since there is no output schema, the description could be more complete by indicating what the agent should expect (e.g., success confirmation).

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 describes the 'id' parameter as a UUID from 'subscribe', which covers 100% of parameters. The description adds value by implying that the ID must belong to the caller (ownership enforcement), providing context beyond the schema's literal 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 states the tool cancels a subscription by ID, using the verb 'cancel' and resource 'subscription'. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

The description explains when to use the tool (to cancel a subscription by ID) and provides important constraints (ownership enforced, deactivation not deletion). It does not explicitly state when not to use it, but the context is sufficient for an AI agent to select it appropriately.

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

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

Beyond the read-only/idempotent annotations, the description discloses the internal routing logic (structured SEC vs grounded pipeline), the full set of verdicts, and the critical distinction between could_not_verify (check did not happen) and unsupported (no source covers it). It also notes that could_not_verify must not be shown as evidence, adding crucial behavioral nuance not captured by annotations.

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

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

The description is longer than average but every section serves a purpose: trigger phrases, routing logic, verdict meanings, and error handling. It is front-loaded with examples, then explains the dual-path behavior. The only redundancy is the list of synonyms at the start, which, while helpful for classification, could be trimmed. Still, it's well structured and not wasteful.

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

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

Given the tool's complexity (two pipelines, multiple verdicts, potential errors) and the absence of an output schema, the description covers all necessary aspects: what to expect in the return (verdict, value with citation, reasoning), the meaning of each ambiguous verdict, and an explicit caller warning. It also contextualizes the tool's efficiency (replaces 4–6 calls). This is a complete description for an agent to select and invoke correctly.

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

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

The input schema already covers both parameters with descriptions, but the tool description adds meaningful context: it explains that tolerance_pct overrides the implied tolerance, gives a recommended range (1–2) for hallucination detection, and clarifies the default behavior (implied by wording, capped at 5). This goes beyond the schema's 'Max percent deviation' description, enhancing the agent's ability to choose appropriate values.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with explicit trigger phrases ('fact check', 'verify the claim that…') and a specific verb ('validate'). It distinguishes from siblings by describing its dual pipeline (SEC EDGAR fast path vs grounded pipeline) and the consolidated single-call nature, making its purpose unambiguous.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides examples of claim types (company financial vs any other). It also explains the fallthrough behavior and warns against misinterpreting could_not_verify, giving clear contextual guidance. However, it doesn't explicitly name alternative tools or state when NOT to use it, so it stops 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.