N8n

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds valuable context beyond that: the default free Workers AI model, the BYO-API-key cost implication for Anthropic calls, and the per-model return structure. It does not mention potential timeouts or error handling, but given the strong annotation coverage, the added cost and model behavior details warrant a 4.

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

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

The description is compact (~70 words), front-loaded with the core purpose in the first sentence, and every subsequent sentence adds necessary detail (default behavior, cost, return format, use cases). There is zero redundancy or filler.

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

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

With no output schema, the description compensates by explicitly listing the return shape (per-model {score, confidence, signals, raw_response} + combined view). It covers default model, optional auth, and realistic use cases. Minor gaps remain around failure modes or cache behavior, but for a 4-parameter tool this is well-rounded and nearly 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 meaning beyond the schema by naming the exact default model ('Workers AI Llama-3.3-70b'), clarifying that omitting 'models' yields just the free default, and explaining the _apiKey pass-through semantics (BYO key, direct billing). This enrichment pushes the score to 4.

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

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

The description uses specific verbs ('Probe', 'score visibility') and a clear resource ('one or more LLMs'), with a concrete output range (0-100 per model). It distinguishes itself from general question-answering tools by emphasizing per-model scoring and a combined view, 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 clearly states when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing strong contextual guidance. However, it does not explicitly name alternatives or state when not to use it, especially given the similar sibling tool 'scan_competitor_ai_presence', so it misses full exclusion 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context about routing across many tools, filling arguments automatically, and returning structured answers with pipeworx:// citation URIs. It does not mention edge-case behavior like unsupported questions or response-time variability, but that is a minor gap.

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

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

The description is longer than average but front-loaded with the most important guidance and organized logically: when to use, what it does, examples, and alternatives. The domain list is useful for such a broad routing tool, though a few promotional phrases like 'one fast call' and 'works on every tier' add only marginal 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?

Since no output schema is provided, the description attempts to compensate by noting that the result is a structured answer with stable citation URIs. It also explains broad source coverage, routing behavior, and step-up alternatives. Exact output shape is not described, but for a highly open-ended routing tool this is a reasonable and mostly complete level of detail.

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

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

Schema description coverage is 100% because the single meaningful parameter question is fully documented, including all aliases. The description's examples show natural-language usage but do not add much beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly identifies ask_pipeworx as a broad factual-answer tool that routes questions to the appropriate source tool and returns a structured answer with citation URIs. It explicitly contrasts itself with siblings like ask_pipeworx_grounded and deep_research, making the purpose and differentiation crisp.

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

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

The description gives explicit and practical when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specific example query triggers. It also tells the agent when to step up to ask_pipeworx_grounded or deep_research, which is excellent alternative-selection 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=false. The description adds behavioral context beyond annotations: it explains the dynamic nature (candidate routing may be active, currently none), and that it is a full working router, not a fallback. It doesn't contradict annotations and provides useful a priori information for the agent.

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

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

The description is moderately sized but front-loaded with the beta nature and current state. It is structured logically, first explaining what it is, then current status, then usage instruction, and finally a clarification that it's fully functional. Each sentence adds value, though some redundancy exists (e.g., 'identical universal router' and later 'this IS a full working router'). Still, it's concise enough.

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

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

Given the tool's complexity (a router with thousands of tools) and the provided schema and annotations, the description is complete. It explains the response shape, current state, usage guidance, and reassures it's fully functional. No output schema exists, but the description compensates by referencing the same response shape as ask_pipeworx, which is sufficient context.

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

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

Schema description coverage is 100%, with each parameter well-documented (aliases for 'question'). The description does not add any additional parameter semantics beyond the schema, so baseline 3 is appropriate. No extra context is provided about parameter usage or constraints.

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

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

The description clearly states it's a beta version of ask_pipeworx, a universal router with the same tools and arguments, and explicitly distinguishes itself by being the experimental edge with candidate routing improvements. It names the sibling tool ask_pipeworx and explains the current state (identical to stable router). This is specific and differentiates from siblings.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared to decide merges. It provides clear context for when to use it, though it doesn't explicitly list when not to use it or alternative tools, but the context implies the stable ask_pipeworx for non-experimental 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?

Goes far beyond annotations by detailing the return contract: success shape with answer/evidence/confidence/source/fetched_at, and explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also discloses the extra LLM call cost. Annotations already declare read-only/idempotent, so the description's extra behavioral detail is additive and non-contradictory.

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?

Every sentence earns its place: purpose, mechanism, return shape, refusal cases, usage guidance, and cost tradeoff. It is front-loaded with the most important label and contains 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?

Despite having no output schema, the description fully specifies return values and error/refusal cases. It contextualizes when the tool should be used and names the alternative, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (all six params are aliases for question, each documented). The description doesn't add parameter-specific syntax or formats, but it doesn't need to; the schema carries the full burden. Baseline 3 is appropriate.

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

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

The description opens with a specific, high-signal label: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly explains the tool's mechanism (routing, fetching, extracting from tool result) and differentiates itself from the sibling ask_pipeworx by stating it uses only the tool result and costs an extra LLM call.

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

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

Explicitly provides 'when to use' ('whenever an answer will be quoted, cited, or acted on...') and 'when not to use' ('prefer ask_pipeworx for casual lookups'), naming the exact alternative. This is exemplary usage guidance.

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

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

Beyond the readOnly/idempotent annotations, the description richly discloses behavior: resolver match confidence and alternatives, low-confidence short-circuiting, blocked paths for closed/dead markets, wide-spread illiquidity flags, cancellation-rule risk with ev impact, 24h-move warnings, and news-fallback failure fields. No contradiction with annotations exists.

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 clearly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK) and front-loads the core purpose. It is long and dense, but nearly every section conveys unique operational detail that helps an agent use the tool correctly; minor trimming could improve conciseness without losing 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 the tool's complexity and lack of an output schema, the description is exceptionally complete. It covers response shapes (result.market, result.analysis, result.evidence), resolver trust contract, parent-event extraction, news fallback behavior, safety mechanisms for low-confidence/closed markets, and resolution-rule risk. An agent has enough context to invoke the tool and interpret its output safely.

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

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

Schema description coverage is 100%, so the schema already documents market input forms, depth enum, and include_raw behavior/defaults. The description reinforces these via examples and fan-out context but does not add meaningful new parameter semantics beyond what the schema already provides, matching the baseline of 3.

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

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

The first sentence clearly states a specific action and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from siblings like polymarket_edges and polymarket_arbitrage by describing its one-call research, classification, fan-out to category-specific data packs, and market-vs-model comparison outcome.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also lists classifiers and fan-out examples to help agents choose it for specific bet types. It does not mention when not to use it or name alternative sibling tools, so it falls short of full alternative/exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA), off-calendar fiscal year handling, sorting by primary metric, and pipeworx:// citation URIs per entity. This goes far beyond annotation metadata.

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

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

The description is dense but every sentence serves a purpose: query examples, scope constraints, data source details, output format, and performance efficiency. It is front-loaded with the most actionable usage cues and contains no filler or redundant restatements.

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

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

Given the tool's complexity (two entity types, multi-source data, sorting, citations) and lack of an output schema, the description is remarkably complete. It covers triggers, scope, data sources, edge cases (fiscal year handling), result ordering, output URIs, and performance benefits—fully standing in for return-value documentation.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by explaining what each type pulls (company financial metrics vs drug adverse-event/trial data), providing concrete examples for values (tickers/CIKs, drug names), and noting the sorting behavior tied to the primary metric. This adds significant value beyond the schema.

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

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

The description explicitly states the tool's function with specific verbs ('compare', 'side-by-side comparison'), identifies the resource scope (2–5 companies or drugs), and distinguishes itself from 'sequential single-pack lookups'. This clearly separates it from sibling tools like entity_profile.

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

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

It provides explicit trigger phrases ('X vs Y', 'rank these companies'), states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and notes the efficiency gain ('replaces 8–15 sequential lookups'), giving clear when-to-use guidance and an alternative approach to avoid.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, but the description enriches understanding with details on findings packet structure, gaps[] behavior, never-invented policy, second-hop iteration, contradictions[], citation resolvability, and latency. No contradictions with annotations.

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

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

The description is long but every sentence adds substantive detail about capabilities, limitations, account requirements, alternatives, and runtime. It is a single dense paragraph without bullet points, but remains highly informative and earns its length given the tool's complexity.

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

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

The description fully compensates for the lack of an output schema by explaining the returned findings packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]) and important behavioral nuances. Combined with rich annotations, nothing critical is missing for an agent to select and invoke correctly.

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

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

The input schema already covers 100% of parameters with descriptions, so baseline is 3. The description adds value by explaining consequences of depth choices (gap recovery, contradiction scanning, hop counts) and emphasizing that questions can be broad/multi-part, which is not in the schema.

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

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

The description explicitly identifies deep_research as a grounded multi-source research tool across 1462 structured data sources, with clear differentiation from open-web search and siblings like ask_pipeworx. It states the resource and scope, 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?

Provides explicit when-to-use guidance: best for broad/multi-part structured-data questions, and when not to use it (single lookups, breaking/current news). Also names specific alternatives (ask_pipeworx) and explains conditional behavior (account required, depth tiers).

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 readOnly, idempotent, and non-destructive, but the description adds valuable behavioral context: returns top-N relevant tools with names, descriptions, and full input schemas, and that results are ready to call directly without a second schema lookup. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences with the main purpose front-loaded. The second sentence, though long, efficiently lists domain coverage and output specifics, and the third gives actionable usage advice. Every sentence earns its place without redundancy.

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

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

Given the absence of an output schema, the description compensates by fully explaining what is returned (top-N tools with names, descriptions, schemas, examples). It covers what the tool does, when to use it, and its output format. The large sibling set makes this tool an index, and the description clarifies its role as a discovery entry point.

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

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

Schema description coverage is 100%, and the schema itself already provides detailed parameter descriptions including aliases and examples. The description mentions 'describing the data or task' which aligns with the query parameter but adds no new semantic information beyond what the schema provides, so the 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 tool's purpose with a specific verb ('Find tools') and resource ('tools by describing the data or task'). It distinguishes itself from siblings by positioning as a discovery tool to be called first when exploring available tools, contrasting with the many specific task-oriented sibling 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 says 'Use when you need to browse, search, look up, or discover what tools exist' and provides a concrete domain list. It also instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', which gives clear guidance on when to use it versus alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses concrete behavioral traits: parallel fan-out across multiple sources, the USPTO PatentsView API sunset with soft-fail behavior, GDELT→GNews fallback, and the exact return fields. This goes well beyond annotation basics.

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

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

Long but information-dense and well-structured. The initial examples front-load the use case, followed by preference guidance, then a structured list of return data, and finally input format caveats. No wasted sentences; every detail is functional.

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 (multi-source aggregation, no output schema), the description is remarkably complete. It covers return fields, data source limits (up to 5 filings), fallback behavior, and input constraints. All critical information an agent needs to invoke and interpret results is present.

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

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

The input schema already covers both parameters with 100% description coverage, including valid formats and the name-not-supported caveat. The description repeats this info without adding new parameter semantics, so the 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 tool creates a 'full cross-source profile of a US public company' with specific verb ('profile') and resource ('US public company'). It distinguishes itself from siblings by explicitly saying to prefer this over chaining single-pack SEC/XBRL/news lookups and references resolve_entity for name-only inputs.

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

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

Provides explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when-not-to-use ('names not supported — use resolve_entity first'). This is rare and highly useful for an agent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds context about the data being 'sensitive' and 'previously stored', but does not disclose additional behavioral details such as irreversibility (beyond destructiveHint) or what happens when the key doesn't exist. It provides minimal 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?

Two sentences, efficiently front-loaded with the action and resource. The first sentence states the core function; the second provides usage scenarios and complementary tools. No redundant information.

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

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

Given the simple single-parameter delete operation, strong annotations, full schema coverage, and no output schema, the description covers purpose, usage, and pairing with related tools. It is sufficient for an agent to decide when and how to invoke this 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 description coverage is 100% and the only parameter 'key' is described as 'Memory key to delete'. The description does not add further detail about accepted formats, constraints, or behavior of the key parameter, so it relies on 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 the specific verb 'Delete' with a resource 'previously stored memory by key', and clearly distinguishes itself from sibling tools by mentioning pairing with remember and recall. It is immediately clear what the tool does.

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

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

It explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It does not provide explicit when-not guidance, but the positive usage contexts are clear. The mention of pairing with remember and recall suggests complementary usage, though not formal alternatives.

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

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

The description explains the internal process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also discloses the output format ('single text blob') and placement. Since annotations already declare readOnly/idempotent safety, this additional context is valuable and not redundant.

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

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

The description is compact and front-loaded, with two sentences covering the core functionality and a brief, focused 'Useful for' list. Every statement contributes useful information without fluff.

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

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

Given the tool's simplicity (2 params, no output schema) and solid annotations, the description covers purpose, process, output format, and use cases. It is sufficiently complete 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?

Both parameters are fully described in the schema, including the default and max for max_links. The description does not add extra meaning beyond what's already in the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific verb 'Generate' and resource 'llms.txt'. It also explains the purpose (helping AI crawlers index) and distinguishes from sibling tools that audit AI presence or visibility.

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 by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not explicitly mention alternative sibling tools or when not to use this tool, so it falls just short of full 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, covering the safety profile. The description adds that the tool returns the caller's own subscriptions, not global ones, and explicitly lists the output fields. This provides valuable context beyond the annotations, though it doesn't mention any additional behavioral nuances like pagination limits.

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

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

The description is two sentences long, front-loaded with the core action and resource, followed by return fields and usage guidance. Every word earns its place; there is no redundancy or fluff.

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

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

For a simple list operation with one optional parameter, the description fully covers what the tool does, what it returns, and when to use it. Combined with the rich annotations and complete schema, there are no significant gaps.

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

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

The only parameter, include_inactive, is fully described in the schema, so schema coverage is 100%. The description adds no extra meaning about the parameter, but the schema already explains it well. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb 'List' with a clear resource: 'the caller's active subscriptions'. It also lists the return fields, which further clarifies what the tool does. This distinguishes it from sibling tools like subscribe and unsubscribe, which are mutation operations.

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

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

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear usage context and implies alternatives (subscribe/unsubscribe) without naming them directly, but the guidance is strong and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the tool as a safe read operation. The description adds valuable context beyond annotations: it lists the returned fields, explicitly mentions the auth requirement (instance_url + API key), and notes the id source. This goes beyond the baseline provided by annotations.

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

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

The description is two sentences, front-loaded with the main purpose, and includes essential details (return fields, id source, auth requirement) without any fluff. Every sentence earns its place.

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

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

For a simple read tool with 3 fully documented parameters, rich annotations, no output schema, and a clear prerequisite from a sibling tool, the description is complete. It explains what is returned, how to get the id, and what auth is needed. There are no significant gaps.

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

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

Schema coverage is 100% with detailed parameter descriptions (e.g., '_apiKey' is sent as X-N8N-API-KEY, instance_url format). The description adds extra meaning by stating that workflow_id comes from n8n_list_workflows, which is not in the schema, thereby clarifying the parameter's provenance and 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 tool's purpose with a specific verb ('Get') and resource ('one workflow's detail by id'). It enumerates the returned fields (name, active state, node list, tags, timestamps), distinguishing it from list tools by emphasizing the 'by id' scope and explicitly referencing n8n_list_workflows as the source of the id.

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

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

The description provides clear usage context: 'Get the id from n8n_list_workflows' establishes a prerequisite workflow. It implies this tool is for fetching full details after listing workflows. However, it does not explicitly state when NOT to use it or mention alternatives (e.g., n8n_list_executions), so it lacks 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?

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable context: it mentions required auth (instance_url + API key), summarizes the output fields, and notes the 'recent' scope of executions. 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 three sentences: purpose, output fields, then filtering and requirements. It is front-loaded and every sentence carries meaningful information without redundancy.

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

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

With 5 parameters, no output schema, and richer annotations, the description covers purpose, use cases, output shape, auth requirements, and filtering. It is sufficiently complete for an agent to select and invoke correctly; only minor details like pagination are left to the schema.

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

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

Schema coverage is 100% and parameter descriptions are thorough. The description only restates 'Filter by status and/or workflow_id', which adds minimal value beyond the schema. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

The description uses a specific verb+resource: 'List recent workflow executions (runs)' which clearly distinguishes from sibling tools like n8n_list_workflows and n8n_get_workflow. It also lists concrete use cases ('did our workflows run', 'show recent failures', '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 provides clear context for when to use the tool via use cases and mentions filtering by status/workflow_id. However, it does not explicitly state when not to use it or name alternatives like n8n_list_workflows for workflow definitions, just implies the distinction.

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 a safe read-only, idempotent operation. The description adds useful context by stating the required credentials (instance_url and API key) and the fields returned per workflow, which is valuable beyond the annotations. No contradiction with annotations.

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

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

The description is a compact, front-loaded paragraph that conveys purpose, examples, return fields, and a filtering option in just a few sentences. Every sentence adds value without redundancy.

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

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

The description covers the essential behavioral aspects: what it lists, the breakdown, authentication requirements, and return fields. While there is no output schema, the description compensates by naming the fields. It is not overly complex, and the annotations provide safety context, so this is reasonably complete.

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

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

Schema coverage is 100% and each parameter already has a clear description. The tool description does not add meaning beyond what the schema provides; it only repeats the active_only behavior already documented. Baseline 3 is appropriate since the schema handles parameter semantics.

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

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

The description clearly states the tool lists workflows in the user's n8n instance with an active/inactive breakdown, and provides example questions it answers. This distinguishes it from sibling tools like n8n_get_workflow and n8n_list_executions, 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 gives clear context for when to use the tool (e.g., answering questions about active workflows) and mentions the active_only flag for filtering. However, it does not explicitly exclude alternatives or reference sibling tools, so it lacks explicit when-not-to-use guidance.

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

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

The description reveals behavioral traits beyond the annotations: it explains the claim_token flow for anonymous filing, rate-limiting ('5 per identifier per day'), that it is free and doesn't count against quota, and that the team reads digests daily. These are valuable context not available from 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 the main purpose and then efficiently covers usage, exclusions, workflow, and limits. Every sentence adds value, and there is no redundancy or filler. It is appropriately sized 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?

The description is complete given the tool's complexity and the absence of an output schema: it explains the return mechanism (claim_token, status, resolved changes), rate limits, and the appropriate scope. It also accounts for edge cases like uncertain tool ownership with practical advice.

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

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

While the schema covers 100% of parameter descriptions, the description adds important usage nuances: it explains that claim_token is for retrieving previous feedback and must be passed alone, and it advises users to describe issues in terms of Pipeworx tools/packs and not paste user prompts. This goes beyond the schema's baseline 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 with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It further distinguishes sub-uses (bug, feature/data_gap, praise) and emphasizes it is exclusively for Pipeworx-served tools, making it distinct from any sibling 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?

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server in your client ... file it with that server instead,' pointing to the correct alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. Beyond that, the description adds valuable behavioral context: it explains the data source ('derived from CF analytics-engine'), privacy guarantees ('no PII, just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This goes well beyond what annotations provide.

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

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

The description is well-structured and front-loaded with the core purpose, followed by actionable use cases and important technical caveats. Each sentence contributes meaningful information—no fluff or redundancy. The use of bullet points improves readability without being overly verbose.

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

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

Even though there is no output schema, the description explicitly states the return contents: top tools, top packs, total call volume, and the data format '(pack, tool, count)'. It also mentions caching and the absence of PII, which addresses common concerns. For a tool with one optional parameter, the description provides sufficient context to select and 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?

The schema already covers the single parameter 'window' fully with an enum and a description ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The tool description repeats the window values but adds no new parameter semantics beyond what the schema explains. Thus, the baseline of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's function: it returns top tools, top packs, and total call volume over a recent window, with examples of the window values. This specific verb and resource clearly distinguishes it from siblings like discover_tools or ask_pipeworx, which focus on discovery or direct querying rather than aggregated trending signals.

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 'Useful for' bullets that give concrete scenarios: discovering hot data sources, confirming a canonical tool choice before asking, and checking alignment with other agents' needs. While it does not name alternative tools or say 'when not to use', the usage contexts are clear and actionable, giving strong practical guidance.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing internal logic like Jaccard similarity thresholds, placeholder filtering, fill-check pricing against live CLOB depth, and the 'do not trade' condition. It also explains response fields and edge cases, with no contradiction to 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 long but well-structured, front-loaded with the core purpose and then organized into modes, semantic anchor, partition filter, response, and fill check. Every section is operational and necessary for correct invocation, though it could be slightly condensed without losing value.

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

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

Given no output schema, the description fully specifies response fields and edge cases (skipped_low_similarity, placeholder fraction >20% null signal, realizable_edge_pp <= 0 no-trade rule). It also references related tools for complementary needs, making it comprehensive for a complex tool.

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

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

The schema already describes both parameters with examples and usage guidance, so the baseline is 3. The description enriches this by explaining what the tool does with each parameter (walks child markets for event, runs comparator on union for topic) and reinforces examples, adding meaningful behavioral 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 finds arbitrage opportunities on Polymarket via specific methods (monotonicity violations + partition-sum checks), distinguishing it from siblings like polymarket_fill_risk (which prices fills) and polymarket_edges. It also explains the different modes and what they accomplish, 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 provides explicit mode selection: no args for trending scan, event for a specific market, topic for cross-event scan, with concrete slug/examples and a recommendation. It also points to polymarket_fill_risk for custom sizing, giving clear alternatives and when to use them.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses extensive internal behavior: the three model families with their exact formulas, placeholder-slug filters, gate relaxation history, edge_pp_net definition, Kelly caps, the 24h-move warning, and KV-level caching. This is far more than annotations provide and gives the agent deep insight into how results are produced.

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 uses clear uppercase headers and (1)/(2)/(3) enumerations to organize segments, knobs, and response structure. Every sentence conveys substantive detail—from model formulas to caching—making it information-dense rather than wasteful. It loses one point only because the sheer length could overwhelm an agent parsing it quickly, but the structure effectively mitigates that.

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

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

Despite having no output schema, the description fully specifies the response top-level (by_segment, fed_candidates/fed_note, _diagnostics) and explains why segments might be empty. It also documents the caching behavior, Fed data limitations, and all knobs' effects. For a tool with 9 parameters and complex internal logic, this is exceptionally complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable nuance beyond the schema: it explains how min_liquidity/max_spread_pp act as 'tradeable-edge' filters, clarifies that min_partition_leg_kelly applies to per-leg Kelly inside top_legs (and why min_kelly doesn't filter partition arbs), and documents slippage assumptions. This extra context 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 opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' – a specific verb+resource+outcome. It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement discovery. The unique segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) further clarify exactly what the tool computes.

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 'Built for "what should I bet on today"' and mentions 'without paging hundreds of markets', giving a clear use case. It also warns that fed_candidates are 'excluded from ranking' due to unreliable signals, indicating when that portion should be ignored. It stops short of naming alternative tools explicitly, so it gets a 4 rather than a 5.

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

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

Annotations declare readOnly/idempotent hints, and the description adds substantial non-obvious behavior: snapshot write timing (cache-miss), gaps meaning no scan, 60-day TTL history bound, decay computed from daily closes net of slippage, and detailed response semantics for expired opportunities. No contradiction with annotations.

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

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

The description is long but every sentence adds value: purpose, args, response structure, and limitations are clearly segmented. The LIMITS section is particularly useful for setting expectations around TTL and computation methodology. 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?

With no output schema, the description thoroughly explains the response envelope (tracked[], expired[], snapshot_dates[]), field semantics, and edge cases (cache-miss gaps, TTL, slippage). This is complete enough for an agent to understand what results to expect and how to interpret them.

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

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

Schema coverage is 100% and describes both parameters (days with default/clamp, window with enum/default). The description repeats this information without adding genuinely new semantics. Baseline 3 is appropriate because the schema already does the heavy lifting.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question ('how long has this edge existed and is it shrinking?'). It differentiates from siblings like polymarket_edges by focusing on temporal tracking rather than raw edge listing, and explicitly contrasts fresh vs. old wide 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 implies when to use this tool (assessing edge persistence and decay before trading) and even provides a conceptual example ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not name explicit alternatives or exclusions, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), identifies thin_legs and forced_directional_risk, and flags the strategic danger of partial basket fills. This goes far beyond the annotation hints and proactively discloses important failure modes.

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

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

The description is long but exceptionally dense and well-organized. It front-loads the core purpose, then uses clear uppercase labels (SINGLE-MARKET, BASKET) to structure detailed behavior, parameters, and outputs. Every sentence adds substantive information; there is no filler or tautology. The structure aids quick comprehension despite the length.

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

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

Given the tool's complexity and the absence of an output schema, the description fully enumerates return values for both modes (top_of_book, vwap_fill_price, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, etc.), explains parameter semantics in context, and provides a clear usage rationale. It is sufficiently complete 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%, so the schema already documents each parameter well. The description adds the critical business rule that exactly one of `market` or `event` is required, and clarifies the mode-dependent interpretation of `size_usd` and `side` defaults (e.g., auto detection based on partition sum). While some of this is repeated from the schema, the exclusive-or constraint and the mode-specific usage guidance provide meaningful added value.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and enumerates outputs. It explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) and positions itself as a pre-trade risk check, 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?

The description states exactly when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It provides a clear decision threshold, explains why (theoretical overround is not capturable on thin books, partial fills create unhedged directional risk), and implies when it is necessary without ambiguity.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses output structure (leg-by-leg prices, spread), safety fields and their exact trigger conditions, temporal alignment semantics, and skipped comparison counters. It also warns when spreads are mathematically meaningless, which is valuable behavioral context.

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

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

The description is long but well-structured with explicit headings (TWO MODES, RESPONSE, SAFETY FIELDS) and is front-loaded with the core purpose. Every section delivers substantive detail, though some sentences are dense and could be tightened without losing meaning.

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

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

With no output schema, the description fully explains return values including raw probabilities, top_spreads_pp, temporal_alignment, compatibility_warning conditions, and skip counters. It covers all major edge cases and operational nuance expected from a complex cross-venue analysis 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%: each parameter has a description covering the topic list and override behavior. The tool description repeats this information without adding new semantic meaning, so it meets but does not exceed the baseline for full schema coverage.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, names two distinct modes, and includes an explicit caveat distinguishing it from single-venue analytics. This specific verb+resource combination sets it apart from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use topic shortcuts versus explicit ticker/slug pairings, and it warns that most pre-mapped topics return compatibility_warning, indicating limited tradeable use cases. However, it does not explicitly name or contrast with related sibling tools, leaving some implicit inference.

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

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

Annotations already declare read-only and idempotent behavior. The description adds important context beyond those annotations: scoping to the agent's identifier ('anonymous IP, BYO key hash, or account ID') and the listing behavior when the key is omitted. No contradiction exists.

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

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

The description is three sentences, each serving a distinct function: stating the core action, giving use-case context and examples, and noting scoping and sibling relationships. There is no wasted text, and the most critical information is front-loaded.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description covers the full behavioral scope: what it does, how the parameter changes behavior, scoping, and how it pairs with sibling tools. Nothing critical 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?

The single parameter is fully documented in the schema ('Memory key to retrieve (omit to list all keys)'), and the description repeats this meaning using consistent wording. No new semantic detail is added beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Retrieve a value previously saved via remember') and clearly distinguishes the two modes: retrieving a single key or listing all keys. It also explicitly contrasts with sibling tools 'remember' and 'forget', making the tool's unique role unambiguous.

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

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

The description provides explicit usage context ('Use to look up context the agent stored earlier') and names the alternatives with their functions ('Pair with remember to save, forget to delete'). This gives the agent clear guidance on when to choose this tool versus its 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?

The description discloses a write side-effect: mark_read:true flags events as read, affecting subsequent calls. This contradicts the readOnlyHint annotation. The annotation indicates a purely read-only tool, yet the tool can mutate read state, so the description contradicts the structured metadata.

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 (four sentences), front-loaded with the primary purpose, and every sentence adds value: return contents, filters, mark_read behavior, polling suitability, and alternative endpoint. No redundant text.

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

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

The description covers what is returned, the feed context, filtering options, mark_read behavior, and even an alternative access method. It does not explicitly discuss pagination or limit usage, but the schema describes the limit parameter. The main gap is the annotation contradiction, but that is penalized under behavioral transparency.

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 meaning beyond the schema by providing an example for type (e.g., sec_8k), clarifying since as ISO timestamp, and explaining the effect of mark_read on future calls. Schema coverage is 100%, but the extra context elevates it above the 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 retrieves fired events from the subscription feed, with specifics on return contents and filtering. It does not explicitly distinguish from sibling tools like recent_changes or list_subscriptions, but the resource is distinct enough that the purpose is 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 gives clear context for when to use the tool (retrieving recent alerts, polling) and even provides an alternative endpoint for scripts/dashboards. It lacks explicit exclusions or comparisons to other tools, but the usage context is well-defined.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the fan-out architecture across three sources, the GDELT→GNews fallback trigger, the PatentsView API sunset causing soft-failure, and the return structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs). This is rich behavioral context that annotations alone do not 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 dense but every sentence earns its place: it fronts with use cases, then explains the fan-out and fallbacks, date formats, return contract, and finally points to an alternative. No filler or repetition; the structure naturally guides the agent from intent to invocation.

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 (multi-source fan-out, fallback logic, soft-fail conditions, date parsing) and the absence of an output schema, the description covers all necessary behavioral and result details: sources, fallback triggers, soft-fail rationale, return shape (changes[], total_changes), and citation URIs. It also notes the parallel-call efficiency, making it complete for safe selection and invocation.

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

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

Although schema coverage is 100%, the description adds substantial parameter semantics: 'since' accepts ISO date or relative shorthand with examples ("7d", "3m") and a recommendation ("30d" or "1m"); 'value' is clarified with ticker or CIK examples; 'type' enum is explicitly narrowed to "company". These practical details go well 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 opens with concrete user intents ("What's new with X", "latest on Y") then states it is a "change feed for a company in the last N days/weeks/months in ONE parallel call." It names the specific sources (SEC EDGAR, GDELT→GNews, USPTO) and clearly distinguishes itself from the sibling tool entity_profile, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance with example queries and states that entity_profile should be used instead when a static profile is needed. It also explains fallback behavior (GDELT preferred, GNews when rate-limited, USPTO soft-fails) which informs the agent's decision-making.

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

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

Beyond annotations, the description discloses scoping by identifier, persistence differences (authenticated vs anonymous), and 24-hour retention for anonymous sessions. This adds context not shown in annotations.

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

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

The description is compact, front-loaded with the core action, and contains only relevant information. Each sentence contributes: definition, usage, scope, persistence, and sibling references.

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 two-parameter tool with no output schema, the description covers purpose, usage, behavioral traits, and interactions with related tools. It is complete for an agent to select and invoke correctly.

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

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

The schema already describes both parameters with examples. The description adds that the store is a key-value pair scoped by identifier, though it doesn't elaborate on key/value format beyond schema's existing coverage.

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

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

The description clearly states the tool saves data for later reuse via key-value pairs. It explicitly mentions 'Save data the agent will need to reuse later' and contrasts with siblings recall and forget, establishing a distinct purpose.

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

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

The description specifies when to use ('when you discover something worth carrying forward') and pairs with recall/forget for alternative actions, providing 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable nuance: 'LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return' and 'each call cascades through several lookup endpoints'. 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 front-loaded with examples and a clear purpose statement. Every sentence adds value, but it is somewhat verbose (e.g., the detailed explanation of output structure could be trimmed). Still well organized and not wasteful.

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

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

No output schema exists, so the description must cover return values. It does so by describing the identifier labels, unresolved field, and source attribution. It also covers edge cases (graceful degradation). Slightly more detail on the exact output structure would be ideal, but it is sufficient for an agent to understand the result.

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 goes far beyond the schema by detailing accepted inputs (ticker, CIK, ISIN, company name, brand/generic name), explaining output behavior (identifiers labelled with source, unresolved list, ISIN-to-LEI mapping), and the graceful degradation. This adds significant semantic richness.

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 like 'What's the ticker for…' and states 'resolve a user-spoken NAME to the canonical/official identifiers'. It clearly identifies the verb (resolve) and resource (names to identifiers). It distinguishes from siblings like compare_entities and entity_profile by focusing on the initial lookup step.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also provides example queries that trigger the tool. However, it does not explicitly mention when not to use it or directly compare to sibling tools, though the domain is sufficiently distinct.

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

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

The description adds valuable behavioral details beyond the annotations: it reveals the tool internally calls ai_visibility_check per entity, ranks by score, and returns a ranked list with score, confidence, and signal density. This explains observable behavior and output structure, making the tool's execution predictable.

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

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

The description is three sentences, each serving a purpose: stating the main function, explaining the mechanism, providing a use case, and specifying outputs. It is front-loaded, dense, and free of unnecessary wording.

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

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

Despite having no output schema, the description specifies the return format (ranked list with score, confidence, signal density). The annotation covers safety, and the schema fully documents parameters, so together they give a complete picture for invoking 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?

Since the schema descriptions cover 100% of parameters, the description doesn't need to add much. It reiterates the 'first entry as subject' concept already in the schema and introduces the brand-vs-competitor framing, but adds no new concrete 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 specifically states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks results. It distinguishes itself from the single-entity sibling ai_visibility_check by emphasizing side-by-side comparison and from generic compare_entities by focusing on 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 clearly gives a usage context ('competitive AI-marketing audits') and implies when to use it (comparing multiple entities' AI visibility). However, it doesn't explicitly name alternatives or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable behavioral context: fans out across two external services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. This goes well beyond annotations and does not contradict them.

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

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

The description is multi-sentence but information-dense: purpose, use case, return fields, ecosystem limitation, and failure behavior. Each sentence contributes unique value—no fluff. It is front-loaded with the main purpose and structured logically.

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

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

With no output schema, the description takes on the burden of explaining return shape and failure modes. It lists the summary block fields, per-advisory detail, links, alternative versions, and the sources_failed behavior. Combined with the parameter schema, an agent has everything needed to invoke and 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?

Input schema descriptions cover both parameters 100%, including that 'package' is an npm package name and that version defaults to latest. The description reinforces the same information without adding new meaning beyond the schema. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description opens with a clear composite-purpose statement: "should I add this npm package to my project" check in ONE call, and specifies the two data sources (deps.dev, bundlephobia). It also explicitly scopes to NPM ecosystem in v1, distinguishing it from any generic dependency tool and from sibling tools, which are unrelated research/Pipeworx 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?

Provides explicit trigger examples: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". Also gives a clear exclusion: "NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly." This is excellent when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the exact output format (passages with offsets and similarity scores), the embedding model (BGE-base-en), window size (500-char overlapping), and the 200K char truncation behavior with flagging. This is substantial behavioral detail that aids the agent in interpreting results.

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

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

Every sentence earns its place: definition, use case, tool pairing, and technical constraints. It's front-loaded with the core action and never wastes 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?

For a tool with a rich 3-param schema and no output schema, this description fully explains the return format, technical approach, and constraints (truncation). It even situates the tool in a workflow with ask_pipeworx_grounded, making it self-contained for a capable 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?

The schema already has 100% parameter coverage, so the baseline is 3. The description adds value by giving concrete examples for text (SEC 10-K body, article) and query ('supply-chain risk'), and it reinforces the 200K cap, which helps the agent form better inputs. This elevates it to 4.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' naming the verb, resource, and scope. It distinguishes itself from sibling tools like ask_pipeworx by emphasizing the fetched-record context and the 'top-N passages with character offsets' return.

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

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

It explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names a paired tool, ask_pipeworx_grounded, and explains the workflow of fetching with the gateway and grounding over relevant passages. This provides clear context and an alternative path.

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

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

Beyond the annotations, the description discloses important side effects and constraints: OAuth account requirement, inability of anonymous/BYO users to persist, phone verification and the 10/day SMS cap. It also states the delivery model (feed always on, optional email/SMS). Annotations are not contradicted.

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 purpose and key return value are front-loaded, and every part of the description carries useful information. However, it is a dense run-on with multiple semicolon-separated clauses and partially duplicates schema detail, keeping it from a perfect score.

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

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

For a tool with three parameters, nested objects, and no output schema, the description explains the return value, auth requirements, supported types, and delivery/retrieval behavior. The only omitted channel detail (webhook) is fully covered by the input schema, so the overall context is 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?

Input schema coverage is 100%, and the schema already documents type-specific params and delivery object semantics. The description repeats many of those examples (sec_8k, polymarket_edge, fred_series) but primarily adds account-level context rather than new parameter meaning, so it meets the baseline but does not substantially exceed it.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and explicitly notes it returns the new subscription id. This clearly distinguishes it from sibling tools such as list_subscriptions and unsubscribe.

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

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

It provides concrete context for when to use the tool, including an OAuth prerequisite ('anonymous + BYO cannot persist subscriptions') and supported event types. It also points to recent_alerts/GET registry.pipeworx.io/alerts.json as the pull mechanism for the always-on feed, but it does not explicitly name alternatives or exclusions beyond those.

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

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

Annotations already declare readOnly/openWorld/idempotent. The description adds valuable behavioral context: it returns category-bucketed example questions drawn from a live catalog of thousands of tools, and that each example includes the exact tool+argument shape. It also explains the effect of omitting `topic` (full spread). 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 appropriately sized for an onboarding tool, starting with example user questions, then the value proposition, return format, parameter usage, and explicit usage guidance. Every sentence contributes new information without redundancy or fluff.

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

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

Despite no output schema, the description thoroughly explains what the tool returns (category-bucketed example questions with tool+argument shapes), covers both invocation modes, and positions it within the sibling tool family by naming the meta-tools it teaches. It is complete for a read-only suggestion tool.

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

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

The schema already documents `topic` with a list of allowed values, so baseline is 3. The description adds meaningful behavior beyond the schema: passing `topic` focuses the results, while omitting it returns a cross-category spread, and it gives concrete examples ('finance', 'pharma', 'betting'). This enriches parameter understanding.

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

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

The description clearly states the tool is the onboarding entry point for answering 'what can I ask Pipeworx?', returning category-bucketed example questions with the exact tool and argument shape. This distinguishes it from siblings like discover_tools by positioning it as the first tool to use.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools' and gives concrete examples of when to pass `topic` versus call with no arguments. It names specific meta-tools (ask_pipeworx, entity_profile, compare_entities), providing clear context.

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

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

The description goes beyond annotations by disclosing ownership enforcement, deactivation rather than deletion, and preservation of historical events via recent_alerts. This adds meaningful behavioral context that complements the readOnlyHint and destructiveHint annotations 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?

Three concise sentences, front-loaded with the core action, and every sentence adds value: operation, ownership rule, and lifecycle behavior. No redundancy or filler.

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

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

For a single-parameter tool with rich annotations, the description is fully complete. It covers what the tool does, who can use it, the effect (deactivation), and how historical data is preserved, leaving no significant gaps.

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

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

Schema description coverage is 100%, with the id parameter already described as 'Subscription id (uuid) returned by subscribe.' The description repeats 'by id' but adds no new parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the unsubscribe operation, and adds ownership and deactivation details that clarify its scope.

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

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

The description implies usage context: to cancel a subscription you own. It mentions ownership enforcement as a prerequisite, but does not explicitly contrast with alternatives like 'use subscribe to create' or 'list_subscriptions to view'. Still, the context is clear and actionable.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description adds critical semantics: what 'could_not_verify' truly means (check did not happen) and warns not to present it as evidence. It also explains the routing behavior between structured and grounded pipelines, providing essential mental-model context.

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

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

The description is longer than average, but every sentence delivers high-value context: examples, routing logic, verdict semantics, and error handling. It is well-structured with a natural flow from usage to behavior, earning its length without being bloated.

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

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

For a tool with no output schema, the description thoroughly explains return values (verdicts, actual value, citation) and edge-case semantics (could_not_verify vs unsupported). It also covers the internal pipeline decision, making the tool's behavior fully predictable for an agent.

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

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

The schema already documents both parameters clearly, but the description adds guidance for tolerance_pct, explaining how to override it for hallucination detection. This supplements the schema rather than merely repeating it, making the parameter's purpose and tuning meaningful.

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

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

The description opens with explicit natural-language trigger phrases and clearly states the tool verifies factual claims against authoritative sources. It distinguishes itself from sibling tools by positioning claim verification as a single consolidated operation, replacing 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?

It states 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates the structured SEC path from the grounded pipeline. However, it does not explicitly list excluded scenarios or alternatives, so it stops short of full when-not-to-use guidance.

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