Leadconnector

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: the default free model, the need for an API key for Anthropic, cost implications, and a summary of the return structure (score, confidence, signals, raw_response). No contradiction with annotations.

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

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

The description is four sentences, front-loaded with the core purpose, and every sentence adds value. No redundancy or unnecessary details.

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

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

Despite no output schema, the description summarizes the return structure per model and combined view. For a tool with 4 parameters and optional configurations, the description is fully adequate.

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

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

Schema coverage is 100%, but the description goes beyond: it gives examples for 'entity', explains default and options for 'models', describes the key format and pass-through for '_apiKey', and clarifies disambiguation for 'context'. This is highly informative.

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: to probe LLMs for knowledge about an entity and score visibility from 0-100. It uses specific verbs ('probe', 'score') and distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on per-model scoring.

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

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

The description provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and BYO key option. However, it does not explicitly mention when to avoid using this tool or differentiate from very similar siblings like 'scan_competitor_ai_presence'.

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, open-world, and non-destructive behavior. The description adds valuable context by disclosing the internal routing mechanism, citation URI output, and performance ('one fast call'). It does not cover failure modes or rate limits, but the annotation coverage lowers the burden, making this a strong but not perfect transparency score.

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

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

The description is long but front-loaded with the key 'PREFER OVER WEB SEARCH' and the data domains, followed by usage triggers, examples, and alternatives. Each section serves a purpose, though there is some redundancy in repeatedly emphasizing it as the default/start point. Overall, it is well-structured for a complex entry-point tool.

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

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

The description covers output format (structured answer with citations), scope of questions, alternatives, and performance characteristics. Given the simple one-parameter schema and non-destructive annotations, this is sufficient for the tool's complexity. It lacks details on error handling or edge cases, but those are not critical for a read-only Q&A 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 provides 100% coverage with descriptions for all 6 parameters (aliases), but the description enriches semantics with concrete examples of valid questions and clarifies the natural language input expectation. Beyond the schema's generic 'Your question or request', it explains the range of topics and phrasing, making parameter usage more tangible.

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

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

The description uses a specific verb (routes, returns) and resource (5,529 tools, 1,455 verified sources), and clearly distinguishes itself from web search and siblings like ask_pipeworx_grounded and deep_research. It states the tool answers factual questions with citations, making the purpose unmistakable.

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

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

Provides explicit usage triggers ('what is', 'look up', 'get the latest', etc.) and states to use this as the default entry point. It explicitly names alternatives for specific scenarios: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for multi-part questions, with clear '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?

Beyond the annotations (readOnly, openWorld, idempotent), the description adds valuable behavioral context: it's a beta version with candidate routing improvements active only during tests, currently none active, and that it's a full working router, not a fallback. It also notes results are compared against the stable router, which clarifies its experimental nature.

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

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

The description is somewhat lengthy but every sentence adds value: it explains the beta relationship, current state (no active candidate), usage instruction, and reassurance that it's a working router. It's front-loaded with the core identity and well-structured for an AI agent.

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

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

The description is complete for a beta router with no output schema: it tells the agent it's identical to ask_pipeworx, including response shape, which is sufficient given the sibling tool exists. It doesn't spell out the response format, but 'same response shape' is a clear pointer, and the complexity of a 5,529-tool router makes it impractical to enumerate.

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

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

The schema covers 100% of the parameters, including aliases for the single 'question' parameter. The description adds no specific parameter details beyond saying 'same arguments' as ask_pipeworx, so the schema does the heavy lifting. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as 'Beta version of ask_pipeworx: identical universal router' with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx by noting it has experimental routing improvements enabled only when under test, and currently matches ask_pipeworx exactly.

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 'Use it exactly like ask_pipeworx when you want the newest routing', providing clear guidance on when to use it. It does not explicitly state when not to use it (e.g., for stable results) or mention alternatives like ask_pipeworx_grounded, but the beta context implies the tradeoff.

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 key behavioral traits not in annotations: it uses ONLY the tool result, returns a structured refusal with specific reasons (not_in_source, no_tool_match, etc.), and costs an extra LLM call. This goes beyond annotations and helps the agent anticipate failure modes.

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

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

The description is information-dense but well-structured: it leads with the core value proposition, then explains the mechanism, return format, use cases, and tradeoff. Every sentence adds important detail, though it is slightly long.

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 thoroughly explains the complete return payloads for both success and refusal cases, including refusal reason enums. It also covers routing scale, cost tradeoff, and ideal use cases—making the tool fully understandable in context.

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

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

Schema coverage is 100%—all six parameters are documented as aliases for 'question.' The description adds nothing about parameters beyond the schema, but the schema itself is fully self-explanatory, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the action (answering with grounded extraction), the resource (Pipeworx), and distinguishes it from the sibling ask_pipeworx by explaining the same routing but constrained output.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This gives clear when-to-use and when-not-to-use criteria with alternative tool 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant detail: resolver contract, parent event extractor, news fields, safety mechanisms (low-confidence short-circuit, closed market handling), wide-spread market warnings, and resolution-rule risk. 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 lengthy, containing many details in dense paragraphs. It is front-loaded with essential info but could be more concise. Structure via section headers helps, but brevity is sacrificed for completeness.

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

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

Without an output schema, the description fully explains response shapes (market, analysis, evidence), resolver confidence, parent event extraction, news fallback mechanisms, and safety/edge cases. It covers what agents need to handle responses correctly.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). The description adds context (e.g., depth fan-out explanation, include_raw behavior), improving understanding beyond schema. However, the schema already provides the core meanings.

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: researching a Polymarket bet by pulling Pipeworx data. It specifies multiple input formats (slug, URL, question text) and targets specific use cases like 'should I bet on X'. It distinguishes from siblings by focusing on single-bet 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?

Explicitly states when to use the tool (e.g., 'should I bet on X', 'what does the data say'). Provides examples of fan-out per category, giving context but not explicit exclusion of alternatives. Sibling tools like polymarket_edges serve different purposes (edge tracking), so guidance is adequate.

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

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

Annotations indicate read-only and idempotent, and the description adds behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions.

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

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

The description is well-structured with usage patterns first, then entity-type specifics. While it is relatively long, every sentence adds useful information. A minor reduction could improve conciseness, but it remains clear and efficient.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description adequately covers what data is pulled and how results are sorted. It mentions 'paired data + citation URIs' but could be more explicit about the output structure. Overall, it provides sufficient context for correct usage.

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

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

Schema already covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds value by clarifying that values should be tickers/CIKs or drug names and reinforces the 2–5 range, but does not add substantial new semantics 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 starts with specific usage patterns like 'Compare X and Y' and 'which is bigger,' then clearly states the tool performs side-by-side comparison of 2–5 companies or drugs. It differentiates from sibling tools by explicitly mentioning it replaces sequential lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups' and states it replaces 8–15 sequential lookups, providing clear when-to-use guidance. Implicitly excludes single-entity queries, which are handled by sibling entity_profile.

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 readOnlyHint/idempotentHint annotations, the description discloses account/payment requirements, parallel routing across 5,529 tools, the findings packet with verbatim evidence/confidence/source/fetched_at/citation, gaps[] for unanswered facets, no invention, hop fields, citation resolution guarantees, semantic excerpting, contradictions[] for standard/thorough, and expected latency. This far exceeds annotation coverage.

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

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

The description is long but appropriately so for a complex tool; no sentence is wasted. Critical access constraints and the primary alternative are front-loaded in the first sentence, followed by core functionality, distinct use cases, depth differences, and return-value details in a logical order.

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

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

With no output schema, the description fully explains the findings packet and its fields, gap and contradiction behavior, citation_uri resolvability, excerpting strategy, and timeouts. It anticipates common pitfalls (current-news gaps, large-record truncation) and covers prerequisites and pricing, making it complete for an agent to decide and invoke correctly.

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

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

Although the schema already documents both parameters at 100% coverage, the description adds specific enum semantics: quick=3 facets, standard=5 with gap-recovery hop and contradictions scan, thorough=8 paid with iterative hop plus contradictions. It also clarifies that broad/multi-part questions are acceptable, reinforcing the question parameter's natural-language flexibility.

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 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition/routing behavior, distinguishing itself from open-web search and sibling ask_pipeworx. It specifies a clear verb+resource scope: deep research over structured data, best for broad/multi-part questions.

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

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

Explicit when-to-use guidance is provided: use ask_pipeworx when not signed in, for single lookups, and for breaking/current-news topics; deep_research is recommended for broad/multi-part structured questions. It even warns that current-news queries return empty gaps[], giving clear exclusions.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavior: returns schemas with curated examples, results ready to call directly, and covers a wide range of data sources. No contradictions with annotations. A 4 is appropriate as it provides useful 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 concise yet comprehensive: first sentence states purpose, second lists domains, third explains return value, fourth gives usage guideline. Every sentence adds value, and the most important info is front-loaded. No wasted words.

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

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

Given the tool's complexity (meta-discovery across many domains), the description covers purpose, usage, return format, and domain scope. No output schema is needed because the description already explains the return. All relevant aspects are addressed for a discovery tool.

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

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

Schema coverage is 100%, and all parameters have descriptions. The description explains the query parameter as 'natural language description' and mentions acceptable aliases, which adds marginal value. The examples in the schema provide concrete usage. Baseline 3 raised to 4 due to the examples and alias clarification.

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 'Find tools by describing the data or task.' It specifies many domains (SEC filings, FDA, etc.) and explains that it returns top-N relevant tools with full schemas. This distinctly differentiates it from sibling tools, which are domain-specific.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use. However, it does not explicitly state when not to use or mention alternatives, though the sibling list implies this is the discovery entry point.

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, openWorldHint, idempotentHint, destructiveHint), the description discloses that the tool fans out across multiple sources in parallel, returns specific fields (cik, recent_filings, fundamentals, etc.), and notes that the patents feature soft-fails until reactivated (May 2025). 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 dense and front-loaded with example queries, but somewhat long. Every sentence adds value, but the details of return fields could be slightly more organized. Still clear and well-structured.

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

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

Given the tool's complexity (multiple data sources, soft-failures, no output schema), the description thoroughly explains what is returned (cik, filings with URIs, fundamentals sorted, patents status, news fallback, LEI). It covers limitations and behavior, making it complete for selection and invocation.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context that the value parameter expects a ticker or zero-padded CIK (e.g., '0000320193') and that names are not supported, reinforcing the schema. This adds nuance but does not drastically improve 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 it returns a full cross-source profile of a US public company with example queries like 'Tell me about X' and lists specific data sources (SEC, XBRL, USPTO, news, GLEIF). It distinguishes from sibling tools by explicitly recommending it over chaining individual lookups and mentioning resolve_entity for name resolution.

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' and advises using resolve_entity first if only a name is available. Provides clear context for when to use and when not to use (names not supported).

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, which the description aligns with by stating it deletes a memory. However, the description does not add new behavioral details beyond what the 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 two sentences, front-loading the action and following with usage guidance. No unnecessary words or repetitions.

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

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

The description covers purpose, usage, and parameter context. Given the simplicity (one required param, no output schema), it is sufficiently complete. It does not explain what happens if the key is missing, but idempotentHint suggests it's safe.

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

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

Schema coverage is 100% with the parameter 'key' described as 'Memory key to delete.' The tool description adds only 'by key,' which does not enhance meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' which is a specific verb+resource combination. It also distinguishes the tool from siblings by referencing 'remember' and 'recall' as paired operations.

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

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

Explicit usage guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This gives clear criteria for when to invoke the tool.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detail: fetches page, extracts title/description/key links, emits standard markdown format. 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 front-loaded with purpose and well-structured, but slightly longer than necessary. Every sentence adds value, so minor deduction for wordiness.

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 simple tool (2 params, no output schema), the description covers input, output format, and use cases. It doesn't mention error handling or rate limits, but annotations handle safety. Adequate for its 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 clear descriptions for both parameters. The description only repeats 'for any URL' and does not add new semantics beyond the 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?

The description clearly states the verb ('Generate') and resource ('llms.txt file for any URL'), and distinguishes itself by listing specific use cases. No sibling tool has a similar purpose, so differentiation is not needed.

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

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

The description provides explicit context ('so AI crawlers can index the site cleanly') and lists three concrete use cases. It lacks explicit when-not-to-use or alternatives, but the unique function makes this less critical.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat these. The description adds value by stating what fields are returned ('full detail: name, email, phone, tags, source, custom fields, and timestamps'), which helps the agent understand the response. No contradiction with annotations.

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

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

The description is a single concise sentence plus a clarifying clause, with no wasted words. It is front-loaded with the verb and resource, and provides immediate understanding of what the tool does.

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 (fetch a single contact by ID), the description covers the return fields adequately. There is no output schema, so the description's mention of return fields adds necessary context. Some minor gaps like error handling or rate limits exist, but they are not critical for a read-only idempotent tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema; it mentions 'contact ID' but does not explain format, length, or any constraints. The schema already describes both parameters adequately.

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

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

The description clearly states the verb 'Fetch' and the resource 'single CRM contact', specifies it's by contact ID, and lists what full detail includes (name, email, phone, tags, source, custom fields, timestamps). This is specific and distinguishes it from sibling tools like leadconnector_list_contacts that might list multiple contacts.

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 this tool is for fetching a single contact by ID and returning full detail, but it does not explicitly say when to use it versus alternatives (e.g., when you need a single contact vs. a list). No prerequisites or exclusions are mentioned, but the context is clear enough for the agent to infer basic usage.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the specific return envelope structure (campaigns array with IDs, names, status). This adds useful 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 concise, consisting of two sentences. The first sentence states the core function, and the second adds return format and a practical use case. Every sentence is valuable with no redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema, clear annotations), the description is sufficiently complete. It explains what the tool does, the return format, and a typical use case, leaving no gaps for the agent to guess.

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

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

The input schema has 100% coverage for the single required parameter (_apiKey), with a clear description in the schema itself. The tool description does not add any additional meaning or details about the parameter. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists marketing/automation campaigns in the account. It uses a specific verb ('list') and resource ('campaigns'), and the return format is described. It distinguishes from sibling tools like leadconnector_list_contacts and leadconnector_list_opportunities.

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

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

The description provides a use case ('useful for finding a campaign to attribute or enroll contacts'), which gives context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Adds value beyond annotations by describing the return envelope structure and fields. Annotations already indicate read-only and idempotent, so description complements them well.

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

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

Two sentences, front-loaded with purpose, no fluff. 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?

Describes return format and fields, but missing pagination details (e.g., cursor or offset) which would be helpful for a list operation.

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

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

Schema already provides 100% coverage with clear parameter descriptions. Tool description adds minimal extra beyond summarizing query matching behavior.

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 'search or list CRM contacts' with specific verb and resource. Distinguishes from sibling 'leadconnector_get_contact' which is for a single contact.

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 contacts by free-text query but does not explicitly contrast with alternatives like 'get_contact' nor provide 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds value by stating the return fields (monetary value, stage, status, contact) beyond the annotations' safety profile.

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

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

The description is two sentences, front-loading the core purpose and prerequisites. No extraneous information or repetition. 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?

For a list tool with 3 parameters and no output schema, the description covers the key return fields (monetary value, stage, status, contact) and the required prerequisite. It could optionally mention pagination or default limit, but given the limit parameter's schema coverage, it is complete enough.

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

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

Schema description coverage is 100%, with all three parameters documented. The description adds little beyond the schema: it notes pipelineId as required and mentions pipelineId's dependency on leadconnector_list_pipelines, but this is already implied by the schema's description field. Baseline 3 is appropriate.

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

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

The description clearly states 'List opportunities (pipeline deals) for a given pipeline,' specifying the verb (list), resource (opportunities/deals), and scope (per pipeline). It distinguishes from siblings like leadconnector_list_pipelines and leadconnector_list_contacts by focusing on opportunities within a pipeline.

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

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

The description explicitly states the prerequisite ('Requires a pipelineId') and directs how to obtain it via sibling tool leadconnector_list_pipelines. It does not mention when not to use this tool or provide alternatives, but for a list tool this is sufficient guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds detail on the return format ({pipelines:[...]}), which is helpful beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with the core purpose, with no redundant 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 (1 parameter, no output schema, strong annotations), the description fully covers what the agent needs: what it does, what it returns, and how to use the result with another 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?

Only one parameter (_apiKey) with full schema description coverage (100%). The description does not add extra semantics beyond the schema. Baseline score of 3 is appropriate.

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

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

The description states 'List all sales pipelines and their stages' with a specific verb and resource. It also distinguishes from the sibling tool leadconnector_list_opportunities by noting to use the returned pipeline ID with that tool.

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

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

The description provides clear guidance: use this tool to get pipeline IDs for use with leadconnector_list_opportunities. It does not explicitly list when not to use it, but the context is sufficient.

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

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

Annotations already declare the tool safe (read-only, idempotent, non-destructive). Description adds value by detailing return fields and scoping to caller's subscriptions, but lacks mention of potential pagination or rate limits, which are absent due to simplicity.

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 return info, then usage guidance. No superfluous content.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, return shape, and usage context. No gaps.

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

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

The single parameter include_inactive is fully documented in the schema. The description adds no additional meaning beyond what the schema provides, meeting but not exceeding expectations with 100% 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 tool lists the caller's active subscriptions and specifies returned fields. However, it does not explicitly differentiate from sibling tools like subscribe or unsubscribe, though the purpose is distinct.

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

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

Explicitly advises when to use the tool: to review monitored items before adding more or to find an ID to cancel. This is clear and actionable.

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

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

While annotations only set hints to false, the description discloses important behavioral details: filing without an account returns a claim_token, the token can be used later to read resolution status, rate-limiting to 5 per identifier per day, free usage, and that feedback directly affects roadmap. No contradiction with annotations.

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

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

Although the description is relatively long, every sentence earns its place: it covers purpose, scope, exclusions, claim_token usage, rate limits, and roadmap impact. The content is dense and well-structured, with no filler or redundancy.

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

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

Given the tool's complexity (4 parameters, nested context object, no output schema), the description fully covers all necessary aspects: what to report, how to report, what happens with/without an account, rate limits, and how to check resolution. It is complete for the agent to use effectively.

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

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

The schema already provides 100% parameter descriptions, so the baseline is 3. The description adds extra value by explaining the claim_token workflow ("pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})") and instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting prompts. This goes 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: "Tell the Pipeworx team something is broken, missing, or needs to exist." It specifies the verb (tell/feedback), the resource (Pipeworx team), and distinguishes from sibling tools by focusing exclusively on feedback about Pipeworx tools, not general questions 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 gives explicit when-to-use scenarios (bug, feature/data_gap, praise) and a clear when-not-to-use: "ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead." This is model guidance with exclusions and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: data source (CF analytics-engine), no PII, cached 5min-1h, and self-aggregating signal. 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 concise sentences plus a bullet list of use cases. Front-loaded with the core function, no wasted words. Every sentence adds value.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, parameters, use cases, caching, and data provenance. No gaps.

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

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

Schema coverage is 100% with enum descriptions. The description adds contextual guidance on window choice (short vs long windows surface different trends), which adds meaning beyond the enum 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 explicitly states the tool returns top tools, top packs, and total call volume over a specified window, with specific use cases. It clearly distinguishes from sibling tools like discover_tools.

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

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

Three explicit use cases are provided, and the parameter description gives guidance on window choice. However, it does not explicitly state when not to use this tool 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 indicate safe/read-only. Description adds extensive behavioral details: no-arg trending scan, event/topic behavior, semantic anchor similarity, partition placeholder filtering, fill check against live depth, and response structure. 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?

Long but well-structured with clear sections. Each sentence adds value given tool complexity. Could be slightly shorter but justified by depth of information.

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

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

Despite no output schema, description fully explains response structure including arrays and objects. Covers error conditions (low similarity, placeholder filtering) and trade decisions. References sibling tool for custom sizing. Complete for an agent to 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%, but description adds significant meaning: explains event parameter expects slug or URL for single-event mode, topic expects seed question for cross-event mode, and provides examples. Also explains how each parameter changes tool behavior.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes two modes (event/topic) and explains each, differentiating from siblings like polymarket_edges.

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

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

Explicitly says when to use no args (trending scan), event (specific market), or topic (cross-event). Recommends event for specific markets, warns about cross-event catching single-event misses. Provides conditions for trade signals and references polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, conveying safe, read-only, and non-destructive behavior. The description adds useful context: caching (1h at KV level), diagnostic info (_diagnostics), edge calculations net of slippage, Kelly cap at 0.25, and a 24h-move warning. 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 highly informative but very dense and lacks clear structure (e.g., bullet points or sections). It front-loads the purpose, but the technical details on model families and diagnostics make it lengthy. Could be more scannable for an AI agent.

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

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

Given 9 parameters, no output schema, and complexity, the description is complete. It explains the output structure (by_segment with segments, fed_candidates, _diagnostics), what fields each opportunity carries (edge_pp_net, kelly_fraction, market info, 24h-move warning), and the tradeable-edge knobs. Caching is noted. This provides sufficient context for an agent to understand and use 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?

Input schema covers all 9 parameters with descriptions (100% coverage), so baseline is 3. The description adds significant value by explaining how parameters like min_kelly, min_partition_leg_kelly, and slppage_pp work in context (e.g., 'skips opportunities that are too small to bet sensibly', 'tradeable-edge filter'). 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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs ('scan', 'return') and identifies the resource (Polymarket markets). The detail on three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides context for when to use (daily discovery) and describes knobs for filtering (min_liquidity, max_spray_pp). However, it lacks explicit 'when not to use' or direct comparisons to alternative tools among siblings.

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

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

Annotations already declare idempotent and read-only behavior. The description adds rich behavioral detail: response structure (tracked, expired, snapshot_dates), meaning of fields (trend categories, decay computation), and edge cases (negative values for SELL YES, gaps in snapshots, limits on history depth). This goes well beyond the annotations.

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

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

The description is front-loaded with the core purpose and uses clear sections (Args, RESPONSE, LIMITS). It is efficient but slightly verbose in the RESPONSE section, where it lists fields in a paragraph instead of a more structured format. Still, nearly every sentence adds value.

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

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

Given no output schema, the description thoroughly explains the return structure and edge cases. It covers data sources, decay computation, and limitations. Could be enhanced with a concrete example or more direct guidance on interpreting results, but overall it is quite complete for a specialized telemetry 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 detailed descriptions for both parameters. The tool description essentially repeats this information (days, window, defaults, constraints) without adding new meaning. Per guidelines, baseline is 3 when schema coverage is high.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It explicitly answers the question it addresses and distinguishes itself from the sibling tool `polymarket_edges` by focusing on time-series analysis rather than a current snapshot.

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 (to differentiate new vs. old edges) and provides context on limits (60-day TTL, snapshot gaps). It does not explicitly mention alternatives, but the sibling list is available and the description's framing makes its unique value clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description's primary job is to add behavioral context beyond these. It does so by detailing the check process (walks the ladder, returns metrics like top_of_book, vwap_fill_price, slippage_pp, verdicts) and explicitly warns about thin books and directional risk. This adds significant value beyond the safety profile provided 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 a single paragraph with clear section breaks (e.g., 'SINGLE-MARKET:', 'BASKET:') and uses bold for emphasis. It covers all necessary details without redundancy, though it is somewhat lengthy due to the tool's complexity. Every sentence adds value, and the structure is logical.

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 the return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp for single-market; theoretical_sum, realizable_sum, capture_ratio, thin_legs for basket). It also addresses edge cases like forced_directional_risk, making the tool highly understandable for correct agent 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 meaning beyond the schema: it clarifies the dual mode (single-market vs basket), explains default side selection for basket, and elaborates on the interpretation of size_usd for both modes (spend vs target proceeds vs settlement notional) and the clamp range. This enriches parameter understanding.

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

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

The description specifies the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by advising use before acting on their signals or trades above ~$500.

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

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

Provides explicit when-to-use guidance: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. Warns about the risks of partial basket fills converting arb into unhedged directional positions, which clearly indicates when not to use or to proceed with caution.

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

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

The description goes far beyond annotations, detailing safety fields like compatibility_warning, temporal_alignment, and skipped_cross_type/ subtype. It explains when spreads are real signals versus meaningless, and discloses the tool's behavior in edge cases (e.g., non-equivalent bet shapes). No contradictions with annotations (readOnlyHint, idempotentHint, destructiveHint).

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 bold headings for modes and safety fields, and front-loads the core purpose. It is detailed but not excessively verbose. Each sentence adds meaningful information, though some redundancy could be trimmed (e.g., repeated emphasis on compatibility warnings).

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 the response structure (leg prices, matched spread, top_spreads_pp) and all safety fields. It covers temporal alignment, skipped cross types, and compatibility warning conditions, providing complete context for interpreting results.

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

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

The input schema already covers all parameters with descriptions (100% coverage). The description adds value by explaining the mode switching (topic vs explicit), listing valid topic values, and describing how explicit tickers override the topic-mapped side. This enhances understanding 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 spreads between Kalshi and Polymarket. It explains two modes (topic shortcuts and explicit tickers) and distinguishes the tool by being cross-venue. The purpose is 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 provides clear context for when to use the tool (e.g., comparing prices across venues) and includes strong warnings about pre-mapped topics often returning compatibility warnings. However, it does not explicitly mention alternative tools for single-venue analysis or other arbitrage tools from the sibling list.

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 and destructiveHint=false. The description adds scoping details (identifier-based) and explains the listing behavior when key is omitted, providing beyond-annotation context.

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

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

The description is three sentences, front-loaded with the main function. Every sentence adds value without redundancy. It is concise and well-structured.

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

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

Given no output schema, the description covers retrieval and listing behavior but does not explicitly mention the return format (e.g., value or list of keys). It is nearly complete but could be slightly more explicit.

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 a parameter description. The description adds significant meaning by clarifying the dual functionality (retrieve vs. list) and scoping, which is not in the schema itself.

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

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

The description clearly states the tool retrieves values saved via remember or lists all keys when omitted. It specifies the verb (Retrieve/list) and resource (saved values), differentiating it from siblings like remember and forget.

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

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

The description explains when to use: to look up previously stored context without re-deriving. It mentions pairing with remember/forget but doesn't explicitly state when not to use. The context is clear enough for correct selection.

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

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

Beyond annotations, it describes the return shape (source, citation_uri, raw payload) and the mark_read behavior, adding significant context for the agent.

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

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

Four sentences, front-loaded with purpose, each sentence adds value without redundancy. Well-structured for quick parsing.

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

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

The description covers all parameters, explains the return shape, and gives usage context. Without an output schema, it could be more explicit about all possible fields, but it is sufficient.

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

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

Schema coverage is 100%, and the description adds examples (e.g., 'sec_8k' for type) and clarifies mark_read semantics, providing extra value beyond the schema.

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

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

The description uses a specific verb ('pull') and resource ('fired events from your subscription feed'), clearly distinguishing it from sibling tools like subscribe or list_subscriptions.

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

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

It explicitly mentions filtering by type and since, the mark_read effect, and gives polling advice with an alternative REST endpoint, telling the agent when and how to use the tool.

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

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

Beyond annotations (readOnly, idempotent), description reveals parallel execution, fallback logic (GDELT preferred, GNews on rate limits/5xx), PatentsView soft-fail post-May 2025, and output structure. No contradiction with annotations.

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

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

Description is roughly 5 sentences, front-loaded with examples, and every sentence serves a purpose (behavior, parameters, sibling reference). No filler or redundancy.

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

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

Despite no output schema, description adequately explains returns (structured changes[], total_changes, citation URIs). For a multi-source tool with fallback, this provides sufficient guidance 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 already covers parameters with descriptions (100% coverage). Description adds value by giving concrete examples for since, value (ticker/CIK), and suggesting typical monitoring windows. It does not rely on 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 it provides a change feed for a company over a time window, listing specific sources (SEC, GDELT/GNews, USPTO). It contrasts with sibling entity_profile (static profile vs. dynamic changes), making its purpose distinct.

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

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

The description includes example queries and suggests typical since values ("30d" or "1m"). It also directs users to entity_profile for static profiles. Although it doesn't exhaustively list when not to use, the sibling distinction is sufficient.

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

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

Annotations show idempotentHint=true, but no other hints. Description adds critical behavioral details: memory is key-value scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

Three sentences, front-loaded with main purpose. Efficient but includes some redundancy (e.g., 'so you don't have to look it up again' slightly wordy). Overall well-structured.

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

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

For a simple write tool with no output schema, the description sufficiently covers usage context, storage behavior, and tool linkages. Complete enough for effective 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 description coverage is 100% and both parameters are well-described in the schema. The description adds minimal extra value beyond schema (e.g., naming examples) but is not needed for understanding.

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

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

The description clearly states 'Save data the agent will need to reuse later' with specific verb (save) and resource (data stored as key-value pairs). It distinguishes from siblings 'recall' and 'forget' by focusing on the writing action.

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

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

Explicitly describes when to use: 'when you discover something worth carrying forward' and mentions complementary tools 'recall' and 'forget'. However, does not explicitly state when not to use or contrast with other storage mechanisms.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral context beyond this: identifiers are labelled with source, unresolved identifiers are explicitly listed under 'unresolved', LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. This gives the agent confidence in failure modes and output completeness.

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

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

The description is long but every sentence carries essential information. It is well-structured: example queries first, then core purpose, then detailed breakdown of supported types, then enrichment behavior. No redundant phrases; the density is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining returns. It explains what identifiers are returned for each type, how sources are labelled, that unresolved IDs are listed, and how failures are handled. For a tool with two complex entity types and cascading lookups, this description is substantially complete.

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

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

Schema coverage is 100%, so baseline is 3. But the description significantly enriches both parameters: type='company' now implies a cross-source identity spine (CIK, ticker, LEI, FIGI) with ownership data, while type='drug' returns RxCUI, ingredient, brand, and a citation. It also gives concrete input examples (e.g., 'AAPL', '0000320193', 'ozempic') and explains failure behavior, which is far 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 begins with concrete example queries and explicitly states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from siblings by focusing on identifier lookup (ticker, CIK, LEI, RxCUI) and even notes that it replaces multiple manual lookups.

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

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

It provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies supported entity types and input formats, and implies when not to use (e.g., when you already have an ID). The mention of graceful degradation and replacing manual lookups further helps the agent decide.

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

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

Adds significant behavioral context beyond annotations: probes each entity with ai_visibility_check, ranks results, returns score/confidence/signal density. Mentions API key requirement for Anthropic model. 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?

Four sentences, efficient and well-structured. Front-loaded with main action, then details. 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 no output schema, description adequately explains return format. Covers probing mechanism, ranking, and API key usage. Sufficient for agent to understand tool's capabilities and outputs.

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 meaning: explains 'entities' first entry treated as subject, 'context' is shared across probes, and 'models' default behavior. Enriches understanding 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 it compares AI visibility across multiple entities, ranks them by score, and surfaces most/least recognized. It distinguishes from sibling 'ai_visibility_check' by being a side-by-side comparison 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 says it's useful for competitive AI-marketing audits and gives an example question. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

Beyond the annotations (readOnlyHint, etc.), the description adds critical behavioral details: composite call fan-out, partial failure handling, bundlephobia timeout (5-30s), and return structure, all without contradicting annotations.

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

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

The description is front-loaded with purpose and usage, then progressively detailed with technical notes. It is slightly verbose but each sentence adds value, earning a high but not perfect score.

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

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

Despite lacking an output schema, the description enumerates all return fields, explains partial failure, and sets expectations for timing and ecosystem scope, making it fully actionable for the agent.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description does not add significant new meaning beyond confirming scoped package acceptance, which is already in the schema.

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

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

The description uses a specific verb ('check') and resource ('npm package') and clearly states the composite nature, distinguishing it from sibling tools by noting that other ecosystems fall under direct deps.dev calls.

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 provides when-to-use examples ('is X safe / popular / small') and when-not-to-use (non-NPM ecosystems should use deps.dev:version directly), offering clear guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses technical behavior: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and returns character offsets. 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?

Concise at about 6 sentences, front-loaded with the main action. Each sentence adds distinct value: defines tool, use case, sibling pairing, technical details. No fluff or redundancy.

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

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

For a tool with 3 params, no output schema, but with annotations covering safety, the description fully explains: what you get (top-N passages with offsets and scores), how it works (embeddings, windows), and limitations (200K char cap). It is complete for an agent to understand invocation and expected outcome.

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 (e.g., text max chars, query examples, limit range and default). The description adds context that text comes from a fetched record and that output includes offsets and scores, but this is marginal additional value beyond the schema. Baseline 3 plus extra context warrants a 4.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning passages with offsets and scores. It uses specific verbs ('search inside', 'pass the text', 'get back') and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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'. Provides a clear alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives both usage context and alternative.

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

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

Annotations indicate idempotentHint=true and readOnlyHint=false. The description adds that it returns a new subscription ID, explains delivery channel limits (10/day SMS cap, webhook auto-disable), and mentions feed persistence. No contradictions with annotations.

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

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

The description is a single paragraph but well-organized with logical flow. It is information-dense yet readable. Minor improvement could be using bullet lists for the three delivery channels, but it remains concise and front-loaded.

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

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

Given the tool's complexity (5 subscription types, required params, optional nested delivery object), the description covers authentication, type-specific filters, delivery options with limitations, and the return value ('Returns the new subscription id'). No output schema exists, so description handles it fully.

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

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

Schema coverage is 100% but the description enriches every parameter with concrete examples and constraints (e.g., 'sec_8k: items:["5.02"] = officer change'). It clarifies the type-specific params and delivery subfields beyond the schema definitions.

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

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

The description uses specific verbs ('Create a proactive monitoring subscription') and clearly identifies the resource ('live-data event stream'). It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation of subscriptions.

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

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

The description states the requirement for a Pipeworx OAuth account and gives detailed examples per subscription type. It lacks explicit when-to-use vs alternatives but the context makes it clear this is for setting up monitoring, not for retrieving existing alerts.

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 detailing that the tool returns example questions from a live catalog, with category bucketing and tool+argument shapes, and explains behavior with/without topic argument. 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?

The description is dense but well-structured, front-loading purpose and usage indications. Every clause contributes value, though it is longer than minimal. Could be slightly more concise 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 tool's role as an onboarding entry point with no output schema, the description is remarkably complete. It covers when to use, what it returns (category-bucketed questions with tool+argument shapes), parameter options, and relationship to sibling tools. 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?

Input schema has 100% coverage with a single optional string parameter 'topic' and its description. The description adds meaning by saying omitting topic gives a cross-category spread and listing example values, enhancing 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's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It differentiates from siblings by positioning itself as a first-use tool and listing sibling meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly says to use this tool first when the agent does not know what Pipeworx can do or to learn how to call meta-tools. It also describes when to omit or include the topic parameter, providing clear context for alternatives.

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

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

Adds information beyond annotations: ownership enforcement, deactivation vs deletion, and relation to recent_alerts. Annotations already indicate idempotent and non-destructive, so description complements well.

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

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

Two sentences, front-loaded with purpose, no unnecessary words.

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

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

Complete for a simple tool: explains behavior (deactivation), ownership, and connection to recent_alerts. No output schema needed as return value is implied.

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

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

Schema covers 100% of the single parameter with description. The description does not add further detail about the parameter beyond what the schema provides, meeting baseline.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id', distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement and that the row is deactivated not deleted, providing context for when to use and what happens after. Lacks mention of alternatives but is 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=true, openWorldHint=true, and idempotentHint=true, but the description adds crucial behavioral detail beyond this: the meaning of each verdict (especially could_not_verify vs. unsupported), the presence of verification_error{stage,detail} for failures, the routing logic, and the explicit warning that could_not_verify is not evidence for/against the claim. This is rich, non-contradictory context that greatly aids correct interpretation.

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

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

The description is dense but every sentence earns its place: usage triggers, routing behavior, return values, and critical error semantics are all covered. It is front-loaded with examples and immediately tells the agent when to use the tool. The structure flows logically from what it does, to how it works, to what it returns and what to be careful about.

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

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

For a tool with no output schema, the description comprehensively explains return values (verdict list, actual value with citation, reasoning, verification_error). It also covers the two execution paths, the distinction between could_not_verify and unsupported, and even mentions the efficiency benefit over sequential calls. Combined with full parameter schema coverage and supportive annotations, this is complete for safe and correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance for tolerance_pct, explaining how it overrides the default implied by claim wording (capped at 5) and recommending 1–2 for hallucination detection. It also clarifies that 'claim' is a natural-language factual statement, reinforcing the schema's examples. This goes beyond a simple restatement of parameter 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 identifies the tool as natural-language claim verification against authoritative sources, with concrete query examples ('fact check', 'verify the claim that…'). It distinguishes itself from siblings by explaining the two routing paths (SEC EDGAR/XBRL for financial claims, grounded pipeline for everything else) and its role as a replacement for 4–6 sequential calls.

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 guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains when the financial fast path applies versus the general grounded pipeline. However, it does not explicitly name alternative tools or state when not to use it (e.g., when deep research is needed), leaving some ambiguity in tool selection.

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