N8n

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

Annotations already indicate it is read-only, open-world, idempotent, and non-destructive. The description adds important context: the default model is free, but probing Anthropic requires a BYO API key with external billing. It also outlines the return format, adding value beyond annotations.

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

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

The description is extremely concise: two sentences covering purpose, output, default model, API key, and use cases. Every sentence adds value with no redundancy.

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

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

Given the tool has 4 parameters (all well-described), no output schema, and rich annotations, the description covers the main aspects: what it does, how to use API key, return format, and use cases. It could mention error handling or interpretation of scores, but overall it is sufficiently 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 description coverage is 100%, and all parameters have adequate descriptions in the schema. The description adds some extra context (default model, API key usage) but not essential for understanding parameter 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 clearly states the verb 'probe' and the resource 'LLMs', with specific outputs (visibility score 0-100 per model). It distinguishes from siblings like 'ask_pipeworx' and 'deep_research' by focusing on AI visibility 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 clear context for use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains the default model and API key requirement for Anthropic, but does not explicitly mention when not to use 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 cover idempotency, read-only, and non-destructive nature. The description adds that it returns structured answers with citation URIs. It doesn't discuss failure modes, rate limits, or ambiguity handling, but provides adequate 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 front-loaded with the critical 'PREFER OVER WEB SEARCH' directive. It includes many examples, which add value but lengthen it. Overall well-structured, though could be slightly more concise.

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

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

Given the tool's complexity (meta-tool routing to thousands), the description explains the citation mechanism but lacks return format details and error handling. With no output schema, more information about the response structure would be helpful.

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

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

Schema coverage is 100%, so baseline 3. The description adds examples of valid questions and states it accepts natural language, but doesn't detail parameter constraints 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 answers factual questions using authoritative structured data, routing to 3,767 tools. It explicitly contrasts with web search and provides numerous examples, making the purpose undeniable and distinguishing it from siblings like 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?

The description gives strong usage guidance: 'PREFER OVER WEB SEARCH' and lists many query types. It tells the agent when to use this tool even if web search could answer. However, it doesn't explicitly mention when not to use it or compare to direct siblings like deep_research.

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

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

Description explains internal behavior (picks tool, extracts only from result, returns explicit refusals with reasons). Annotations (readOnlyHint, destructiveHint false, idempotentHint) are consistent and description adds context about extra LLM call cost.

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

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

Front-loaded with purpose, uses clear structure with key details, no wasted sentences. 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 high complexity (3,767 tools, 891 sources), presence of annotations, and no output schema, description provides complete output format and refusal reasons, making it fully informative.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. Description adds no additional parameter semantics beyond what schema provides, so baseline 3 is appropriate.

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

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

Description explicitly states it is a 'hallucination-resistant answer mode' for high-stakes reads, explains the routing and extraction process, and distinguishes from ask_pipeworx by noting extra LLM call and use case.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups', providing clear when-to-use and when-not-to-use with sibling 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description complements with extensive behavioral details: fan-out logic, classifiers, response shapes, safety checks (low-confidence short-circuit, closed markets, wide spreads), resolver contract, parent event extractor, and cancellation rule risk. 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 long but front-loaded with core purpose and usage. It contains detailed technical information that is highly relevant. While every sentence adds value, the dense structure could be slightly more organized for ease of reading.

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, high schema coverage, and lack of output schema, the description covers all aspects: input, output shapes, edge cases (closed markets, low confidence), safety, and resolution risks. It is comprehensive enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining input formats, depth options (quick vs thorough), and include_raw rationale (summary vs full payloads). 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 it researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The purpose is distinct from siblings like ask_pipeworx or polymarket_edges, though not explicitly compared.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides examples of fan-out. However, it doesn't explicitly state when not to use or compare to specific 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 concrete behavioral details: what data is pulled per type (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), fiscal year handling, sorting by primary metric, and output format (paired data + citation URIs). No contradiction with annotations.

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

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

The description is front-loaded with example queries, immediately conveying purpose. Every sentence adds value: usage preference, data sources, handling of fiscal years, sorting, and output. Though longer than average, it is efficient for the complexity (two entity types) and contains 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 the complexity (two entity types, multiple data sources, sorting, citations), the description covers all necessary details for an agent to select and invoke the tool correctly. It explains when to use, what data is returned, and how it compares to siblings (replacing sequential lookups). No output schema, but it sufficiently describes return format.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches meaning by linking types to specific data sources ('company' => financials, 'drug' => adverse events) and provides examples for values (tickers vs drug names). It adds constraints (min 2, max 5) and implies format requirements.

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 ('compare', 'side-by-side comparison') and clearly identifies the resource (companies or drugs) and actions (pulling financial data or adverse event counts). It distinguishes itself from sequential lookups by claiming to replace 8-15 calls, making its purpose unmistakable.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example queries and clarifies when to use ('compare X and Y', 'rank these companies'). Though it does not explicitly state when not to use, the positive guidance is strong and practically covers usage scenarios.

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. Description adds significant behavioral context: returns verbatim evidence with confidence, source, fetched_at, stable citations, and explicit gaps[]. States 'never invented'. 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?

Description is concise yet comprehensive. First sentence captures core, then details decomposition and output, then usage guidelines, then requirements, then timing. Every sentence is necessary and well-ordered.

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 describes return content: findings packet with verbatim evidence, confidence, source, fetched_at, citations, and gaps. Also covers tool's pre-verification behavior and time estimate (15-60s). Complete for agent decision-making.

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

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

Schema coverage is 100% with descriptions. Description enriches by specifying depth values: quick=3, standard=5, thorough=8. Also clarifies question parameter accepts broad/multi-part queries. Adds value beyond schema.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research in ONE call.' It explains decomposition, parallel routing to many tools, and structured output. Distinguishes itself from sibling ask_pipeworx by noting single vs. multi-source.

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

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

Explicitly says 'Use for broad or multi-part questions' and contrasts with ask_pipeworx for single lookups. Also mentions account requirements and paid plan for thorough depth. Provides clear when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat these. The description adds value by explaining that results are 'ready to call directly, no second schema lookup needed' and mentions the default limit of 20 and max of 50. This goes beyond what annotations provide.

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

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

The description is a single paragraph that front-loads the main purpose and then lists many use cases and details. While informative, it could be slightly more concise. However, every sentence adds value, and there is 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 parameter count (6) and no output schema, the description is complete. It explains that the output includes tool names, descriptions, and full input schemas with curated examples, which is sufficient for an agent to understand what will be returned. No additional information is needed for this tool's role.

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 by explaining that the 'query' parameter accepts multiple aliases (task, q, description, search). It also provides natural language examples. This clarifies usage 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 clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific use cases like SEC filings, financials, and FDA drugs, and explains that it returns top-N relevant tools with full schemas. This distinguishes it from sibling tools, which are more specific or operational.

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

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

The description explicitly advises '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 it, though it does not explicitly mention when not to use it or list alternatives. The guidance is sufficient for an AI agent.

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

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

Discloses that patents API will sunset in May 2025 and soft-fails until reactivated. Annotations already indicate read-only, idempotent, and non-destructive behavior; description adds context about parallel fan-out across sources and specific data handling. 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?

Description is front-loaded with example user queries, making intent immediately clear. It is thorough but not excessively verbose; every sentence adds necessary detail. Could be slightly tighter but still effective.

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

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

Despite no output schema, description fully enumerates return fields (cik, filings, fundamentals, patents, news, LEI) with details on sorting and formatting. Covers limitations (patents sunset) and fallbacks (GDELT to GNews). Provides complete mental model of tool's capabilities.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that type must be 'company' and value must be ticker or CIK (not names), reinforcing the need to use resolve_entity for names. This extra guidance justifies 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?

Description clearly states it provides a full cross-source profile of a US public company, listing specific data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields. Distinguishes from sibling resolve_entity by noting that names are not supported here.

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

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

Explicitly tells when to use (user asks for holistic view like 'tell me about X') and when not (if only have a name, use resolve_entity first). States to always prefer this tool over chaining single-pack lookups. Provides clear alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description confirms destructive nature but adds no extra behavioral context beyond usage scenarios.

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: first states action, second provides usage guidance. No redundant words.

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

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

Given the tool's simplicity (1 param, no output schema), the description fully covers purpose, usage, and parameter meaning.

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 description for the single parameter 'key'. Description does not add additional meaning beyond the schema.

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

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

Uses specific verb 'Delete' and resource 'memory by key', clearly distinguishing it from siblings like 'remember' (store) and 'recall' (retrieve).

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: 'stale context, task done, clear sensitive data', and mentions pairing with 'remember and recall' for context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining that the tool fetches the page, extracts title/description/key links, and outputs a single text blob ready to drop at site-root/llms.txt. It does not contradict annotations and provides useful behavioral context beyond what annotations convey.

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

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

The description is concise and well-structured. It front-loads the main purpose in the first sentence, then explains the process and output, and ends with clear use cases. Every sentence adds value without redundancy, making it efficient for an AI agent to understand quickly.

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

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

Given the tool has 2 parameters with full schema coverage and no output schema, the description covers key aspects: what it does, how it works (fetch, extract, emit), and output format. It lacks mention of potential limitations like robots.txt handling or error cases, but overall it is fairly complete for a straightforward 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 baseline is 3. The description does not add new meaning beyond the schema's parameter descriptions. It mentions 'for any URL' and the output format but does not elaborate on how max_links affects output or provide examples. The schema already defines 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 tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It explicitly mentions AI crawlers (ChatGPT, Claude, Perplexity) and describes the output format, effectively distinguishing it from sibling tools like 'ai_visibility_check' which focus on visibility analysis rather than file generation.

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

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

The description lists concrete use cases: getting a client's site indexed, drafting for your own project, or auditing a competitor. It does not explicitly state when not to use or name alternatives, but the use cases are clear and practical. Could be improved by contrasting with related sibling tools, but current guidance 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying return fields and the optional parameter include_inactive, but does not contradict or significantly extend beyond the annotations.

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

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

Two sentences, no wasted words. First sentence states purpose and return fields; second sentence provides usage guidance. Extremely efficient.

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

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

For a simple tool with one optional parameter and no output schema, the description covers what the tool returns and when to use it. Annotations address safety. The description is fully adequate for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with a clear description for the only parameter (include_inactive). The description mentions 'active subscriptions' which aligns with the default behavior, but adds no new semantic meaning beyond what the schema provides. Baseline 3 applies.

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

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

The description clearly states the verb 'list' and resource 'subscriptions', specifies it returns the caller's active subscriptions, and lists the returned fields. This distinguishes it from sibling tools like 'subscribe' and 'unsubscribe' which perform different actions.

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

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

The description explicitly tells when to use this tool: 'review what you're monitoring before adding more or to find an id to cancel'. This provides good context, though it does not mention when not to use it or alternatives beyond the implied different purposes of 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 readOnlyHint and destructiveHint as false, signaling a safe read operation. The description adds value by detailing the return content (name, active state, node list, etc.) and the authentication header, which goes beyond annotations.

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

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

The description is two sentences, directly states the purpose, lists key returned fields, and provides necessary context for ID and authentication. No extraneous information, perfectly front-loaded.

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

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

For a simple read operation with three required parameters and no output schema, the description covers the essential information: what the tool returns, how to get the ID, and what credentials are needed. It is sufficient for an agent to use correctly, though it could explicitly note the read-only nature (already covered by annotation).

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaningful context: it clarifies that _apiKey is an n8n API key sent as the X-N8N-API-KEY header, suggests getting workflow_id from n8n_list_workflows, and provides an example for instance_url. This enhances 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 uses a specific verb ('Get') and resource ('workflow detail'), lists the returned fields (name, active state, node list, tags, timestamps), and clearly distinguishes from sibling tools by indicating it retrieves a single workflow by ID, while siblings like n8n_list_workflows list workflows.

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

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

The description explicitly instructs to obtain the workflow ID from n8n_list_workflows and mentions the required authentication (instance_url and _apiKey). It lacks explicit 'when not to use' or alternative tool guidance, but the context is clear for this single-resource fetch.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds that the API key is sent as a header, and lists returned fields. No contradictions.

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

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

The description is concise, front-loaded with purpose, and contains no unnecessary words. Could be slightly more structured but overall effective.

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

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

Without an output schema, the description lists the key returned fields. It covers auth requirements and filtering. However, it lacks details on pagination, sorting, or the 'recent' timeframe, which would be helpful for a list tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context for _apiKey ('Sent as the X-N8N-API-KEY header') and instance_url ('Must be a public https URL'), going beyond schema.

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

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

The description specifies the action (listing recent executions), the resource (workflow executions in n8n), and provides example use cases. It clearly distinguishes from sibling tools like n8n_get_workflow and n8n_list_workflows by focusing on execution history.

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 context (e.g., 'for did our workflows run') and states required auth. However, it does not explicitly compare to sibling tools or mention when not to use this tool instead of others like n8n_get_workflow.

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 transparency by listing the exact fields returned (id, name, active, createdAt, updatedAt, tags) and the required authentication keys (API key, instance URL). This supplements the annotations well without contradiction.

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

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

The description is efficiently structured: first sentence states the core purpose, then example questions, then return fields, then parameter hint, then auth requirements. No superfluous sentences. It is front-loaded and concise.

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

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

Given there is no output schema, the description covers the return fields (id, name, active, createdAt, updatedAt, tags) adequately. It also mentions authentication requirements. The limit parameter handles pagination hints. It could mention that the response is an array or include error scenarios, but for a listing tool 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%, so parameters are already documented. The description briefly repeats the active_only parameter ('Set active_only:true to list just the live ones') but does not add new meaning beyond what the schema provides. The baseline of 3 applies as the schema carries the burden.

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

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

The description uses specific verbs ('list') and a clear resource ('workflows in YOUR n8n instance'), with explicit example questions and a breakdown of returned fields. It distinguishes itself from sibling tools like n8n_get_workflow and n8n_list_executions by focusing on listing multiple workflows with active/inactive status.

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 example usage scenarios ('how many active workflows do we have', 'list our n8n workflows') and indicates when to use the active_only filter. While it doesn't explicitly state when not to use this tool, the presence of sibling tool names like n8n_get_workflow implies alternative for single workflow retrieval. The context is clear enough for an agent to 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?

Description adds significant context beyond annotations: it explains that feedback goes to the team, is read daily, affects roadmap, and is rate-limited. Since annotations are all false, the description fully carries the burden of behavioral disclosure, which it does comprehensively.

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

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

The description is a single paragraph that is well-structured: opening purpose, usage guidance, behavioral notes, and limitations. Every sentence adds necessary information without redundancy. It is efficient 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 simplicity and the lack of an output schema, the description fully covers what an agent needs: purpose, usage, behavior, and limitations (rate-limit, quota). No critical information is missing.

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

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

Schema coverage is 100%, but description adds value by elaborating on the enum type values ('bug', 'feature', etc.) and providing guidance on how to use the optional context fields. This enriches the schema details, so a score above baseline is warranted.

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

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

Description clearly states verb 'Tell' and resource 'Pipeworx team' with scope 'something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools (none of which are feedback tools) by specifying that it's for submitting feedback about tools/packs.

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

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

Explicitly lists when to use (bug, feature/data_gap, praise) and when not to (avoid pasting end-user prompt). It provides context on describing issues in terms of tools/packs, notes rate limits (5 per identifier per day), and clarifies that it's free and doesn't count against the tool-call quota.

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 significant context: data source (CF analytics-engine), PII disclaimer, caching behavior (5min-1h). 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 brief yet comprehensive, using two main sentences with a bullet list of uses. Every sentence adds value—no filler or repetition.

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

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

While the description covers purpose, use cases, behavior, and parameter semantics, it lacks an explicit description of the return format (e.g., structure of results). However, given the tool's simplicity and no output schema, the description is sufficient for an AI to decide to use it.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds value by explaining that shorter windows surface hot trends while longer windows show steady-state demand, going beyond the schema's enum description.

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

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

The description uses specific verbs ('Returns') and resources ('top tools, top packs, total call volume') and distinguishes itself from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on trending data rather than specific answers or tool discovery.

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 lists three distinct use cases (discovering hot data sources, confirming canonical tool choice, aligning use case) and implies when not to use (for factual queries, not trend analysis). This provides clear guidance over 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 indicate readOnly, openWorld, idempotent, and non-destructive behavior, which the description does not contradict. The description adds rich behavioral detail: semantic anchor, partition filter, fill check against live CLOB depth, and conditions for trade signals. It fully discloses the tool's logic and limitations.

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

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

The description is comprehensive but slightly verbose. It uses paragraphs with clear sections, though the formatting could be more structured (e.g., bullet points). All information is relevant and earns its place, but could be tighter.

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 response structure (opportunities array, partition_check, fill_check details) and even references a sibling tool for custom sizing. It covers edge cases (skipped_low_similarity, placeholders_filtered) and provides complete context for an AI agent to use the tool 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?

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains the difference between 'event' and 'topic' modes, provides example inputs, and details how each parameter affects behavior (single-event vs cross-event scanning). This greatly aids parameter selection.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases and examples, making the purpose unambiguous.

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

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

The description explicitly requires one of 'event' or 'topic' and warns that calling with no args fails. It recommends event for specific markets and topic for cross-event scanning, and mentions custom sizing using polymarket_fill_risk as an alternative. However, it does not explicitly state when not to use this tool versus other 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 readOnlyHint, openWorldHint, and idempotentHint as true, indicating safe read-only behavior. The description adds substantial behavioral context: caching at KV level keyed on all knobs (1h TTL), diagnostics for empty segments, 24h-move warnings, and detailed filtering logic for each segment. 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 well-structured with bolded segment names and hierarchical details, but it is dense with technical information. It front-loads the purpose and then dives into specifics, which is good, but the length may be overwhelming for an AI agent. It earns its place but could be more concise.

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

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

Given 9 parameters, no output schema, and rich annotations, the description compensates thoroughly by detailing the response structure (by_segment, fed_candidates, _diagnostics) and explaining the rationale behind each segment. It ensures the agent knows what to expect and why segments might be empty, providing a complete picture.

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 parameters are already well-documented in the schema. The tool description provides overarching context for the 'tradeable-edge knobs' but does not add significant new meaning beyond the schema's descriptions. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is a specific verb-resource pair, and the phrase 'Built for "what should I bet on today"' distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on opportunity discovery.

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

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

The description provides strong usage context with detailed explanations of when to adjust knobs like min_kelly, max_spread_pp, and min_liquidity. However, it does not explicitly state when NOT to use this tool or mention alternatives among siblings, so it misses explicit exclusions.

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

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

The description adds extensive behavioral context beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false). It details the response structure (tracked[], expired[], snapshot_dates[]) and explains how derived fields like trend and decay_pp_per_day are computed. It also discusses snapshot gaps due to cache-miss and the 60-day TTL, providing transparency about data availability.

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

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

The description is well-structured: it starts with the core purpose, then arguments, then response format, then limitations. It is front-loaded with the key question it answers. While quite detailed, every sentence adds value, though some sentences are run-on and could be tightened slightly.

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 comprehensively covers return values including the meaning of each field (tracked[], expired[], snapshot_dates[]). It explains derived metrics and data gaps. The tool is complex (historical telemetry), and the description provides all necessary 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 description coverage is 100%, so both parameters have basic descriptions. The tool description adds value by explaining the 'window' parameter in terms of snapshot families (24hr, 1wk, 1mo) and clarifying the default and clamp for 'days'. This adds context beyond the schema, though the schema already covers syntax.

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 using specific verbs and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than just raw edges.

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

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

The description provides clear context on when to use: to determine if an edge is fresh or old, noting that a fresh wide edge and a 3-week-old wide edge are different trades. It includes limitations such as the 60-day snapshot TTL and that decay is from daily closes not intraday. However, it does not explicitly state when not to use or suggest alternative tools for different needs.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, indicating a safe read operation. The description adds rich behavioral detail: walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; basket mode returns theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. Warns about partial fills and unhedged directional risk.

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

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

The description is verbose, spanning multiple paragraphs with repeated details (e.g., mode descriptions). While structured with headings, it could be more concise. Every sentence adds value, but the density could be improved.

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 modes, many return fields, no output schema), the description is thorough. It covers both modes, parameter behavior, return values (key fields listed), and risks (partial fills, directional risk). An agent can fully understand what to expect and how to interpret results.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The explanation adds significant meaning beyond the schema: clarifies mode-dependent behavior (single-market vs basket) for parameters like size_usd and side, explains default side for basket mode, and gives real-world constraints (default 1000, clamp 10–1,000,000).

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes, and explicitly differentiates from siblings like polymarket_arbitrage and polymarket_edges by advising 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade 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 usage context: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains risks of partial basket fills and thin books. Lacks explicit 'when not to use' but gives strong situational 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, and destructiveHint. The description adds extensive behavioral context: two modes, response structure (leg-by-leg prices, matched spreads, safety fields), compatibility warnings with scenarios, temporal alignment, and skipped comparators. 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 long but well-structured: starts with core purpose, then two modes, response details, safety fields, and caveats. Every sentence provides value; however, some sections (e.g., skipped_cross_type counters) could be slightly more concise without losing clarity. Front-loaded with key info.

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

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

Despite lacking an output schema, the description thoroughly explains the response format (leg prices, matched spreads with 'top_spreads_pp', safety fields like compatibility_warning and temporal_alignment). It covers all critical context for an agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning: explains that 'topic' maps to 10 shortcuts, and explicit parameters override the mapped side with expected format examples (e.g., 'KXFED-26OCT'). This goes beyond the schema by clarifying usage semantics.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (compute spread) and resource (two prediction markets), distinguishing it from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly describes two modes ('topic' and explicit parameters) and warns that most pre-mapped topics return compatibility warnings, guiding agents when to use alternatives. It sets clear expectations that 'pre-mapped ≠ tradeable' and explains the conditions for meaningful spreads.

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 info beyond annotations: omitting key lists all keys, scoping by identifier. Annotations already indicate read-only and idempotent; description aligns and enriches with usage context and 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?

Two sentences, front-loaded with core behavior, then use cases and scope. No wasted words; each sentence adds distinct 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 tool with one optional parameter, the description covers retrieval and listing behavior, scope, and usage context. Lacks return format details, but output schema is absent; still sufficient for agent understanding.

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 and describes the key parameter. Description adds the dual behavior (omit to list all keys) and clarifies purpose of key as retrieval vs listing, exceeding 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?

Clearly states the verb 'retrieve' and 'list' with resource 'value previously saved via remember' or 'all saved keys'. Differentiates from siblings like remember and forget by explicitly pairing with them.

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

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

Explicit use cases: 'look up context the agent stored earlier... without re-deriving it from scratch', with examples. Implicitly suggests alternatives through sibling pairing, but lacks explicit when-not-to-use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details like the mark_read flag's effect on subsequent calls and the structure of returned events, providing 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 a concise paragraph with 4 sentences, each adding value. It front-loads the main purpose and includes details without unnecessary fluff. Perfectly sized for quick comprehension.

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 covers return fields and key behaviors. It mentions the alternative endpoint and provides enough context for effective use. Minor gap: no mention of error handling or rate limits.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for 'type' (e.g., 'sec_8k'), clarifies 'since' as ISO timestamp, and explains the effect of 'mark_read', adding meaning beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the resource and action. It mentions the return fields (source, citation_uri, payload), but does not explicitly differentiate from sibling tools like list_subscriptions, preventing a 5.

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 guidance on when to use this tool ('Polls work fine') and mentions an alternative direct endpoint for scripts/dashboards. It explains filtering options but does not explicitly state when to avoid this tool or compare to other MCP tools.

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

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

The description discloses multiple behavioral traits beyond annotations: the fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback mechanism, the PatentsView API sunset soft-fail, and the output structure. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with concrete example queries. It is somewhat long but every sentence adds value; a slight reduction in length could be possible 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?

The description is comprehensive for a complex tool with multiple data sources, fallback behavior, and no output schema. It explains return structure, parameter semantics, and differentiation from a sibling tool. No gaps are evident.

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 description adds substantial meaning beyond the input schema: it explains the `since` parameter accepts both ISO dates and relative shorthand with examples, clarifies that `value` can be a ticker or CIK, and notes that `type` currently only supports 'company'. Schema coverage is 100% so baseline would be 3, but the description compensates and adds context.

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

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

The description explicitly states the tool is for 'What's new with X' / 'latest on Y' queries, and lists multiple example user intents. It clearly differentiates from sibling tool entity_profile by specifying when to use each.

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

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

The description provides explicit usage guidance: it tells when to use this tool vs. entity_profile (static profile). It also explains the fallback logic (GDELT -> GNews) and the acceptable input formats for the `since` parameter.

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

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

Annotations indicate idempotent and non-destructive. Description adds beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. No contradictions.

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

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

Three well-structured sentences with no fluff. Front-loaded with purpose, then usage, then behavior. Every sentence earns its place.

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

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

No output schema, but description explains storage mechanism (key-value pair, scoped by identifier) and persistence behavior. Also mentions pairing with recall and forget, making it complete for a simple tool.

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

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

Schema coverage is 100% with descriptions for key and value. Description adds context on what to store (findings, addresses, preferences) and usage examples, adding value beyond schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It provides specific examples of what to save (resolved ticker, target address, user preference) and distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject) so you don't have to look it up again.' It pairs with recall and forget, giving clear usage context.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral details: each call cascades through several internal endpoints, auto-disambiguates inputs, and returns citation URIs. This fully contextualizes the tool's operation beyond the annotations.

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

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

The description is a single, well-structured paragraph that front-loads example queries and then details behavior. Every sentence adds value—no redundancy. It is concise yet comprehensive.

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

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

Given the absence of an output schema, the description thoroughly explains return values for each entity type, including specific fields and citation URIs. It covers input variations, internal cascading, and entity-specific details, making the tool fully understandable.

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, but the description enriches both parameters: for 'type' it gives concrete examples (e.g., 'company', 'drug'), and for 'value' it explains acceptable formats and auto-disambiguation. This adds meaning 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 starts with concrete example queries and explicitly states the tool's purpose: resolving a user-spoken name to a canonical identifier required by other tools. It clearly distinguishes between supported entity types (company, drug) and describes the output fields, making the purpose very specific and actionable.

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 FIRST whenever you have a name but need an ID', providing clear guidance on when to invoke this tool. It also notes that it replaces multiple manual lookups. However, it does not explicitly state when not to use it, missing a small but useful exclusion.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns per-entity metrics. It also notes the optional _apiKey requirement for Anthropic models, which goes beyond annotations.

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

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

Three sentences, each necessary: core action, how it works, use case. Front-loaded with verb and resource. No extraneous words.

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

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

The description covers purpose, process, and output format. Lacks mention of error handling or number of probes, but for a read-only tool with high annotation coverage, it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that 'entities' first entry is the subject, and that 'models' includes 'workers-ai' as default. It also explains the 'context' parameter disambiguates common names.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using ai_visibility_check, and ranks them. It distinguishes from sibling ai_visibility_check by emphasizing multi-entity comparison, and from compare_entities by specifying the domain (AI presence).

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 targets competitive AI-marketing audits and implies single-entity use should go to ai_visibility_check. However, it does not explicitly list when not to use 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?

Beyond annotations (readOnlyHint, idempotentHint), the description reveals composite behavior (fans out to two services), partial failure handling (sources_failed), bundlephobia latency (5-30s on first measurement), and complete return structure. This fully prepares the agent for behavioral expectations.

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

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

The description is front-loaded with the core purpose and then provides necessary details. While slightly long, every sentence adds unique value (limitations, return fields, error behavior). It is well-structured and efficient for the tool's complexity.

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

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

Despite no output schema, the description comprehensively lists all return fields (summary block with 9 fields, advisories, links, alternative versions) and handles edge cases (partial failures, latency). This ensures the agent knows exactly what to expect.

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

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

Schema description coverage is 100% (both package and version have descriptions). The tool description adds a note about scoped packages being accepted, but the schema already mentions that. Baseline 3 is appropriate; the description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for evaluating whether to add an npm package, combining data from deps.dev and bundlephobia. It specifies the verb 'check' and the resource 'npm package', and the scope is unique among sibling tools which cover different domains.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clarifies limitations: NPM ecosystem only in v1, and mentions alternative tools for other ecosystems. This leaves no ambiguity about when to invoke.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral details: uses BGE-base-en embeddings with cosine similarity over 500-char windows, 200K char limit with truncation flag, and each passage includes offset for verification.

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 3 sentences plus technical details. Core purpose is front-loaded. Every sentence serves a purpose: what it does, when to use, and how it works internally. No wasted words.

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

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

No output schema, but description explains what is returned (top-N passages, offsets, similarity scores). The tool's complexity (semantic search) is well covered given the annotations and input schema richness. Complete 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 coverage is 100%, so baseline is 3. The description adds context: 'text' is a document already fetched, 'query' is a natural-language request with examples, and 'limit' default and range. This adds meaning beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with examples (SEC 10-K, article) and specifics on output (passages with offsets and scores). It distinguishes from sibling tools 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 for the prompt. Also provides a specific alternative: pairing with ask_pipeworx_grounded for grounding over relevant passages.

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: describes authentication, rate limits (10/day SMS), webhook auto-disable, and return of new subscription id. Idempotency not explicitly addressed but annotations cover it.

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

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

Well-structured and front-loaded with purpose. Succinctly covers complex information without redundancy. Slightly long but justified by depth.

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 tool with 3 params, 5 types, and no output schema. Explains all constraints, delivery behavior, and integration points. An agent can confidently invoke this tool.

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

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

Description richly extends the schema with concrete examples for each type, parameter structure, and delivery channel details including verification and caps. Fully compensates for 100% schema coverage with additional context.

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

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

Clearly states verb (create), resource (subscription), and key outcome (returns subscription id). Distinguishes from siblings like list_subscriptions, unsubscribe, recent_alerts.

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 required OAuth account, lists supported types with examples, and contrasts with pull-based recent_alerts. Could be more explicit about when not to use, but context is clear.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context about returning category-bucketed example questions and exact tool+argument shapes, and its role as an onboarding tool. No contradictions or missing critical behavioral traits.

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 and well-structured, front-loading common user queries. Each sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given no output schema, the description adequately explains the return type (category-bucketed example questions with tool shapes). It also contextualizes its role relative to other tools, making it complete for its purpose.

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

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

Schema coverage is 100% with a single optional parameter. The description adds meaning by explaining that omitting topic yields a cross-category spread and lists valid focus areas, providing context 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 returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes from siblings by specifying its role in helping users learn what Pipeworx can do and how to call meta-tools.

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

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

Explicitly advises to use this tool 'FIRST when you do not yet know what Pipeworx can do for you' and explains how to use it with or without the topic argument. It provides clear context but does not explicitly state when not to use it or alternative tools.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement, row deactivation (not deletion), and preservation of historical events. This fully compensates for the lack of annotation detail.

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 efficient sentences: action, constraint, effect. No wasted words; front-loaded with the core purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage constraint, and side effects. It references sibling tools appropriately.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by specifying the source of the id ('returned by subscribe') and the ownership context, which clarifies usage.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes it from sibling tools like subscribe (creation) and recent_alerts (historical events). It also includes specific behaviors like ownership enforcement and deactivation.

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 indicates when to use (to cancel a subscription) and includes a constraint (ownership enforced). It could explicitly mention alternatives like list_subscriptions for finding IDs, but the guideline is still 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=False. The description adds value by detailing the return structure (verdict, structured form, actual value with citation, percent delta) and efficiency gains, which are not covered 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 well-structured with examples first, then purpose, scope, and output details. It is slightly lengthy but each sentence adds value, and it is front-loaded with usage triggers.

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 single parameter and good annotation coverage, the description is fairly complete. It explains the supported domain, what it returns, and its efficiency, which is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description does not add further meaning to the 'claim' parameter beyond the schema description, so score remains at baseline.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific examples of queries and distinguishes itself from sibling tools by noting it replaces 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies the domain (company-financial claims) but doesn't explicitly state when not to use it, though the scope is clear.

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