Monday

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true. The description adds valuable context beyond this: it reveals that probing Anthropic incurs direct cost to the user ('BYO key — you pay Anthropic directly'), clarifies the external API call, and details the per-model return structure. This is substantive behavioral disclosure.

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 (three sentences) and front-loaded with the core action. It covers purpose, key parameters, return format, and use cases without redundancy. 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 read-only probing tool with annotations covering safety, the description is nearly complete. It explicitly states the return structure (per-model fields + combined view), which compensates for the lack of an output schema. It could add a note about when to use alternatives like 'scan_competitor_ai_presence', but the core usage context is well covered.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by specifying the default model ('Workers AI Llama-3.3-70b') and explaining that `_apiKey` is for Anthropic with cost implications. This adds meaningful context for parameters, lifting the score above 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 a specific verb+resource: 'Probe one or more LLMs for what they know' and the output (visibility scores 0-100 per model). It also lists concrete use cases. However, it does not explicitly distinguish this tool from similar siblings like 'scan_competitor_ai_presence' or 'compare_entities'.

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

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

Provides clear usage context with 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional `_apiKey` and default model behavior. No exclusions or explicit 'use this instead of X' guidance are given, but the context is sufficient for most scenarios.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower. The description adds valuable behavioral depth: it routes to 5,529 tools across 1,455 sources, fills arguments, returns stable pipeworx:// citation URIs, and is a fast single call. 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 longer than typical but well-structured with front-loaded preference, examples, and escalation steps. Every sentence contributes value, though it could tighten redundancy (e.g., multiple examples of question phrases).

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

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

Given no output schema, the description covers return format (structured answer with citations), scope, use cases, and alternatives. It provides enough context for an agent to select and invoke the tool correctly in most scenarios.

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?

Schemas have 100% coverage for the 'question' param and aliases. The description reinforces natural-language usage but doesn't add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions with authoritative structured data and citations, using specific verbs like 'routes' and 'returns'. It distinguishes itself from siblings by explicit positioning as the default entry point and naming alternatives (ask_pipeworx_grounded, deep_research).

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and gives trigger phrases ('what is', 'look up', 'get the latest'), with examples. It also provides clear escalation paths: 'Step up only when needed' to ask_pipeworx_grounded or deep_research, and notes when it already covers breaking news.

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

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

Annotations already declare the tool as read-only and idempotent, and the description supplements this with crucial experimental context: candidate routing may be active, currently matches ask_pipeworx exactly, and it is a fully working router. It also discloses that behavior may vary when candidates are under test, going beyond annotation baselines.

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

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

The description is reasonably concise at ~70 words and front-loads the essential beta/identical framing. Each sentence adds specific value, though the 'Falls back to nothing' phrasing is slightly redundant with 'this IS a full working router.'

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 references 'same response shape' to anchor expectations. It also explains the tool's current behavior (no active candidate), how it relates to ask_pipeworx, and its experimental role, which is sufficient for a beta variant.

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 fully describes all 6 parameters (question plus five aliases) with 100% coverage, so the description need not compensate. The description only mentions 'same arguments' but adds no semantic detail 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 identifies the tool as the beta version of ask_pipeworx, a universal router with the same tools and arguments. It clearly distinguishes itself from the stable sibling by mentioning live candidate routing improvements and the lack of an active candidate, making its purpose and differentiation explicit.

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 to use it exactly like ask_pipeworx when wanting the newest routing, and that results are compared against the stable router. It provides clear context for experimental use but does not explicitly list when-not-to-use scenarios or alternative tools like ask_pipeworx_grounded.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description discloses the extra LLM call cost, the exact refusal reasons, and the fact that it only uses tool result content. No contradiction with annotations; it adds meaningful behavioral context for an 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 dense but well-structured, front-loading the core value proposition and then detailing returns, refusals, and cost tradeoff. Some specifics like '5,529 across 1455 sources' are slightly verbose but non-redundant. All sentences earn their 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?

This is a complex tool with no output schema, so the description carries the burden of explaining return format and failure modes. It provides a complete picture: success shape, refusal categories, use cases, and cost comparison—more than sufficient for an agent to decide 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?

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level semantics beyond what the schema already provides—it only restates that the question is in natural language. The aliases are already fully documented 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 begins with 'Hallucination-resistant answer mode for high-stakes reads' which is a specific verb+resource with a clear differentiator. It contrasts with sibling ask_pipeworx by emphasizing evidence extraction and explicit refusal, making the tool's unique role 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?

It gives explicit use cases: 'Use whenever an answer will be quoted, cited, or acted on...' and an explicit alternative: 'prefer ask_pipeworx for casual lookups.' This is textbook when/when-not guidance with a named 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?

The description is exceptionally transparent about tool behavior: it discloses resolver match confidence, low-confidence short-circuit behavior, closed-market status handling, illiquid wide-spread warnings, news fallback mechanics, and resolution-rule risk (e.g., refund_50_50). This goes far beyond the annotations, which only note readOnly/openWorld/idempotent/destructive hints.

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

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

Although long, the description is extremely well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and every sentence adds functional value. The first sentence front-loads the core purpose, and the length is justified by the tool's complexity and absence of an output schema.

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 compensates by documenting return shapes (result.market, result.analysis, result.evidence, result.parent_event), status codes, warning fields, and resolver-contract semantics. It also covers edge cases like closed markets, low-confidence matches, cancellation rules, and news fallback behavior, making the tool safely usable without an output 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%, so the baseline is 3. The description adds contextual fan-out examples and response shapes, but does not add meaning about the individual parameters beyond what the schema already states; e.g., the market parameter's slug/URL/question-text alternatives are already in the schema.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from sibling Polymarket tools by scoping it to bet-specific research, and explicitly lists usage intents like 'should I bet on X' and 'is there edge in Z'.

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 for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z''), and provides concrete examples of fan-out categories. It does not explicitly state when not to use it or name alternatives, but the use cases are clear enough to differentiate it from 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and output format (paired data + citation URIs). Contradicts no annotations.

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

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

The description is dense yet well-structured, front-loading the core purpose and usage before detailing behavior. Every sentence contributes valuable information without redundancy or filler, making it 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?

Given the two parameters, lack of output schema, and existing annotations, the description covers all essential context: what the tool does, when to use it, how it behaves, what data it returns, and performance benefits. It is fully sufficient 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?

The input schema already provides 100% coverage with descriptions for both parameters. The description adds meaningful semantics for the 'type' parameter by detailing what metrics each entity type pulls (e.g., company: revenue/net income; drug: adverse-event counts), which enhances the agent's ability to choose correct values.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, with explicit trigger examples ('X vs Y', 'rank these companies'). It distinguishes this from single-entity lookups, making the purpose specific and unambiguous.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8–15 sequential lookups. This clearly tells when to use this tool and implies the alternative approach.

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, but the description adds substantial behavioral context: account/paywall requirements, latency (15-60s, up to ~90s), the gaps[] and contradictions[] fields, semantic excerpting of large records, citation resolvability, and the explicit 'never invented' guarantee. This far exceeds 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 lengthy but densely packed with essential caveats and behavioral details. It is front-loaded with the most critical constraint (account required, fallback to ask_pipeworx). While a few details could be trimmed (e.g., the enumeration of source types), every sentence adds value for such a complex tool.

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

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

With no output schema, the description goes beyond the minimum by detailing the return format: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers limitations (structured-only, empty gaps for current news) and operational expectations (latency, hops). This is complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters already described. The description adds meaning beyond the schema by explaining the depth parameter's facet counts and hop behavior ('quick=3... standard=5... thorough=8'), and by clarifying that the question can be broad/multi-part because decomposition is the point. This enriches the schema's descriptions.

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

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

The description uses a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with 'NOT open-web search'. It also differentiates from siblings like ask_pipeworx by describing its decomposition and parallel routing capabilities. This makes the tool's unique role clear.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and clearly states alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains depth levels and their appropriate use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral context by explaining the output: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations and clarifies the tool's operation and output format.

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

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

The description is front-loaded with the core purpose and then provides supporting details. The long list of domains is somewhat verbose but relevant for discovery. Each sentence contributes value, though the domain enumeration could be trimmed without losing clarity.

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

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

Given that there is no output schema, the description adequately explains the return format (top-N tools with names, descriptions, and schemas) and the intended use case. It covers what the tool returns and when to use it, making it complete for a meta-tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the semantics by stating 'by describing the data or task' and gives examples in the schema. However, it does not clarify the alias/required distinction or add significant new parameter meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find/discover), and lists the domains covered. This distinguishes it from sibling tools that perform specific tasks rather than meta-search.

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

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

The description gives explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides a clear directive but does not name specific alternative tools or provide when-not-to-use conditions, which prevents 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?

The description goes well beyond the annotations by detailing the tool's internal fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF, and specifying exactly which data fields are returned. It also discloses important caveats like the USPTO API sunset with soft-fail behavior and the GDELT→GNews fallback, providing deep behavioral transparency.

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

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

The description is lengthy but every segment carries useful information: example intents, the core promise, fan-out details, return fields, and constraints. It is front-loaded with the main use case and structured with semicolons to separate distinct return categories. Slightly dense, but not wasteful; no filler.

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

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

Given there is no output schema, the description thoroughly explains what the tool returns (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and notes limitations (US public companies only, no names). It also covers edge conditions like the USPTO sunset, making it highly complete for an agent to set expectations.

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

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

The schema already covers both parameters fully (type enum and value format). The description reinforces with concrete examples ('AAPL', '0000320193') and reiterates that names are not supported, adding practical clarity beyond the schema's definitions. It does not introduce entirely new semantics but improves usability.

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: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example user intents ('Tell me about X', 'research Acme') and distinguishes itself from sibling tools by noting it should be preferred over chaining single-pack lookups and that names require resolve_entity first.

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

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

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states what inputs are not supported ('names not supported') and names the alternative tool ('use resolve_entity first'), making the when-to-use/not-use decision clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description's action 'Delete' aligns with these. The note about clearing sensitive data adds a use case but not a new behavioral trait. No contradiction, but the description adds minimal context beyond what annotations already 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 two sentences, front-loaded with the core action, and every clause serves a purpose. No filler or redundancy.

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

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

For a single-parameter tool with clear annotations and a comprehensive schema, the description fully equips the agent to select and invoke the tool. It covers purpose, usage, and pairing with related tools, and the output schema absence is fine for a delete operation.

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

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

The schema description coverage is 100%: the only parameter 'key' is fully described as 'Memory key to delete'. The tool description's 'by key' adds no additional semantic value beyond the schema.

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

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

The description uses a specific verb+resource construction: 'Delete a previously stored memory by key.' This clearly states the action and target, and distinguishes it from sibling tools like 'remember' (create) and 'recall' (read).

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

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

The description explicitly provides when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names companion tools ('Pair with remember and recall'), giving clear context for selection against alternatives.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds valuable process detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob ready to drop at site-root/llms.txt.' This goes beyond the annotations by explaining the network fetch and output format.

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 economical. It opens with the core purpose, explains the process, and closes with useful scenarios. Every sentence adds value; there is no fluff or redundancy.

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

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

Despite having no output schema, the description explains the return value ('single text blob') and the standard format. The tool is simple (2 params, no nested objects), and the description covers the process, output, and use cases. No critical information is missing.

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

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

Schema coverage is 100%, so both parameters (url and max_links) have descriptions in the schema. The tool description does not add significant meaning beyond the schema, only restating that it works for 'any URL' and mentioning max links by implication. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL'. The verb 'Generate' and resource 'llms.txt' are specific, and it explains the process (fetches, extracts, emits). However, it does not explicitly distinguish itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence, so it stops short of a 5.

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

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

The description provides explicit 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.' This gives clear context for when to use the tool, but it does not mention when not to use it or name alternative tools, so it's 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations, such as returning specific fields (id, type, params, created_at, last_fired_at, fire_count) and the scope ("caller's"), which helps the agent understand what to expect from the response.

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 only two sentences, front-loaded with the core action, and every clause earns its place. It lists return fields and gives practical usage guidance without any fluff 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?

This is a simple read-only list tool with one optional parameter and no output schema. The description covers the return fields, which is essential because there is no output schema, and provides usage context. It does not mention the include_inactive parameter, but the schema already fully documents that, so the description is sufficiently complete for the tool's simplicity.

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 documented in the input schema with a clear description and default behavior. The tool description does not add any parameter-specific details, but with 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description starts with a specific verb and resource: "List the caller's active subscriptions." It clearly distinguishes this from sibling tools like subscribe and unsubscribe, and enumerates the exact return fields, making the tool's purpose unambiguous.

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

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

The description 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 gives clear situational guidance, though it does not name alternative tools (e.g., subscribe/unsubscribe) by name, stopping short of a full 5.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds value by stating the return behavior (created item ID and name) and provides an example with optional column_values, which goes beyond the schema. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence that states the action, gives an example, and mentions the return value. Every part earns its place with no superfluous 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?

Given the detailed schema, annotations, and existence of an output schema, the description sufficiently covers the tool's purpose and return value. It could mention prerequisites or error handling, but for a create operation with full schema documentation, it is adequate.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds a small example (board ID '12345') but no additional parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool creates a new item in a board, with a concrete example (board ID '12345', name 'New Task'). This verb+resource combination distinguishes it from sibling read/search tools like monday_list_items and monday_search_items.

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 context is clear: this tool is for creating a new item. It does not explicitly mention alternatives or when not to use it, but the action inherently differentiates it from sibling list/get/search tools. No exclusions are stated, but the purpose is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying exactly what data is returned (name, columns, groups, item count), which is behavioral context beyond the annotations. There is no contradiction.

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

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

The description is a single, front-loaded sentence that immediately states the tool's purpose and a key example. Every word contributes to understanding, with no fluff or repetition. It is appropriately concise for a simple two-parameter tool.

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

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

Given the tool's low complexity (2 required parameters, no nested objects), the description is complete. It covers the purpose, provides a concrete usage example, and mentions the nature of the return value, while the existing output schema handles detailed return structure. No critical information is missing.

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

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

Schema description coverage is 100%: both _apiKey and board_id are documented in the input schema. The description adds a concrete example ('board ID 12345') but does not provide additional meaning beyond the schema. Baseline 3 is appropriate since the schema handles parameter documentation.

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

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

The description clearly states the action ('Get board structure and metadata'), identifies the resource (Monday board), and gives a concrete example (board ID '12345'). It also lists the return contents (name, columns, groups, item count), which distinguishes it from sibling tools like monday_list_boards (which lists boards) and monday_list_items (which lists items).

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 when you need board structure/metadata, but it provides no explicit guidance about when to use this tool versus alternatives. It does not mention exclusions, such as 'use monday_list_boards for board enumeration' or 'use monday_search_items for item-level queries'. The context of sibling tools is present but the description itself does not offer comparative 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 value by disclosing the returned fields, helping agents anticipate the response shape. It does not contradict 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 concise sentence that front-loads the main action and adds useful return-field details. No filler words or redundant information.

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

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

For a simple list tool with full schema coverage, an output schema, and strong annotations, the description covers purpose, returns, and context. The only minor gap is that 'all boards' is technically constrained by the limit parameter, but the schema clarifies this, so it's not a significant omission.

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 both _apiKey and limit fully described. The description adds no parameter-specific guidance, but none is needed given the schema's completeness, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists boards and specifies the return fields (board ID, name, state, item count), distinguishing it from siblings like monday_get_board that target specific boards. The phrase 'to discover available boards' reinforces its discovery 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 implies usage for discovering available boards, providing a clear context. However, it does not explicitly mention alternatives or when not to use this tool, so it lacks explicit exclusions. The context is still sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by specifying the return fields (item ID, name, group, column values, created date), which goes beyond the annotations and helps set expectations. No contradictions with annotations.

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

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

The description is a single, front-loaded sentence that immediately states the action, gives an example, and lists return fields. Every word earns its place; no waste or redundancy.

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

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

For a simple read-only list tool with an output schema and rich annotations, the description is sufficient. It covers the core functionality and return values, though it omits details like pagination or default limit, which are documented in the schema. The presence of an output schema reduces the need to explain return values further.

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 fully documents all three parameters. The description adds a minor example (board ID '12345') and hints at the board_id parameter but does not explain limit or _apiKey beyond what the schema provides. This meets the baseline for 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 uses a specific verb-resource pair ('List items in a board') and includes a concrete example (board ID '12345'), making its purpose unmistakable. It also clearly distinguishes from sibling tools like monday_list_boards (which lists boards) and monday_search_items (which searches).

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 (when you need items from a specific board) but does not explicitly state when to use this tool versus alternatives like monday_search_items or monday_get_board. No exclusions or alternative guidance is provided, though the board-focused wording provides some implied 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 establish read-only and non-destructive behavior, so the bar for additional transparency is lower. The description adds context about the search scope ('across all boards') and return fields (ID, name, board name, column values), which goes beyond the annotation safety profile.

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

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

The description is two sentences, zero waste, and front-loaded with the primary action. It efficiently conveys scope and return information without unnecessary detail.

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 an output schema present and strong annotations, the description covers the essential behavior for a simple read-only search tool. It could mention ordering, matching logic, or pagination behavior, but those are not critical given the structured context.

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

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

Schema coverage is 100% with descriptive parameter text for query, limit, and _apiKey. The tool description adds no additional parameter-level detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb 'Search' and a clear resource 'items across all boards' with a keyword scope. This distinguishes it from sibling tools like monday_list_items, which likely operate within a single board rather than across all boards.

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 indicates this tool is for cross-board keyword searches, implying when to use it over other monday tools. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5.

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

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

Beyond the all-false annotations (which give no safety hints), the description discloses important behavioral details: filing returns a claim_token that can be reused to read resolution status, rate-limit of 5 per identifier per day, and that it is free and does not count against tool-call quota. It also notes that the team reads digests daily and that feedback affects roadmap, setting expectations for response.

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 provides essential guidance: purpose, use cases, scope restriction, content instructions, token flow, rate limit, and cost. It is front-loaded with the main purpose and structured logically. The length is justified by the multiple caveats the user must know, though a slightly tighter edit could still be made.

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

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

Given the tool's moderate complexity (4 params, nested object, no output schema), the description covers all necessary operational aspects: what to report, what not to report, how to follow up, rate limits, and cost. It even explains what happens when filing without an account. No critical information is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter semantics beyond the schema. It explains the claim_token lifecycle (filing without an account returns it, and passing it back later reads the status), clarifies the 'type' values with practical examples, and specifies that claim_token should be used with no other arguments. This 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 identifies the tool as a channel to send feedback to the Pipeworx team, with specific verbs ('Tell', 'report') and a well-defined resource. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on reporting issues, missing features, or praise rather than querying information.

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 (bug, feature/data_gap, praise) and an explicit when-not-to-use exclusion (for tools from other MCP servers), even telling the user to file with that server instead. It also includes practical advice on how to describe the issue in terms of Pipeworx tools and not to paste end-user prompts.

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 behavior. The description adds context about data provenance ('derived from CF analytics-engine'), privacy ('no PII'), and caching ('Cached 5min-1h depending on window'). 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?

Four sentences efficiently cover purpose, output, use cases, and data characteristics. The numbered use cases improve scannability without unnecessary 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?

For a simple read-only tool with one optional parameter and no output schema, the description fully explains what is returned, the use cases, and the underlying data source. Enough for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% and the parameter description already explains the meaning of each window option. The description adds only tangential information about cache timing, not deeper 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 states 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)' with a clear verb and resource. It distinguishes itself from siblings like discover_tools by focusing specifically on current agent call activity.

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

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

Lists three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. Provides clear context but does not explicitly name alternative tools or when-not-to-use scenarios.

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

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

Annotations already note readOnly, openWorld, idempotent, non-destructive. The description goes well beyond by explaining internal filters (SEMANTIC ANCHOR, PARTITION FILTER), response details, and the FILL CHECK behavior including the critical warning that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' This is rich behavioral transparency.

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

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

Despite being long, every sentence earns its place. The structure is logical: main purpose, mode selection, semantic anchors, partition filter, response format, fill check, and pointer to related tool. It is front-loaded and highly information-dense 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 tool's complexity (three modes, filters, response schema, fill-check behavior) and no output schema, the description is exceptionally complete. It explains return fields, edge cases (e.g., placeholders, low similarity), and practical usage constraints, making it sufficient 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% with parameter descriptions, but the tool description adds substantial semantic depth: event slugs with examples, full URL acceptance, topic seed questions, and how each mode behaves differently. This goes far beyond the schema's basic descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk by emphasizing arbitrage detection.

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, actionable guidance: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also recommends the event mode for specific markets and points to polymarket_fill_risk for custom sizing, demonstrating clear when-to-use 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?

Annotations only declare readOnly/idempotent/openWorld, so the description carries the burden of explaining behavior—and it does so thoroughly. It discloses response top-level keys, per-opportunity fields (edge_pp_net, kelly_fraction), the 24h-move warning, the parent-level Kelly=0 design for partition_overround, diagnostics funnel counters, and KV caching. 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 densely packed with unique, purposeful information. It is structured with capitalized labels (MODEL_DRIVEN, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) that aid parsing. While some sections are verbose, every sentence adds value; it is not padded with 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?

With no output schema, the description must explain the return structure—and it does: by_segment, fed_candidates/fed_note, _diagnostics, and field-level details. It also covers behavioral caveats (Fed signal unreliability), caching semantics, and parameter effects. For a complex 9-parameter read-only tool, this is complete and self-contained.

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 valuable cross-parameter interactions: it explains min_kelly does not filter partition arbs (since parent kelly is 0) and that min_partition_leg_kelly applies per-leg inside top_legs. It also contextualizes slippage_pp as a net-of-slippage adjustment and describes the tradeable-edge knobs in prose, going 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 opens with a specific verb+resource+output: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly positions itself for 'what should I bet on today' and outlines three distinct response segments, which distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker even without naming them.

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

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

The description provides a clear use case ('Built for "what should I bet on today"') and explains how knobs like min_liquidity/max_spread_pp filter out non-tradeable opportunities. It lacks explicit 'when not to use' or direct alternative comparisons, but the unique discovery purpose and detailed filter semantics give strong contextual guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond these: the 60-day snapshot TTL, the meaning of snapshot gaps, that decay is computed on daily closes of edge_pp_net rather than intraday, the signed nature of edge_pp_net, and the semantics of expired opportunities. This significantly exceeds the annotation baseline.

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

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

Although lengthy, the description is well-structured with clear labels (Args, RESPONSE, LIMITS) and front-loaded purpose. Every section provides necessary details for correct invocation and interpretation, and even the parenthetical about why an old wide edge matters helps the agent understand the tool's value. No wasted words are present.

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

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

The tool has no output schema, so the description takes on the full burden of describing the response. It does so thoroughly, covering tracked[], expired[], snapshot_dates[], the meaning of edge_pp_net signed values, and computation limitations. It also addresses history depth and data gaps, making the description complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds only minor semantic details, such as 'snapshot family' for window and 'max 30' for days, which are slightly more explicit than the schema's 'clamp 2-30'. This meets the baseline for high schema coverage but does not add substantial meaning beyond 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 a specific verb phrase, 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' and explicitly states the question it answers: 'how long has this edge existed and is it shrinking?'. This clearly differentiates it from the sibling polymarket_edges tool, which presumably focuses on current edges, by emphasizing historical persistence and decay.

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 conveys a clear use case: evaluating whether an edge is fresh or old and whether it is decaying, with the illustrative contrast between 'a fresh wide edge and a 3-week-old wide edge'. It also provides context about snapshot gaps and TTL limits, but it does not explicitly name the alternative tool for current-edge data, so it falls just short of explicit when/when-not guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description extensively discloses behavior: how it walks the order book, what it returns (top_of_book, vwap_fill_price, slippage_pp, etc.), edge cases like partial fills converting an arb into unhedged directional risk, and the meaning of forced_directional_risk. This is a comprehensive behavioral disclosure.

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 is information-dense and necessary for a tool with two modes and multiple return fields. It is front-loaded with the core concept, though the extensive parentheticals and run-on sentences slightly reduce scannability. It earns its space but could be better structured with bullet points or clearer separation of modes.

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 still lists all return fields for both modes, explains the verdict values (clean|degraded|cannot_fill), and highlights risk factors (thin_legs, forced_directional_risk). It also provides context on when to use the tool relative to other arbitrage tools, making it fully self-contained for an AI agent.

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

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

Although schema coverage is 100%, the description adds significant meaning by explaining how size_usd is interpreted differently in single-market vs basket modes (max spend vs settlement notional), the default side behavior in basket mode, and the requirement for one of market or event. It also clarifies clamp ranges and per-leg semantics, exceeding basic schema info.

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

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

The description clearly identifies the tool as a fill-risk check against live CLOB order-book depth, with explicit modes (single-market and basket). It distinguishes itself from siblings by naming specific use cases (polymarket_arbitrage and polymarket_edges) and describing the unique value (realizable-vs-theoretical edge check).

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when to use single-market vs basket mode, and warns about theoretical overround on thin books, making the intended context very clear.

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

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

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral context: it discloses the compatibility_warning conditions, temporal_alignment implications, skipped_cross_type/subtype counters, and the caution that most pre-mapped topics return warnings. This far exceeds what annotations provide and gives a clear picture of the tool's limitations and edge cases.

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 tightly structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value: purpose, caveat, mode definitions, response format, safety fields, temporal alignment, skip counters, and final warning. No filler or redundancy.

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

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

Despite no output schema, the description explains return values (leg-by-leg prices, spread in pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and how to interpret them. It gives examples of explicit inputs. This is a complete explanation for a complex tool with edge cases.

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 parameters significantly: it explains the topic shortcut list, what auto-fetching does, that explicit tickers/slugs override the topic-mapped side, and how the two modes interact. This is far beyond the schema's basic descriptions and clarifies usage patterns.

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

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

The description clearly identifies the tool as providing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by focusing on cross-venue comparison and explicitly stating the safety logic around equivalent bet shapes. The two modes and response summary reinforce a specific, actionable 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 explains when to use each mode (topic shortcuts vs explicit tickers/slugs) and provides strong when-not guidance: pre-mapped ≠ tradeable, and compatibility_warning indicates non-equivalent bet shapes or unrelated events. It does not, however, name alternative tools or explicitly state 'use this instead of X', so it stops short of full alternatives.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation, and the description adds valuable context about the memory being 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID),' which is not conveyed by the annotations. It also clarifies the relationship to remember and forget. 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 three focused sentences. The first sentence states the core functionality, the second gives concrete usage examples, and the third explains scope and paired tools. Every sentence contributes meaning; there is no repetition 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 tool with one optional parameter, rich annotations, and no output schema, the description adequately covers purpose, usage, scope, and related tools. It could mention what happens when a key isn't found or the exact return format, but this is not essential given the simplicity and available annotations.

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

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

The single key parameter is fully documented in the schema ('Memory key to retrieve (omit to list all keys)'), and the description repeats this information without adding new semantics. With 100% schema coverage, the description provides no additional parameter-level insight beyond what the schema already states.

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-resource pair: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly states the action and scope, and explicitly distinguishes the tool from siblings by naming remember and forget.

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

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

The description gives concrete use cases ('the user's target ticker, an address, prior research notes') and explains when to use it: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also points to remember and forget as paired tools, providing clear context, though it doesn't explicitly list exclusion criteria.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds important context: mark_read:true flags events as read and changes future call results. It also discloses the return payload fields and the poll-friendly nature. This goes beyond the structured 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?

Three sentences, each carrying distinct information: the action, the response contents, and additional options/alternatives. No redundant or filler 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?

With no output schema, the description compensates by naming the returned fields (source, citation_uri, raw payload) and explaining mark_read behavior. It does not detail pagination beyond limit, but that is covered by the schema. The external endpoint mention also rounds out the 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 covers 100% of parameters, so baseline is 3. The description adds value by giving a concrete type example ('sec_8k'), clarifying since as ISO timestamp, and explaining the effect of mark_read on subsequent calls. This goes beyond the bare parameter descriptions.

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

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

The description starts with 'Pull fired events from your subscription feed', which clearly identifies the verb and resource. It adds that it returns the most recent alerts written by the evaluator, which distinguishes it from sibling tools like list_subscriptions and subscribe.

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 says 'Polls work fine' and points to an alternative HTTP endpoint for scripts/dashboards, giving practical context. However, it does not explicitly contrast with other PipeWorx tools or state when-not-to-use it, only offering an external 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?

The description discloses nuanced behavior beyond the annotations: source precedence (GDELT preferred, GNews fallback on rate-limit/5xx), the USPTO PatentsView sunset causing soft-fail, and the output shape (changes[] grouped by source, total_changes, pipeworx URIs). This is substantial operational detail.

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

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

The description is dense but every sentence earns its place: example phrasings, source breakdown, failure modes, date syntax, output structure, and cross-reference. It is front-loaded with user-oriented query patterns and remains highly readable despite its length.

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

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

Given the tool's complexity (multiple datasources, fallback logic, flexible date parsing, structured output) and lack of an output schema, the description covers all necessary context: input semantics, expected return value, and failure/limitation behavior. No critical gaps remain.

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

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

While the schema already covers all parameters, the description adds critical semantics: `since` accepts ISO dates or relative shorthand with examples, and recommends '30d' or '1m' for typical monitoring. It also clarifies `value` formats (ticker or zero-padded CIK). This exceeds schema information.

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

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

The description clearly identifies the tool as a 'change feed for a company in the last N days/weeks/months' with concrete example queries. It enumerates the fan-out sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes itself from entity_profile, making its scope 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 guidance on when to use this tool ('What's new with X' / 'latest on Y' etc.) and when to choose an alternative ('Use entity_profile instead when you want the static profile'). This directly addresses the decision boundary.

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 write intent (readOnlyHint false) and idempotency. The description adds valuable context on storage scope (key-value scoped by identifier) and retention policies (persistent for authenticated users, 24 hours for anonymous). No contradiction with annotations.

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

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

Three sentences front-loaded with the core action, followed by usage and storage details. No wasted words; each sentence earns its place.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence, and companion tools. It provides enough context for an agent to decide when and how to use it.

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

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

Schema covers 100% of parameters with descriptive examples. The description adds minimal parameter-specific meaning beyond 'key-value pair', so 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 saves data for later reuse, with specific examples of what to store (ticker, address, preference). It distinguishes from siblings recall and forget by naming them as companions, not duplicating their function.

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

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

Provides explicit 'Use when' guidance with concrete scenarios (resolved ticker, target address, user preference). It also points to complementary tools (recall, forget). Lacks explicit 'when not to use' exclusions, but the guidance is strong.

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

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

Annotations already declare readOnly=true and idempotent, but the description adds crucial behavior: unresolved identifiers are explicitly stated, LEI/FIGI enrichment degrades gracefully, and internal cascading lookups occur. These details go beyond the annotations and help the agent anticipate fault tolerance and output completeness.

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

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

While long, the description is front-loaded with intuitive examples and structured by entity type, with graceful-degradation notes at the end. Every sentence carries useful information, though the opening example list could be trimmed without loss.

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 describes return data for both company and drug types, including source labels, unresolved placeholders, and fallback behavior. This makes the tool predictable and complete for a complex resolution tool.

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

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

The input schema has 100% coverage, with descriptions for both 'type' and 'value' including examples. The description adds no new parameter syntax or format details, as the schema already documents accepted inputs (ticker, CIK, name, brand/generic). Thus the description provides minimal additional 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 explicitly states it resolves user-spoken names to canonical/official identifiers, with concrete query examples and supported entity types. It clearly differentiates from sibling tools like entity_profile or compare_entities by focusing on ID resolution as a prerequisite 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?

It instructs 'Use FIRST whenever you have a name but need an ID', giving explicit when-to-use guidance. It also notes that a single call replaces 2-3 manual lookups, implying it consolidates steps. It doesn't explicitly exclude scenarios, but the guidance is sufficient for selection among siblings.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds value by revealing that it internally probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. 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?

Two sentences: the first states purpose and process, the second gives use case and return value. Every sentence earns its place with no wasted words.

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

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

Although there is no output schema, the description discloses the return format (ranked list with score, confidence, signal density) and names the underlying probe tool. It provides enough context for an agent to understand expected behavior, though rate limits or call structure are not detailed.

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 descriptions cover 100% of parameters, including the entities' first-entry-as-subject rule and model/API key requirements. The description adds no additional parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, specifying the process of probing each entity with ai_visibility_check, ranking by score, and surfacing most/least recognized. This distinguishes it from sibling ai_visibility_check, which likely handles a single entity.

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 a specific use case (competitive AI-marketing audits) with an example query. Implies this is the multi-entity alternative to ai_visibility_check, but does not explicitly exclude single-entity use or address other sibling tools like compare_entities.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds behavioral context beyond that: it fans out across two services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s, with sources_failed listing timeouts. It also specifies what is returned, which is critical when there is no output schema.

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

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

The description is information-dense but efficiently structured: core purpose, use case, return details, ecosystem limitation, and failure behavior. Every sentence contributes value, and it opens with the exact question the tool answers, making it scannable for an agent.

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

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

Without an output schema, the description must enumerate return values, which it does: summary block fields, per-advisory detail, links, alternative versions. It also covers edge cases like slow first measurement, partial failure, and ecosystem scope, making the description self-sufficient for a composite tool with moderate complexity.

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

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

The input schema already provides 100% coverage with descriptions for both package and version parameters, including the default behavior for omitted version. The tool description does not add further parameter-level semantics beyond what the schema states, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific composite check for npm packages, naming the exact sources (deps.dev, bundlephobia) and the question it answers (should I add this package). It distinguishes from siblings by explicitly limiting to NPM ecosystem and pointing to deps.dev:version for other ecosystems.

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: 'Use whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also gives an exclusion/alternative for non-NPM packages (PyPI/Maven/Cargo/Go fall under deps.dev:version directly).

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds substantial behavioral context beyond those: the 200K character cap with truncation flagging, BGE-base-en embeddings, 500-char overlapping windows, and character offsets for quote verification. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and immediately gives usage context. It is slightly wordy with some redundancy ('returns only the passages that matter' vs 'top-N passages'), but every major point (cap, offsets, pairing) is valuable and the structure is logical.

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

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

With no output schema, the description fully explains the return format (passages with character offsets and similarity scores), edge-case behavior (200K truncation flagged), and the integration with ask_pipeworx_grounded. It is complete for a semantically-scoped search tool with good annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the semantics with examples ('supply-chain risk') and repeats the 200K cap, but does not materially add meaning beyond the schema's own parameter descriptions. It does clarify that limit controls 'top-N passages', which the schema already states.

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+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes itself from siblings like ask_pipeworx_grounded by emphasizing searching within already-fetched text rather than the whole document, and mentions pairing with that sibling to clarify the workflow.

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

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

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt' directly states when to use it. It also names an alternative, ask_pipeworx_grounded, and explains the intended pairing, giving clear context and exclusions.

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

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

The description discloses critical behavioral details beyond the annotations: OAuth account requirement, inability for anonymous/BYO accounts to persist subscriptions, SMS phone verification, 10/day SMS cap, webhook auto-disable after 10 failures, and one-time signing secret delivery. This fully informs the agent of side effects and prerequisites.

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

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

The description is dense but well-organized, leading with the core purpose and then layering type and delivery details. It is longer than typical, but every sentence carries operational information; minor redundancy with the schema's delivery object prevents a 5.

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

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

Given the tool's complexity (multiple subscription types, delivery channels, verification prerequisites), the description covers purpose, auth, return value, per-type parameters, and delivery caveats comprehensively. The absence of an output schema is mitigated by the explicit statement about returning the subscription id.

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

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

Even though the schema covers all parameters, the description adds significant semantic value with type-specific examples like items:["5.02"] = officer change and params:{topic:"fed"}. It also clarifies required sub-fields (e.g., clinical_trial requires sponsor or condition) and SMS delivery constraints, going well beyond the schema's descriptions.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' a specific verb+resource statement that clearly distinguishes this from sibling tools like list_subscriptions, recent_alerts, and unsubscribe. It also states the return value (new subscription id), cementing its purpose.

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

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

The description provides rich context on when to use the tool by enumerating supported subscription types (sec_8k, polymarket_edge, fred_series) with concrete examples, and explains delivery channel options. It does not explicitly call out alternative tools for viewing or canceling subscriptions, but the purpose is clear enough that an agent can infer appropriate usage.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: output is category-bucketed examples tied to the live catalog, and behavior varies based on whether topic is provided. 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 dense but every element earns its place: query variants, output structure, category list, argument behavior, and usage timing. It is longer than a minimal description but appropriate for an onboarding tool that needs to teach the agent what it can do.

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 and no output schema, the description fully covers purpose, output characteristics, argument semantics, and when to use it. The agent can correctly select and invoke this tool based on the description alone.

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

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

Schema coverage is 100% and the one optional parameter is already well-described. The description repeats the topic examples but adds no new constraints or syntax details, 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 this is the onboarding entry point that returns categorized example questions with the exact tool and argument shape that answers them. It distinguishes itself from siblings by prescribing to 'Use this FIRST' when the agent does not know Pipeworx capabilities.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools') and explains no-arg vs topic-focused invocation. It stops short of naming alternatives or explicit when-not-to-use conditions, but the context is clear.

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

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

Beyond the annotations, the description discloses that the row is deactivated rather than deleted, and explains the consequence ('historical events stay available via recent_alerts'). It also enforces ownership semantics. These traits are not captured in the annotations and significantly enhance understanding of the tool's side effects.

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 compact sentences deliver all essential information: the action, the ownership constraint, the soft-delete behavior, and the link to recent_alerts. No redundant words, and the key message 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 simple one-parameter mutation tool with no output schema, the description fully covers the behavioral outcome, the ownership restriction, persistence semantics, and integration with recent_alerts. It is complete for the tool's complexity.

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

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

The schema provides 100% coverage for the single 'id' parameter, including its format (uuid) and origin (returned by subscribe). The description adds no extra parameter detail beyond restating 'by id', 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 uses the specific verb 'Cancel' and clearly identifies the resource ('a subscription by id'), distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. It also states ownership scope ('your own subscriptions'), making the tool's purpose unambiguous.

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

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

The description provides clear context for when to use the tool (to cancel a subscription) and important constraints (ownership, deactivation behavior). It does not explicitly name alternatives or exclusion criteria, but the ownership enforcement and mention of recent_alerts implicitly guide appropriate usage. Lacks explicit when-not-to-use guidance, so a 4.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds valuable behavioral context: it enumerates possible verdicts, explains the difference between could_not_verify (indicating a failed check with verification_error, not evidence) and unsupported (no source covers it), and describes the output components (actual value, pipeworx:// citation, reasoning). This deeply informs the agent of failure modes and return semantics, going well beyond the annotated safety profile.

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

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

The description is long but justifiably so—each sentence serves a purpose, from lead-in examples to the critical 'IMPORTANT for callers' warning. It is well-structured with a clear flow. It could be slightly tightened but is overall efficient for the tool's complexity.

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

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

Given the tool's complexity (dual pipelines, tolerance math, verdict enumeration, error semantics), the description is thorough. It covers the return format, failure distinctions, and applicability, leaving no major gaps. Even without an output schema, an agent has enough to correctly interpret and act on results.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description does not add any additional explanation of claim or tolerance_pct beyond what the schema already provides; it only mentions "exact percent-delta math" indirectly. Thus it meets the minimum viable standard but doesn't enhance 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 identifies the tool as a natural-language claim verification tool against authoritative sources, with specific verbs like "fact check" and "verify the claim that." It distinguishes itself from siblings by describing the two pipelines (SEC EDGAR for financial, grounded for non-financial) and explicitly noting it replaces 4–6 sequential calls, setting it apart from generic Q&A tools like ask_pipeworx.

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

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

The description explicitly states "Use whenever the agent needs to check whether something a user said is factually correct," providing clear usage context. It also gives guidance on the two internal pathways (financial vs. non-financial). However, it doesn't explicitly exclude alternative tools for non-claim queries, so it's clear but not exhaustive on when NOT to use this tool.

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