Linkedin Humblebrag

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the bar is lower. The description adds valuable context beyond annotations: default model is Workers AI Llama-3.3-70b (free), and passing _apiKey to probe Anthropic means the user pays directly. It also discloses the return structure.

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

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

The description is three sentences, front-loaded with the core purpose, then default behavior and return format, and ends with use cases. Each sentence earns its place; no redundant or vague 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 good annotations and full schema coverage, the description completes the picture by specifying the return shape (per-model {score, confidence, signals, raw_response} + combined view) and cost implications. It lacks explicit exclusions or edge-case notes, but these are not critical for this simple read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by connecting models and _apiKey ('pass _apiKey to also probe Anthropic') and clarifying the cost relationship ('BYO key — you pay Anthropic directly'). This integrates parameters into usage context.

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

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

The description clearly states the tool probes one or more LLMs and scores visibility 0-100, with a specific verb ('Probe') and output format. It distinguishes itself from siblings like ask_pipeworx (which asks questions) and scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternatives or exclusions, 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 state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations: it returns 'structured answer with stable pipeworx:// citation URIs,' routes across many sources, and is described as 'one fast call' that 'works on every tier.' No contradictions exist.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and is well organized, but it is somewhat wordy with repeated encouragements such as 'START HERE' and 'default entry point.' Still, every sentence provides useful context, so it earns a 4.

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, no output schema, and rich annotations, the description is highly complete. It explains the return format (structured answer with citation URIs), performance ('one fast call'), and precisely when to use it versus alternatives. This carries the full burden effectively.

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

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

Schema description coverage is 100% and fully documents the required parameter and its aliases. The description does not add parameter-level details beyond what the schema provides, which is acceptable given the schema's completeness. 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 what the tool does: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This provides a specific verb and resource, and differentiates it from siblings like ask_pipeworx_grounded and 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?

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions' and gives clear conditions: 'Use whenever the user asks...' It also names alternatives: 'for a hallucination-resistant single answer ... use ask_pipeworx_grounded; for a broad/multi-part question ... use deep_research.' This is exemplary when-to-use guidance.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: it currently matches ask_pipeworx exactly because no candidate is active, it may change behavior when a candidate is under test, and it always functions as a real router. This exposes the experimental nature and status without contradicting annotations.

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

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

The description is concise yet information-dense. Each sentence earns its place: first defines what it is, second explains current state, third gives usage direction, fourth confirms it's a full router. No fluff or redundancy; front-loaded with the key fact that it is a beta version of ask_pipeworx.

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

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

For a tool with no output schema and only a question parameter, the description is quite complete: it explains the router nature, the identical behavior to ask_pipeworx, the experimental edge, and current status. It could mention what the response shape is in more detail, but saying 'same response shape' as ask_pipeworx is sufficient given the sibling context. Slight gap is that it doesn't explicitly state that it returns the routed tool's answer, though that's implied.

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

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

The input schema has 100% coverage, describing all six parameters as aliases for 'question'. The description adds no additional parameter semantics, but since the schema already fully documents aliases and the 'question' parameter is self-explanatory, the baseline of 3 is appropriate.

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

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

The description clearly states that ask_pipeworx_beta is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes it from siblings by explicitly framing it as the experimental edge with candidate routing improvements, making its purpose unmistakable.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It also clarifies that it is a full working router, not a fallback, which prevents misuse. This is clear when-to-use and implied when-not-to-use information.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses detailed refusal behavior with specific refusal_reason values, the return structure including evidence and confidence, and the extra LLM call cost. It also explains the routing and extraction mechanism, offering rich behavioral context that annotations do not cover.

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?

Though the description is long, every sentence contributes value: purpose, routing, extraction, output shape, refusal reasons, usage guidance, and cost tradeoff. It is front-loaded with the key purpose and structured logically, 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?

For a tool with complex routing, refusal behavior, and no output schema, the description fully specifies the success and failure return formats, enumerates refusal reasons, and explains when to use it. It includes all necessary context for an agent to select and invoke it correctly.

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

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

All six parameters are aliases for 'question' and are fully described in the schema (100% coverage). The description confirms the aliases but adds no new semantics beyond the schema, 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 identifies this as a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by stating it 'EXTRACTS the answer using ONLY what the tool result contains' and returns explicit refusals. This is a specific verb+resource with clear differentiation.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool and explains the cost tradeoff, providing complete usage direction.

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

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

While annotations already indicate read-only/idempotent/non-destructive, the description adds substantial behavioral context: low-confidence matches short-circuit with status, closed markets return a specific status, wide spreads carry a tradeability flag, news fields include fallback retry fields, and the resolver contract includes confidence scores and alternatives. This goes far beyond the annotations, detailing edge-case behavior the agent must know before trusting results.

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

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

Although long, the description is tightly organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every sentence adds operational value. It is front-loaded with the core purpose and then layers critical edge-case information. For a tool with no output schema and high complexity, this level of detail is necessary.

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

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

The description covers the full lifecycle: input resolution, classification, parallel fan-out, response shapes, resolver confidence, parent-event extraction, news fallback behavior, closed-market handling, spread warnings, and resolution-rule risk. With no output schema and rich annotations, the description carries the full burden and succeeds, leaving no major gap in understanding.

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

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

Schema coverage is 100%, and the schema already fully documents `market`, `depth`, and `include_raw` with descriptions and enums. The description reinforces the market input format ('Pass a market slug, a polymarket.com URL, or a question text') but adds no new meaning for the parameters themselves. The detail about response shaping is useful but not parameter-specific, 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly describes the tool's function and distinguishes it from sibling tools (polymarket_arbitrage, polymarket_edges, validate_claim) by focusing on a single bet and returning evidence plus a market-vs-model comparison. The included classifiers and fan-out examples further clarify scope.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples for various bet types. However, it does not mention when not to use this tool or point to specific sibling alternatives (e.g., polymarket_arbitrage for spreads), so it stops short of a 5.

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

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

The description discloses data sources (SEC EDGAR/XBRL, FAERS), edge-case handling (off-calendar fiscal years for AAPL and NVDA), sorting behavior by primary metric, and return format (paired data + citation URIs). This goes far beyond the annotations (readOnly, idempotent) and adds critical behavioral context.

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

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

The description is dense but every sentence adds value—trigger phrases, scope, data sources, sorting, output, and efficiency gain. It is front-loaded with usage examples and avoids verbosity. 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?

For a tool with no output schema, the description adequately explains the return structure (paired data + citation URIs) and covers all complexity: entity types, count limits, data source specifics, fiscal year handling, and output ordering. The agent has all necessary information for correct invocation and interpretation.

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

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

Schema coverage is 100% (baseline 3), but the description adds depth by explaining what each 'type' value pulls (company: financial metrics from 10-K; drug: FAERS counts, FDA approvals, trial counts) and provides concrete examples for the 'values' parameter (e.g., tickers vs drug names). This significantly enhances schema meaning.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from siblings by explicitly mentioning that it replaces 8–15 sequential lookups and by listing trigger phrases for comparison queries.

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

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

Provides explicit usage triggers (e.g., 'Compare X and Y', 'rank these companies') and a strong directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This gives the agent clear guidance on when to invoke this tool rather than alternatives.

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

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

The description goes far beyond the annotations by disclosing critical behaviors: the tool returns explicit gaps[] when it can't answer, never invents facts, provides resolvable citations only when available, and performs semantic excerpting of large records. It also specifies time expectations and contradiction reporting for standard/thorough depths, giving the agent a precise model of tool behavior.

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 information-dense, with no wasted sentences; every clause addresses a functional or operational aspect. It is somewhat dense and could be slightly tightened, but the complexity of the tool justifies the length, and it is well-structured with major points (account, purpose, alternatives, depth, output) in logical order.

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

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

With no output schema, the description thoroughly explains return values: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. It also covers prerequisites, limitations, depth options, and expected latency, making it fully self-contained for an agent to use correctly.

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

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

Schema coverage is 100% and already describes both parameters well. The description adds meaningful context beyond the schema by explaining that 'thorough' requires a paid plan and that 'standard' and 'thorough' trigger a contradictions scan, and it elaborates on depth semantics with facet counts. This enriches the parameter understanding without redundancy.

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 defines the tool's core function: grounded multi-source research across Pipeworx's 1455 structured data sources in one call, with decomposition and parallel routing. It distinguishes itself from siblings by explicitly naming alternatives (ask_pipeworx) and contrasting with open-web search, making the tool's unique value immediately obvious.

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?

Usage guidance is explicit and actionable: it states the tool is best for broad/multi-part questions over structured data, and provides clear when-not-to-use scenarios (single lookups, breaking news) with named alternatives. It also covers account prerequisites and depth-level trade-offs, giving the agent complete decision-making information.

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, idempotentHint, destructiveHint), the description discloses key behavioral traits: it returns top-N ranked tools, includes names/descriptions/full input schemas, and notes that results are 'ready to call directly, no second schema lookup needed'. This provides important operational context that annotations alone do not cover.

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

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

The description is concise and front-loaded with the primary action ('Find tools'). It uses a few dense sentences, each serving a purpose: purpose, usage timing, and return format. The domain list is efficient, not redundant.

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

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

Given the tool's simplicity (one required parameter, no nested objects, no output schema), the description is complete. It explains what the tool does, when to use it, what it returns (including schemas and examples), and the significance of the 'top-N' and 'no second schema lookup' details. No critical gaps are apparent.

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 adds semantic context about the kind of queries supported (listing domains like SEC filings, weather, etc.), which complements the schema's 'query' description but does not materially extend parameter meaning. The aliases and limit 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 uses a specific verb+resource ('Find tools') and clearly scopes the tool's purpose to discovering available tools across a defined set of domains (SEC filings, financials, FDA drugs, etc.). It distinguishes itself from the sibling tools by positioning itself as a discovery layer that returns a list of relevant tools, not a specific task execution.

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 when you need to browse, search, look up, or discover what tools exist') and gives a direct call to action ('Call this FIRST when you have many tools available'). It also implies exclusions by noting the tool is for seeing the option set 'not just one answer', suggesting direct tools are for specific answers.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context: it fans out across SEC EDGAR, XBRL, USPTO, GDELT, and GLEIF, uses a GDELT→GNews fallback, and discloses that the USPTO source 'soft-fails until reactivated.' It also details the return structure, which goes well beyond the minimal annotation.

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 dense, packing examples, a usage directive, and a complete list of outputs into a single well-organized paragraph. It is front-loaded with example queries and the core preference rule. While slightly verbose, every clause contributes useful information, so it earns a 4 rather than 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?

With no output schema, the description fully covers the return contract: it lists cik, company_name, recent_filings (with URI format), fundamentals (specific fields and sort order), patents, news, and LEI. It also explains the parallel-call design and fallback behavior, making the tool's behavior completely understandable for an agent.

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

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

The input schema already provides full descriptions for both parameters, including examples and the note that names are not supported. The description repeats these details but adds no new semantic information beyond what the schema provides. With 100% schema coverage, a baseline 3 is appropriate.

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

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

The description opens with concrete natural language triggers ('Tell me about X' / 'research Acme' / 'brief me on Tesla') and explicitly states its function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools by directing agents to prefer it over chaining single-pack lookups and by pointing to resolve_entity for name-only queries.

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 an explicit usage directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear exclusion ('names not supported') and provides an alternative (resolve_entity), plus notes the patent API's soft-fail condition. This covers when, when-not, and alternatives.

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

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

Annotations already convey destructiveHint=true and idempotentHint=true, and the description's 'Delete' matches this. It adds context about clearing sensitive data, which is useful, but doesn't disclose additional behavioral details like behavior on missing keys. Since annotations cover safety, a 3 is appropriate.

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

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

Two sentences, front-loaded with action, then usage context and pairing. Every sentence earns its place with no redundancy or filler.

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

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

For a simple single-parameter delete tool with strong annotations, the description is complete: purpose, usage triggers, and related tools are all covered. No output schema exists, but the description's scope is sufficient as the tool's behavior is fully contextualized.

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 'key' described as 'Memory key to delete', so the description adds no extra parameter semantics. Baseline 3 is warranted as the schema carries the full explanatory burden.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key', which precisely defines the tool's function. It also distinguishes from siblings like remember and recall by focusing on deletion.

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

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

The description provides explicit when-to-use guidance: stale context, task completion, or clearing sensitive data. It also recommends pairing with remember and recall, signaling related tools. However, it doesn't explicitly state when not to use the tool, 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?

The description discloses the underlying operation ('Fetches the page, extracts title/description/key links') and the output format, adding behavioral context beyond the annotations. It mentions a network fetch, which is a side effect, though annotations already indicate read-only, open-world, and idempotent behavior. This adds value without contradicting annotations.

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

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

The description is three well-structured sentences: purpose, process, output/use cases. It is front-loaded and every clause contributes directly to understanding the tool, with no padding.

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

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

For a two-parameter tool with rich annotations and a full schema, the description is complete: it states the input URL, the optional link cap (via schema), the process, and the output format ('single text blob ready to drop at site-root/llms.txt'). No output schema exists, but the description adequately covers expected return.

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

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

Both parameters are fully described in the schema (url and max_links), so the description doesn't need to add parameter-level detail. The description's mention of 'emits the standard llms.txt markdown format' partially implies the role of max_links but doesn't enhance beyond schema. Baseline 3 applies given 100% schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Generate'), the resource ('llms.txt file for any URL'), and the intended audience ('AI crawlers (ChatGPT, Claude, Perplexity)'). It also outlines the process briefly, distinguishing it from sibling tools that audit AI presence rather than producing the file.

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'), giving clear context for when to apply it. However, it doesn't directly contrast with sibling tools like 'scan_competitor_ai_presence' or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by specifying that the tool generates a self-deprecating, vulnerable, and humorous post and returns shareable text. It does not contradict annotations and gives a clear picture of the transformation performed.

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

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

The description is three sentences, each earning its place. It front-loads the primary action, then explains the input and output. No unnecessary words or repetition of schema details, making it highly concise and well-structured.

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

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

For a simple generation tool, the description covers the core behavior and the main output ('post text ready to share'). The presence of an output schema means return values need not be detailed. The only minor gap is that it doesn't mention the customizable 'spin' option in the text, but the schema provides that information, so overall completeness is strong.

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 67%, but the existing descriptions are mostly tautological ('Your achievement') or minimal. The tool description does not explain the 'spin' parameter or its enum values, nor does it detail how to choose a spin or what 'include_lesson' truly means beyond the schema. The only meaningful guidance is the reference to 'your accomplishment,' which maps to the achievement parameter, leaving the optional parameters underspecified.

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

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

The description clearly states the tool's purpose with a specific verb ('generate'), a specific resource ('a humorous LinkedIn post from an achievement'), and the output ('post text ready to share'). It also distinguishes this tool from all siblings, which are research/monitoring tools, by emphasizing the creative, humorous transformation of an accomplishment.

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

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

The description implies the intended use case: input an achievement to get a humorous post. It clearly indicates what the user should provide ('your accomplishment') and what they receive. However, it does not explicitly mention any alternatives or state when not to use the tool, though no similar sibling tools exist to warrant such exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns the caller's subscriptions and specific fields, but does not mention pagination, rate limits, or other behavioral details beyond what annotations imply.

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

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

The description is three sentences: first states the action and scope, second lists return fields, third gives usage guidance. There is no redundancy or filler; 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 list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context. Combined with rich annotations, it provides sufficient information 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 single parameter include_inactive is fully documented in the schema (100% coverage), with description 'Include cancelled subscriptions in the response (default false).' The tool description adds no additional parameter syntax or meaning beyond the schema, 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 opens with 'List the caller's active subscriptions,' a specific verb+resource+scope that clearly states what the tool does. It distinguishes from sibling subscribe/unsubscribe tools by focusing on the read-only listing of existing subscriptions, and the list of return fields reinforces 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?

It provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' However, it does not explicitly name alternatives or state when-not-to-use, so it lacks the explicit exclusion found in top-tier descriptions.

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 are all false, so the description carries the burden. It discloses rate limits (5 per identifier per day), cost (free, doesn't count against quota), and the claim_token flow (filing without an account returns a token; passing it later reads resolution status). It also mentions the team reads digests daily and signal affects roadmap, providing meaningful behavioral context beyond annotations.

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

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

Although the description is long, every sentence adds value: purpose, usage guidance, exclusions, claim_token mechanics, rate limits, cost, and processing cadence. It is front-loaded with the core purpose and structured logically.

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

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

The description fully covers the tool's behavior for a feedback/reporting tool with no output schema: how to file, what to include, how to follow up, constraints (rate limit, scope), and cost. It addresses potential misuse (reporting other servers' tools) and provides enough context for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics for claim_token (how to use it to check status) and for context (describe in terms of Pipeworx tools/packs, don't paste end-user prompt). This goes beyond the schema descriptions, though not all parameters receive extra detail.

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

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

The description begins with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes this tool from siblings (e.g., ask_pipeworx, discover_tools) by focusing on feedback about Pipeworx tools/packs, not research or queries.

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 scenarios: bug, feature/data_gap, praise. Clearly states when NOT to use it (tools from a different MCP server) and directs the agent to file with that other server instead. Also explains how to handle uncertainty about tool ownership.

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 (read-only, open-world, idempotent), the description discloses that the data is derived from a 'CF analytics-engine', contains 'no PII', is 'cached 5min-1h', and is a 'self-aggregating signal'. These details provide valuable behavioral context without contradicting 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 concise and front-loaded with the core statement, followed by a structured list of use cases. Every sentence adds value—purpose, examples, data source, caching—without unnecessary verbosity.

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

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

For a simple tool with one optional parameter and no output schema, the description is highly complete. It explains what is returned ('top tools, top packs, and total call volume'), the data shape ('(pack, tool, count)'), caching behavior, and privacy aspects, giving the agent enough context to use 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 fully describes the 'window' parameter with enum values and semantic guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description outside the schema only repeats these window options, adding no new parameter semantics, so 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 clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now' and specifies it returns 'top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'. It distinguishes itself from siblings like discover_tools by focusing on real-time aggregated usage trends rather than general discovery.

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

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

The description provides explicit 'Useful for' scenarios: (1) discovering hot data sources, (2) confirming canonical tool choice, (3) aligning use cases with agent demand. It offers clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Even with annotations declaring readOnly/idempotent/non-destructive, the description adds substantial behavioral detail: how partition_check sums YES prices, the >3pp threshold for emitting a signal, placeholder-slug filtering, Jaccard similarity anchors, and the fill-check caveat that a positive theoretical edge does not guarantee a realizable edge in the book. It openly warns 'do not trade it' when realizable_edge_pp ≤ 0.

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 densely informative with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose in the first sentence. Every section adds operational nuance without redundant phrasing, earning its place.

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

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

Given the tool's complexity, no output schema, and zero required parameters, the description fully compensates by specifying the response shape (opportunities[], partition_check fields), mode-specific outputs, and the fill-check pricing behavior. It leaves no major behavioral gap for an agent to guess.

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

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

Schema coverage is 100%, but the description adds examples for both parameters ('fed-decision-may-2026' for event, 'Strait of Hormuz traffic returns to normal' for topic) and clarifies mode-specific behavior. It explains what happens with no args and characterizes event as 'recommended' for specific markets, going well beyond the schema's property descriptions.

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

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

The description opens with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three distinct modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by explicitly positioning arb detection versus fill-risk pricing.

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

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

It explicitly states when to call with no args ('trending_scan'), when to use 'event' ('recommended for a specific market'), and when to use 'topic' ('for cross-event scanning'). It also names an alternative tool ('For custom sizing use polymarket_fill_risk') and explains that cross-event mode catches patterns single-event misses.

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=true, openWorldHint=true, idempotentHint=true), the description adds rich behavioral context: caching at KV level for 1 hour, response structure with by_segment and _diagnostics, why some segments might be empty, and caveats like the unreliable Fed signal. It also clarifies that partition arbs return kelly_fraction_half=0 by design and that gates were relaxed from prior settings, providing deep transparency into tool behavior.

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

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

The description is long but well-structured, with clear section headings (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loaded with the primary purpose. Every section adds meaningful detail for a complex tool, though a more bulleted or segmented format could improve scanability. It's not wastefully verbose, but it's on the heavier side.

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 (9 parameters, multiple model families, nested response structure) and the absence of an output schema, the description does an excellent job of covering return structure, model details, filtering knobs, diagnostics, and caching. It even explains why a segment might be empty and what to do about it, making it highly complete for an agent to use effectively.

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

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

The input schema already has 100% parameter description coverage, so the baseline is 3. The description adds some context about how knobs like min_liquidity and max_spread_pp relate to 'tradeable-edge' and mentions the min_partition_leg_kelly behavior, but much of this is already present in the schema's own parameter descriptions. It doesn't significantly surpass 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 opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's function and distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx data disagreement and a curated 'what should I bet on today' use case.

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

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

The description clearly states the tool is 'Built for "what should I bet on today"' and mentions that agents discover opportunities without paging hundreds of markets, giving strong contextual guidance. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of the 'explicit when/when-not' standard.

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

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

Annotations already indicate a read-only, idempotent operation, and the description adds meaningful behavioral detail: history depth is limited by the 60-day snapshot TTL, snapshot gaps indicate days nobody scanned, and decay numbers are based on daily closes rather than intraday. These are non-obvious, context-specific constraints that help the agent set expectations.

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

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

The description is long but well-structured, separating Args, RESPONSE, and LIMITS into distinct sections. It front-loads the purpose and packs every sentence with relevant detail; the only slightly expendable phrase is the parenthetical about why old wide edges are different, which adds color but also clarifies intent. Overall, it earns a high score for organization despite 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?

With no output schema, the description needed to fully specify the response shape, and it does: tracked[] with full time-series, first_seen, trend, decay_pp_per_day, expired[] with lifespan_days, and snapshot_dates[]. It also covers limits (TTL, snapshot gaps, daily vs intraday). This is a complete spec for a tool with 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?

The schema already documents both parameters with defaults and allowed values (days: 14 default, clamp 2-30; window: 24hr|1wk|1mo). The description restates the defaults and adds the phrase 'snapshot family' to clarify window's meaning, but provides no additional depth beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, and states the core question it answers: 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges by focusing on historical persistence rather than current edge scanning.

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 opens with the exact use case ('how long has this edge existed and is it shrinking?') and explains why it matters (a fresh wide edge vs a 3-week-old one). It does not explicitly exclude alternatives, but the context makes it clear this is for persistence/decay analysis, not for finding new edges or executing trades.

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

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

Annotations already declare read-only and non-destructive behavior, so the bar for additional context is met abundantly. The description discloses operational behavior: walks the order book ladder, returns VWAP and slippage, computes theoretical vs realizable sums, and names 'forced_directional_risk.' It also warns about partial basket fills creating unhedged directional exposure—valuable beyond annotation hints. No contradiction exists.

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

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

The description is long but every sentence carries critical detail. It is front-loaded with the core purpose, uses ALL-CAPS section labels (SINGLE-MARKET, BASKET, USE THIS) to make scanning easier, and avoids filler. It slightly loses a point for density—an agent might need to parse carefully—but it is not redundant.

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 enumerates all key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, capture_ratio, profit_usd, thin_legs, forced_directional_risk). It also covers both modes comprehensively, explains the auto default for side in basket mode, and includes safety thresholds. This is remarkably complete for a tool with two operational contexts.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains how 'side' behaves differently in single-market vs basket modes, how size_usd is interpreted as spend, target proceeds, or settlement notional, and mentions defaults and clamping. For instance, it clarifies 'max spend on buys, target proceeds on sells'—a distinction not present in the schema. This turns the parameter descriptions into actionable usage guidance.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and lists concrete outputs like top_of_book, slippage_pp, and verdict. This sets it apart from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill analysis rather than discovery.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing thin-book overround and the risk of partial fills converting an arb into an unhedged directional position. This gives the agent a clear trigger condition and rationale 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 already declare readOnly, openWorld, idempotent, non-destructive. The description goes far beyond these by detailing compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type counters, and the meaning of matched_pairs:0 cases. It also warns about the rarity of real arbitrage, giving the agent a realistic expectation of outcomes.

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 with clear mode labels and field names. Every sentence carries informational weight, though it is quite long. It earns a 4 rather than 5 because it could be tightened without losing critical details; some redundancy exists (e.g., re-explaining skipped_cross_type in both the warning and the counters description).

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 all return fields and behaviors, which it does comprehensively: leg-by-leg prices, matched_spread[], safety fields, temporal_alignment, and skip counters. It also covers the two input modes and the open-world caveat. This is a complete self-contained spec for a complex tool.

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

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

Schema coverage is 100% with each parameter described, so baseline is 3. The description adds value by explaining how topic maps to both venues, how explicit parameters override the mapped side, and giving concrete examples. It doesn't fully spell out the format of the response within the parameters, but that is handled in the behavior section.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from siblings like polymarket_arbitrage by emphasizing the cross-venue aspect and the two modes of operation.

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) and provides practical guidance with the caution that 'pre-mapped ≠ tradeable.' However, it does not explicitly contrast with related sibling tools (e.g., polymarket_arbitrage) or state exclusion criteria, so it stops short of full alternative 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=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: the scoping to identifier (anonymous IP, BYO key hash, or account ID) and the dual-mode behavior (retrieve single value vs. list all keys). 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 concise, front-loaded sentences. Each sentence earns its place: action (retrieve/list), use-case rationale, and scoping/pairing. 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 simple read-only tool with one optional parameter and rich annotations, the description covers what it does, when to use it, and scoping. It implies the return behavior (value or list of keys) through examples, though it doesn't explicitly describe the return format. This is a minor gap given 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?

Schema coverage is 100% with a clear parameter description ('Memory key to retrieve (omit to list all keys)'). The description reinforces this but adds no new syntactic or semantic detail beyond what the schema provides, so baseline 3 applies.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the resource (saved values/keys), provides concrete examples (user's target ticker, address), and distinguishes it from sibling tools like remember and forget.

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

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

Explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch,' providing clear when-to-use guidance. Also mentions scoping to your identifier and pairs with remember/forget, giving a complete usage model.

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 state readOnlyHint:true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This is a state-changing operation that directly contradicts the read-only annotation. The description also lacks disclosure of other behavioral traits like pagination or error semantics, but the contradiction alone forces a score of 1.

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 earning its place: the first states purpose and return content, the second explains filtering and mark_read behavior, and the third gives polling guidance and an alternative endpoint. No filler or repetition.

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

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

The description covers the main usage scenarios, the shape of the returned payload, persistence, and the alternative feed URL. It does not mention limit defaults or unread_only, but these are already in the schema. Given the tool's moderate complexity and strong schema, the description is nearly complete, though the mark_read contradiction creates a gap in accurate guidance.

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

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

Schema already covers all parameters (100% coverage), so baseline is 3. The description adds value by giving examples for type ('sec_8k'), clarifying the ISO timestamp format for since, and explaining the side effect of mark_read on future calls. This goes beyond the schema descriptions.

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

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

The description opens with the specific verb 'Pull' and the resource 'fired events from your subscription feed', clearly distinguishing this from sibling tools like list_subscriptions. It also details what the returned events contain (source, citation_uri, raw payload), making the tool's purpose concrete.

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

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

The description provides clear context on when to use the tool: for polling recent alerts, and explicitly mentions an alternative HTTP endpoint for scripts/dashboards. However, it does not name specific sibling tools to prefer over this one, so it stops short of full exclusion guidance.

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

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

Annotations already declare the tool is read-only, idempotent, and non-destructive. The description adds significant behavioral context beyond annotations: it discloses fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to PatentsView sunset, and the structured return format with citation URIs.

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: it leads with user intent phrases, then states the core functionality, follows with source details and parameter formats, and ends with an alternative tool. Every clause adds information without redundancy.

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

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

High complexity (multiple external sources, fallback logic, soft-fail). With no output schema, the description covers return shape ('changes[] grouped by source + total_changes + citation URIs'), edge cases (rate limits, 5xx, PatentsView sunset), and the alternative tool. It leaves no critical gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining `since` accepted formats ('2026-04-01' or '7d'), and giving examples for `value` (ticker or CIK). It doesn't dramatically change semantics, but the extra clarity on relative time shorthands and typical usage earns a 4.

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

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

The description begins with clear trigger phrases and states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes from the sibling entity_profile by explicitly contrasting static profile vs. windowed changes.

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 when-to-use guidance via trigger phrases, describes the fan-out to multiple sources, and names an alternative tool (entity_profile) for static profiles. It also clarifies typical `since` values like '30d' or '1m'.

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 non-read-only, idempotent, and non-destructive behavior. The description adds value by disclosing persistence semantics: authenticated users get persistent memory, anonymous sessions retain for 24 hours, and data is scoped by identifier. This goes beyond the structured annotations with meaningful operational context.

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

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

The description is a single focused paragraph that front-loads the purpose in the first sentence. It includes necessary usage guidance, persistence details, and sibling references without excessive verbosity. Each sentence contributes meaningful information, though it is slightly longer than strictly necessary.

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 key-value storage tool with no output schema, the description is complete. It covers what the tool does, when to use it, persistence behavior, scoping, and how it relates to recall and forget. No critical context is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100% for both key and value parameters, so the schema already documents their meanings. The description adds generic context about key-value pairs but no additional parameter-specific details beyond the schema examples. Baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states a specific verb+resource: 'Save data the agent will need to reuse later' and explicitly distinguishes the tool from siblings by naming recall and forget. It also provides concrete examples of what to store (ticker, address, preference, research subject), leaving no ambiguity about the tool's 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 explicit 'when to use' guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names the alternatives (recall for retrieving, forget for deleting), making the usage context crystal clear and differentiating from sibling tools.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description reveals substantial behavior: internal cascading of multiple lookup endpoints, graceful degradation if GLEIF/OpenFIGI are unavailable, source-labeling of identifiers, and explicit reporting of unresolved identifiers. This adds valuable context not captured in annotations.

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

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

The description is long but every sentence serves a purpose: opening with user-intent examples, core purpose, supported types with detailed output, and caveats like graceful degradation. It is well-structured and front-loaded with the most actionable guidance, making the length justified.

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?

There is no output schema, so the description carries the burden of explaining return values. It explicitly lists the identifiers returned (CIK, ticker, LEI, FIGI, RxCUI), the source attribution, the unresolved field, and fallback behavior. This makes the tool fully understandable 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?

With 100% schema coverage, the baseline is 3, but the description significantly extends parameter meaning: it explains the two types ('company' with CIK/ticker/LEI/FIGI and 'drug' with RxCUI/ingredient/brand), the input formats for value (ticker, CIK, name, brand, generic), and enrichment behavior. This goes well beyond the schema's terse descriptions.

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

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

The description clearly states the tool resolves user-spoken names to 'canonical/official identifiers other tools require as input,' with a specific verb ('resolve') and resource ('entity names to identifiers'). It distinguishes itself from siblings by explicitly positioning it as a prerequisite ('Use FIRST') and listing example queries that map to its scope.

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

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

It gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and provides multiple example user queries. However, it does not mention when not to use it or name alternative tools like entity_profile, so it misses the 'when-not/alternatives' component for a top score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral context beyond these: it mentions probing each entity with ai_visibility_check, ranking by score, and returning a ranked list with score, confidence, and signal density. It also implies the tool makes multiple internal probes but does not disclose potential rate limits or costs.

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

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

The description is three sentences long, front-loaded with the core purpose, and each sentence earns its place. It explains what, how, when, and what to expect without any 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?

With no output schema, the description appropriately explains the return format: 'ranked list with score, confidence, signal density per entity.' It also covers the tool's internal mechanism and typical use case, making it complete for the tool's complexity. The 100% schema coverage handles parameter details.

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 significant meaning beyond the schema's parameter descriptions. It echoes the 'first entry subject' idea and 'competitors' from the schema but provides no extra syntax, defaults, or edge cases.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the method (probes each entity with ai_visibility_check, ranks by score) and the output (which is most/least recognized). It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by emphasizing competitive AI-marketing audits.

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: 'Useful for competitive AI-marketing audits' with an example query. However, it does not explicitly state when NOT to use this tool or name alternatives (e.g., 'for single entity, use ai_visibility_check'), though the context implies multi-entity comparison.

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, idempotentHint), the description discloses partial failure behavior, timeout expectations (5-30s for first bundlephobia measurement), and the sources_failed field. It also scopes the tool to NPM ecosystem in v1, which is critical behavioral context. This adds real value beyond the structured annotations.

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

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

The description is compact yet information-dense: purpose, use case, output summary, ecosystem scope, and failure handling in four sentences. Every sentence serves a distinct purpose, and it is front-loaded with the most critical information. No 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?

Despite lacking an output schema, the description enumerates the return fields (summary block, per-advisory detail, links, recent alternatives). It also covers limitations (NPM-only, timeout behavior) and fallback guidance for other ecosystems. This is a complete picture for an agent to invoke the tool appropriately.

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

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

The schema covers both parameters fully (package name and version default). The description restates that version defaults to latest but adds no new semantic detail beyond the schema. Baseline 3 is appropriate given 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 opens with a specific verb phrase 'Composite "should I add this npm package to my project" check in ONE call' and enumerates exact data sources (deps.dev, bundlephobia) and outputs. This clearly distinguishes it from the sibling tools, many of which are focused on research, alerts, or comparisons.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an alternative: for non-NPM ecosystems, use deps.dev:version directly. This is concrete and actionable 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 readOnly/idempotent/destructive=false, and the description adds further behavioral details: embedding model (BGE-base-en), cosine similarity over 500-char windows, 200K char cap with truncation and flagging, and every passage includes character offsets for verbatim verification. 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 dense paragraph that front-loads the core function and then provides usage guidance and technical specifics without redundancy. Every sentence adds value, making it efficient.

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

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

For a 3-parameter tool with no output schema, the description covers what is returned (passages with offsets and similarity scores), limits (200K chars), usage scenarios, and technical implementation. This is sufficiently complete for an agent to 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 detailed descriptions for text, query, and limit. The description reinforces these but does not add new parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' giving a specific verb and resource scope. It distinguishes itself from siblings like ask_pipeworx by emphasizing search within already-fetched text, and mentions pairing with ask_pipeworx_grounded. This is clear 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides an alternative workflow by pairing with ask_pipeworx_grounded, and explains the benefit of saving context and returning only relevant passages.

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

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

Annotations only indicate non-read-only and non-destructive, but the description adds substantial behavioral details: account persistence requirement, feed always-on, email/SMS delivery with verification and caps, webhook HMAC signing, and auto-disabling after 10 consecutive failures. It does not contradict any annotation.

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

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

The description is well-structured: it opens with purpose and return value, then groups supported types and delivery channels with bullet-like clarity. Every sentence adds value, and the length is justified by the tool's complexity.

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

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

For a tool with no output schema, the description and schema together fully cover what is returned, prerequisites, delivery behavior, failure handling, and examples. It leaves no critical gaps for an agent to invoke it correctly.

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

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

Although schema coverage is 100%, the description enriches parameter understanding with concrete examples for each subscription type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and further clarifies delivery options (email, SMS, webhook with signing secret). This goes beyond the schema's terse descriptions.

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

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

The description clearly states the verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and immediately notes the return value (new subscription id). It differentiates from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action.

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

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

Provides explicit when-to-use context by specifying the required OAuth account and exclusions (anonymous/BYO cannot persist). It also gives alternatives for pulling alerts ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'), and details prerequisites for SMS (phone verification) and the 10/day cap. This goes beyond basic usage guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable context about the return structure (category-bucketed examples with tool+argument shape) and that it draws from the 'live catalog of thousands of tools'. It doesn't discuss edge cases like invalid topics, but the annotation coverage lowers the burden.

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: it begins with user-intent examples, then states purpose, output, invocation modes, and usage context. Every sentence contributes meaningful information with no filler. It's longer than average but earns its length with high information density.

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

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

Even though there is no output schema, the description clearly defines what is returned: 'category-bucketed example questions... each with the exact tool + argument shape'. It covers parameter behavior, when to use, and relationship to meta-tools. For a discovery tool with one optional parameter and strong annotations, this is complete.

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

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

Schema covers 'topic' with 100% description coverage, giving a solid baseline. The description goes beyond the schema by providing concrete example values ('finance', 'pharma', 'betting'), clarifying the effect of omission ('full spread' vs 'focus'), and framing topic as a focus control. This enriches the parameter's meaning.

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

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

The description opens with natural user queries, explicitly calls itself 'the onboarding entry point for an agent that just connected', and specifies the exact output: 'category-bucketed example questions... each with the exact tool + argument shape'. It also distinguishes itself from sibling tools with 'Use this FIRST when you do not yet know what Pipeworx can do for you'.

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...' Additionally, it explains the two invocation modes: 'Call with no arguments for the full spread, or pass topic to focus', including example topic values like 'finance', 'pharma', 'betting'.

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

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

The description adds meaningful behavioral details beyond the annotations: ownership is enforced, the row is deactivated rather than deleted, and historical events remain accessible. This aligns with destructiveHint:false and idempotentHint:true, but does not contradict any annotation.

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

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

The description is concise, with two clear sentences. It front-loads the action and then provides two important behavioral caveats without any unnecessary fluff.

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

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

Given the simple tool (one parameter, full schema coverage, no output schema), the description fully covers the necessary context: what it does, the ownership constraint, the non-destructive nature, and the historical events availability. Nothing essential is missing.

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

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

The input schema already provides full coverage for the 'id' parameter, describing it as a 'Subscription id (uuid) returned by subscribe.' The description does not add any additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on cancellation, and adds a scope constraint ('your own subscriptions').

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

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

The description implies usage context: it is for canceling subscriptions, with ownership enforcement. It also signals what happens after cancellation (historical events remain via recent_alerts), providing useful context. However, it does not explicitly name alternatives or 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.

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavioral context: the dual-path routing, the verdict categories, the requirement to cite evidence with pipeworx://, and especially the distinction between could_not_verify (check did not happen, with verification_error) and unsupported (no source covers it). It also warns callers against misinterpreting could_not_verify as evidence, which is crucial. This goes well beyond the structured metadata.

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

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

Though longer than average, every sentence earns its place. It opens with highly recognizable trigger phrases, quickly moves to the routing logic, then enumerates return values and error semantics, and closes with the efficiency benefit (replaces 4–6 sequential calls). There is no filler; the structure is logical and front-loaded with the most important 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?

With no output schema, the description carries the full burden of explaining return values. It provides the complete list of verdicts, the actual value with citation, reasoning, and the critical error handling distinction. Given the tool's complexity (two processing paths), the description is remarkably complete: an agent knows exactly what to expect and how to interpret results. It also explains the trigger conditions and parameter overrides, making it self-sufficient.

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

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

Schema coverage is 100% for both parameters, but the description adds substantial semantic value beyond the schema. For tolerance_pct, it explains that it overrides the tolerance implied by the claim wording, provides a concrete use case (set 1–2 for hallucination detection), and states the default cap at 5. The claim parameter is illustrated with two realistic examples, clarifying expected input format.

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 'validate' with a clear resource: 'natural-language claim verification against authoritative sources.' It lists trigger phrases ('fact check', 'verify the claim that…'), making it immediately identifiable. It differentiates from sibling tools by specifying the structured SEC EDGAR/XBRL path for company-financial claims and a grounded pipeline for other claims, which is distinct from general-purpose ask_pipeworx or deep_research tools.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing guidance for company-financial vs. other claims. However, it does not explicitly name when NOT to use this tool or mention alternative tools (e.g., ask_pipeworx_grounded), so it falls short of the 5 criterion for explicit exclusions.

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