Apology

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) cover safety and idempotency. The description adds beyond this by specifying that the default model is free, requiring an API key for Anthropic, and detailing the return format including per-model score, confidence, signals, and raw response. No contradictions.

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

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

The description is three sentences with critical information front-loaded. Every sentence adds value: what it does, how it works, return format, and use cases. 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?

Given the tool's complexity (multiple models, optional keys, no output schema), the description provides a complete overview: purpose, parameters, behavior, return format, and use cases. It sufficiently prepares an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, setting a baseline of 3. The description adds value by explaining the _apiKey parameter as "BYO key" with cost implications and the context parameter as helping "disambiguate common names." This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: "Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model." It uses a specific verb and resource, and distinguishes itself from sibling tools by focusing on general visibility scoring rather than competitive 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 explicitly lists use cases: "AI-marketing audits, pre-launch brand checks, competitive monitoring." It provides context for when to use the tool but does not contrast with sibling tools like scan_competitor_ai_presence, missing explicit alternatives or 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, idempotentHint true, and destructiveHint false, so the description's claim that it 'returns ready-to-use apology text' adds context but does not contradict. No additional behavioral traits disclosed beyond annotations.

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

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

Two sentences: first sentence defines purpose and all parameters, second sentence states output. No extraneous text, front-loaded with core function.

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

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

The description covers all parameters and output type. Minor gap: it does not note that only offense is required. Otherwise, sufficiently complete for a tool with rich annotations and no output schema needed.

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 0%, but the description explicitly lists all four parameters with example values for each enum (relationship, sincerity, medium). This compensates fully, providing meaning the schema lacks.

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

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

The description clearly states the tool generates a tailored apology, with specific verb 'generate' and resource 'apology'. It lists all input parameters and distinguishes it from sibling tools which are unrelated (e.g., research, betting, visibility).

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

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

No explicit guidance on when to use or when not to use this tool. It does not mention alternatives or prerequisites, relying on the tool's name and description to imply usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral detail beyond annotations: it routes the question, fills arguments, and returns structured answers with stable citation URIs. No contradictions with annotations are present.

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

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

The description is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and packs in trigger phrases, examples, and fallback guidance. It is somewhat long and repeats the 'even if web search could also answer' idea twice, but every section earns its place.

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

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

Given the tool's simple one-required-question-parameter interface and no output schema, the description sufficiently explains what happens when called: routing, argument filling, and structured answers with stable citation URIs. It also covers fallback behavior for topics outside the listed scope, making it complete for an agent selecting and invoking the tool.

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

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

Schema description coverage is 100%, and the schema already documents the question parameter and its aliases in detail. The description's example queries add illustrative value but no additional parameter-level semantics. This meets the baseline for a fully schema-documented single, required parameter.

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

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

The description clearly identifies the tool as a natural-language router to 5,798 tools across 1,517 verified sources, returning structured answers with pipeworx:// citation URIs. It also contrasts itself with web search. However, it does not distinguish itself from sibling variants such as ask_pipeworx_beta or ask_pipeworx_grounded, so it misses full sibling 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: prefer over web search for factual, current, or historical data questions, with concrete trigger phrases and examples. It also states when to fall back to web search. It does not, however, explain when to choose this over the related sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

Beyond the annotations, the description discloses the experimental edge, the on/off state of candidate routing improvements, the fact that results are compared against the stable router, and that this is still a fully working router with no fallback. It also clarifies the current identical behavior to ask_pipeworx, which is critical for an agent deciding whether to use it.

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

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

The description is dense but purposeful, front-loading the beta relationship and the key operational facts. A small amount of redundancy exists around the tool being identical to ask_pipeworx, but every sentence contributes useful context about current behavior and experimental status.

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 universal router with no output schema, the description is remarkably complete: it covers what the tool does, how it relates to the stable version, what is currently active, how to use it, and what response shape to expect. Nothing essential for selecting or invoking the tool is missing.

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

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

Schema description coverage is 100%, and the schema already documents all six parameters and their aliases. The description adds little beyond confirming that the arguments are identical to ask_pipeworx, so the schema carries the semantic burden and the description does not materially improve parameter understanding.

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

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

The description states this is a beta version of ask_pipeworx with the same 5,798 tools, arguments, and response shape, while distinguishing it from the stable router through its candidate routing improvements. The verb 'ask' plus the explicit resource and experimental scope make the purpose immediately clear and distinct from sibling tools.

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

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

The description says to use this tool exactly like ask_pipeworx when you want the newest routing, and notes that it currently matches ask_pipeworx because no candidate is active. It provides clear context and names the stable alternative, though it does not explicitly state when not to use it beyond the implication that stable routing is the alternative.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, so the description goes beyond by disclosing the extra LLM call cost, the structured success and refusal responses, the specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the guarantee to use only tool-returned data. No contradiction with annotations exists.

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

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

The description is dense but each sentence earns its place: mode, routing behavior, output shape, refusal behavior, usage guidance, and cost trade-off. It is front-loaded with the core purpose and the reader never has to hunt for key facts.

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

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

Despite having no output schema, the description fully specifies the success return shape and the refusal shape with enumerated reasons. It also covers cost, use cases, and the relationship to its sibling, making it complete for an agent to decide when to call it and what to expect.

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

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

Schema coverage is 100%, and the schema describes the question parameter and its aliases. The description adds little about parameter semantics beyond saying the tool 'fills arguments' internally, but it does not need to compensate because the schema already fully documents the single meaningful input.

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, with a specific verb ('answer') and resource (Pipeworx). It explicitly distinguishes itself from the sibling ask_pipeworx by describing the same routing but a stricter extraction behavior ('EXTRACTS the answer using ONLY what the tool result contains').

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also names the alternative and gives the trade-off: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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 provides extensive behavioral details beyond annotations, including market resolution process, classifier categories, fan-out examples, response shapes, resolver confidence levels, parent event extraction, news fallback, safety checks (low-confidence, closed markets), wide-spread illiquidity, and resolution-rule risk. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and supplemented. No contradiction.

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

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

The description is information-dense and front-loaded with the core purpose, but it is very long with verbose fan-out examples and detailed edge cases. While justified by complexity, it could be more concise by omitting some examples or moving them to a separate section. Structure is a single paragraph without clear headings.

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 (3 parameters, no output schema), the description covers all necessary aspects: inputs, expected outputs, error states (low-confidence, closed markets), safety mechanisms, and resolution rules. It is comprehensive enough for an agent to correctly invoke and interpret results without ambiguity.

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. The description adds value by explaining the depth enum values (quick = 2-3 sources, thorough = full fan-out) and default behavior, and the include_raw parameter with use cases (summarized vs full payload). Also provides examples for the market parameter inputs. This extends beyond the schema definition.

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 researches Polymarket bets by pulling relevant Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). Although it doesn't explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, the purpose is specific and actionable.

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

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

Explicit use cases are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also provides fan-out examples for different bet types. However, it does not explicitly state when NOT to use the tool or suggest alternatives, though the depth parameter (quick vs thorough) implies some usage nuance.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable details: for type='company' it pulls latest 10-K financial data and handles off-calendar fiscal years; for type='drug' it pulls FAERS counts and trial data. It also describes result ordering and 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 slightly long but highly informative and front-loaded with example queries. Every sentence adds value, though some phrases could be tightened.

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

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

Despite no output schema, the description explains return type (paired data + citation URIs) and sorting by primary metric. It covers all behavioral aspects, making the tool self-contained for an AI agent.

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

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

Schema coverage is 100%, but the description enriches meaning by specifying that values should be tickers/CIKs for companies and drug names for drugs. It also explains that the 'type' parameter determines the data source and metrics.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific example queries like 'compare X and Y' or 'which is bigger'. It distinguishes itself from sibling tools like entity_profile, which does single-entity lookups.

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

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

Explicitly advises to always prefer this tool over sequential single-entity lookups when comparing entities, providing clear when-to-use guidance. No alternatives mentioned but strong preference stated.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the bar for behavioral disclosure is lower, yet the description adds substantial context: account/paid-plan requirements, parallel decomposition into facets, routing to 5,798 tools, gaps[] for unanswered facets, contradictions[] for disagreeing findings, semantic excerpting (not head-truncated), citation fetchability guarantees, and expected latency. No contradictions with annotations.

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

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

The description is long, but every sentence adds a specific fact about behavior, constraints, or return format. It front-loads the account requirement and the key differentiator (structured data, not open-web). It is dense rather than padded, though a slightly tighter structure could improve scannability.

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

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

Given the tool's complexity and the absence of an output schema, the description fully discloses return values (findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation), gap handling, contradiction detection, excerpting behavior, auth prerequisites, and runtime. Everything an agent needs to call it correctly and interpret results is present.

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

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

Input schema covers 100% of parameters, so baseline is 3. The description enriches this by explaining depth semantics beyond the enum descriptions (quick=3 single hop, standard=3 adds gap recovery + contradictions, thorough=6 paid with iterative chase) and adds latency expectations per depth. It also clarifies that the question parameter is meant to be broad/multi-part, which reinforces the schema but adds practical 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 states a specific verb ('research') and resource ('Pipeworx's 1517 STRUCTURED data sources'), and explicitly contrasts with open-web search: 'this is NOT open-web search.' It also differentiates from sibling ask_pipeworx by noting this is for broad/multi-part questions over structured data, making selection unambiguous.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead,' and 'For a single lookup use ask_pipeworx.' It also describes the best use case ('broad/multi-part questions over structured data') and depth-tier tradeoffs, so an agent knows exactly when to invoke this tool vs 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 provide readOnlyHint, idempotentHint, etc. Description adds valuable behavioral details: returns top-N tools with full schemas and curated examples, ready to call directly, which goes beyond annotations.

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

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

Description is ~80 words, well-structured with front-loaded purpose, domain list, and return detail. No unnecessary words; every sentence adds value.

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

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

For a discovery tool with high schema coverage and no output schema, the description fully explains purpose, usage, return format (names, descriptions, schemas, examples), and when to invoke. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra context by listing domain categories that help formulate queries, and mentions aliases already in schema. Partial value added.

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

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

The description clearly states the tool finds tools by describing data or task, lists example domains (SEC filings, FDA drugs, etc.), and distinguishes itself as a meta-tool to call first, setting it apart from siblings.

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

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

Explicit guidance: 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available', giving clear when-to-use context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, and the description adds substantial behavioral context: USPTO PatentsView sunset soft-fails, FDA products may legitimately be empty for small-molecule companies, value resolution behavior, and the sources_used/sources_failed semantics. 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 dense and long, but it earns its length given the tool's multi-source complexity. It front-loads user-phrase examples and the key preference directive before enumerating output sections. A slightly tighter structure would be possible, but no information feels wasted.

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 complex tool with no output schema, this description is remarkably complete: it enumerates every data source, each major return section, URI examples, soft-failure behavior, empty-section semantics, and the private-company edge case. An agent has enough information to invoke the tool correctly and interpret its results 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?

Schema coverage is 100% and already documents type and value clearly. The description adds real semantic value beyond the schema: it confirms 'company' and 'ticker' are interchangeable, specifies valid value shapes (ticker, zero-padded CIK, company name), and explains the resolution/private-company behavior. This goes beyond the baseline without being redundant.

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 and resource: it 'fans out across SEC EDGAR, XBRL, USPTO patents, federal contracts...' to build a 'full cross-source profile of a US public company.' It is immediately distinguishable from sibling tools like resolve_entity and compare_entities because it explicitly states it provides a holistic one-call profile rather than a single lookup or comparison.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving concrete when-to-use guidance. It also distinguishes failure cases: private companies return resolved:false rather than a bare failure, and empty sections are 'real no data, not a bug.'

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

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

Annotations already provide destructiveHint true, and the description adds context about clearing sensitive data, which is consistent. No contradictions.

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

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

Two clear sentences with front-loaded purpose. No unnecessary words.

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

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

For a simple deletion tool with one parameter and full schema coverage, the description adequately covers context. Could mention irreversibility but not required.

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

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

The single 'key' parameter is fully described in the schema (100% coverage). The description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states it deletes a stored memory by key, with a specific verb and resource. It distinguishes from sibling tools like remember and recall.

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

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

Explicitly states when to use the tool: stale context, task done, or clearing sensitive data. Also mentions pairing with related 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?

Annotations already convey readOnly, idempotent, non-destructive traits. The description adds behavioral context by detailing the process (fetches page, extracts info, emits markdown), which complements annotations without contradiction. No further disclosure needed.

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 (4 sentences), front-loaded with the primary action and main features, and every sentence adds value. No unnecessary words or repetitions.

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

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

Given the tool's moderate complexity (2 params, no output schema, but rich annotations), the description covers the process, output format ('single text blob ready to drop at site-root/llms.txt'), and use cases. It provides sufficient context for an AI 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 both parameters fully described. The tool description adds no additional semantic value beyond what the schema already provides. 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 defines the tool's action ('generate a production-ready llms.txt file for any URL') and distinctively positions it among siblings by specifying its use case for AI crawler indexing. It avoids tautology and provides a specific verb-resource combination.

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

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

The description explicitly lists three use cases (client indexing, drafting for own project, auditing competitor), providing clear context for when to use. It does not explicitly state when not to use or name alternatives, but the listed use cases sufficiently guide selection.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc., covering safety. Description adds return fields but doesn't disclose potential limits or pagination. It does not contradict annotations.

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

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

Two sentences, no fluff. Front-loaded with purpose, then lists return fields, then usage guidance. Every sentence adds value.

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

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

Given low complexity (1 optional param, no output schema, annotations cover safety), description is complete. It states purpose, return values, and usage context. No missing critical information.

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

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

Schema has 100% coverage with description for 'include_inactive'. Description adds no additional parameter meaning beyond the schema, meeting baseline for high 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?

Description clearly states it lists the caller's active subscriptions and specifies the return fields (id, type, params, created_at, etc.). It distinguishes from siblings by mentioning 'active' and usage context (before adding or canceling).

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This indirectly covers when-not-to-use (e.g., not for creating or modifying subscriptions). Could more explicitly exclude alternatives, but sufficient.

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

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

With all annotation hints false (no read-only, no idempotency, etc.), the description carries the full burden and does so thoroughly. It discloses the claim_token mechanism for later follow-up, rate limits (5/day), that it is free and does not count against quota, and the operational impact (daily digests, roadmap signal). These details go well beyond what annotations provide.

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

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

The description is a single dense paragraph, but every sentence earns its place. It flows logically: purpose → when to use → exclusion boundary → identification tip → content guidance → token mechanics → transparency (rate limit/quota). No filler, no redundancy, and front-loaded with the most critical information.

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

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

For a medium-complexity tool with 4 params, no output schema, and weak annotations, the description covers nearly all necessary context: return behavior (claim_token, follow-up read), usage boundaries, and operational constraints. It does not detail the exact response shape for a successful submission, but the token-based follow-up mechanism is the key output and is clearly explained.

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

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

The schema already has 100% parameter coverage, but the description adds valuable context: it instructs users on how to frame the 'message' parameter (be specific, avoid pasting end-user prompts) and explains the 'claim_token' parameter's round-trip use (pass it back to read status/resolution). This enriches the raw schema definitions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately enumerates the types of feedback (bug, feature/data_gap, praise) and distinguishes this tool from sibling research/query tools by explicitly limiting it to feedback about Pipeworx-served tools only.

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 (wrong/stale data, missing tool, praise) and when-not-to-use guidance (feedback for tools from other MCP servers, with a clear directive to file with that server instead). It even gives a heuristic for identifying Pipeworx tools, making the decision boundary unambiguous.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: caching (5min-1h), data source (CF analytics-engine), and privacy (no PII). Minor missing details like rate limits, but overall strong.

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

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

Concise at ~80 words, front-loaded with purpose, uses bullet points for clarity. Every sentence adds value without redundancy.

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

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

Given one optional parameter, no output schema, and read-only nature, description covers purpose, uses, caching, and data source. Lacks explicit return format but is sufficient for most agents. Slight gap in not describing response structure.

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?

Single parameter 'window' fully covered in schema (enum, description). Description adds contextual guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand', surpassing baseline 3.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, with specific verbs and resource. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on popularity metrics.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and contrasts short vs. long windows. Provides clear guidance on when to use without requiring further inference.

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

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

Annotations already declare readOnlyHint=true, and the description adds extensive behavioral details: internal filters (Jaccard similarity, placeholder fraction), returned signals, and fill check logic. No contradictions exist, and the description enriches understanding of safe, read-only 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 well-structured with clear mode breakdowns and logical sections, but it is somewhat verbose. Every sentence adds value, though tighter phrasing could improve conciseness.

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

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

Given no output schema, the description fully documents response structure and edge cases (e.g., skipped_low_similarity, partition filter). It covers all three modes, internal filters, and fill check dependency, making it complete for agent invocation.

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

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

Schema coverage is 100% with parameter descriptions, but the tool description adds substantial meaning by explaining mode semantics, providing example slugs, detailing response structures, and linking to fill check behavior. This goes well beyond the schema baseline.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and references sibling tools like polymarket_fill_risk for custom sizing, providing 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 explicitly advises when to use each mode (no args for trending scan, event for per-event checks, topic for cross-event) and warns against trading when the fill check shows non-positive realizable edge. It also recommends the sibling tool polymarket_fill_risk for custom sizing.

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

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

Discloses detailed internals (model families, cache behavior, edge calculations, Kelly fractions, filtration rules) far beyond the annotations (readOnlyHint, idempotentHint). 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?

Well-structured with clear segments and front-loaded purpose, but the description is lengthy (multiple paragraphs). Some redundancy, e.g., repeating cache info. Could be trimmed without losing key information.

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

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

Given 9 parameters and no output schema, the description covers response structure (by_segment, fed_note, diagnostics) and explains edge calculation, filters, and assumptions. Missing output schema details but compensated by verbose explanation.

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

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

Schema covers all 9 parameters well (100% coverage). Description adds valuable nuance, e.g., explaining that min_kelly does not filter partition arbs and how min_partition_leg_kelly applies instead. This exceeds baseline of 3.

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

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

Clear verb 'scan...and return opportunities' and resource 'Polymarket markets'. Stated purpose ('what should I bet on today'). Lacks explicit differentiation from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which weakens sibling distinction.

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 'discover opportunities without paging hundreds of markets' and directs to knobs for filtering. No when-not guidance or comparison to alternatives, but the context is clear enough for typical discovery use.

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

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

The description adds significant context beyond the annotations (readOnlyHint, etc.). It explains that data comes from daily snapshots with a TTL, decay uses daily closes not intraday, how expired opportunities are handled, and the sign convention for decay. This is thorough and honest about data sourcing and computation.

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

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

The description is dense and front-loaded with the core purpose. While it is somewhat lengthy, all sentences add value. It is well-structured with clear sections for response fields and limitations, making it easy to parse.

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

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

The description is exceptionally complete given the lack of output schema. It details the three response arrays (tracked, expired, snapshot_dates) and their fields, plus limitations and interpretation notes. An agent can fully understand what to expect without additional context.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates default and max values for days and default for window, which mostly mirrors the schema. No new semantic information is added beyond what is already in the input schema descriptions.

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

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

The description clearly identifies the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It explicitly answers 'how long has this edge existed and is it shrinking?' and distinguishes itself from siblings by focusing on time-series analysis and trends, not just current edges.

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

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

The description provides clear context for when to use this tool (e.g., for historical edge analysis) and includes limitations like 60-day snapshot TTL and decay computation from daily closes. However, it does not explicitly state when NOT to use it or suggest alternative tools for other use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral detail: it walks the order book ladder, returns specific fields like slippage and verdict, explains basket mode's computation of theoretical vs realizable sum, and warns about thin legs and forced directional risk. No contradictions with annotations.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded with the purpose. It is somewhat verbose but every sentence contributes useful information. Could be slightly more concise, but the structure aids readability.

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

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

Despite no output schema, the description thoroughly explains return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict; theoretical_sum, realizable_sum, capture_ratio, thin_legs, etc.). It also covers edge cases and risks (forced directional risk, partial fill implications). The tool is complex, and the description leaves no significant gaps.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds significant extra meaning: explains the difference in `size_usd` interpretation between single-market (spend vs proceeds) and basket (settlement notional), clarifies side default behavior in basket mode, and gives default values and clamps.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with two modes (single-market and basket). It distinguishes from siblings by explicitly stating 'USE THIS before acting on any polymarket_arbitrage ... or polymarket_edges'.

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

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

The description provides explicit guidance on when to use this tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the risks (theoretical overround not capturable, partial fills creating directional risk). It also clarifies that one of `market` or `event` is required, with defaults for other parameters.

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 though readOnlyHint/openWorldHint/idempotentHint already cover safety, the description adds substantial non-obvious behavior: compatibility_codes semantics, unclassified legs never being paired, temporal_alignment null meaning, gross-vs-net fee disclosure, and skipped comparison counters. It also explains that pairing is keyword-based and not verified by a shared resolution source. This gives the agent critical interpretive context for the response.

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

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

The description is dense, organized into mode/response/safety sections, and front-loads the core purpose before caveats. However, it is quite long and packs many nested caveats and code enumerations into continuous prose, so it places a heavy reading burden on the agent; it could be trimmed without losing value.

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

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

For a tool with no output schema, the description fully covers return fields, flags, codes, edge cases, and fee implications. It even clarifies the null semantics of temporal_alignment and explains skipped_cross_type/subtype counters. An agent has enough information to call the tool in either mode and interpret the result correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds meaning by explaining that topic auto-fetches a pre-mapped event on both venues, that the two explicit parameters override the mapped sides, and that both modes run the same token-overlap matcher. This is helpful but rests on a solid schema baseline.

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

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

The description states precisely that the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, and it goes on to specify two modes and the response contents. It distinguishes itself from single-venue or generic research siblings by emphasizing cross-venue pairing and the same-question requirement. This is far beyond a tautology and gives an agent a concrete model of what the tool returns.

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 clear usage context: topic mode for pre-mapped shortcuts and explicit mode for custom kalshi_event_ticker/polymarket_event_slug pairings, and it warns that most pre-mapped topics return compatibility warnings and are not necessarily tradeable. It does not name sibling tools like polymarket_arbitrage or say when to prefer them, so it stops short of full alternative routing.

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

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

Annotations already indicate readOnly and idempotent behavior. Description adds scoping to identifier and pairing context, which is valuable beyond annotations.

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

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

Three concise sentences with no fluff. Information is front-loaded: first sentence covers core action, second explains use case, third adds scoping and siblings.

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

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

For a simple tool with one optional parameter and no output schema, the description covers input, behavior, use cases, and relationships with siblings completely.

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 the parameter with good description. Description adds real-world use cases and clarifies behavior when key is omitted vs provided, enhancing understanding.

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

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

Clearly states the tool retrieves saved values or lists keys, with concrete examples (ticker, address, research notes). Distinguishes from siblings 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 when to use ('to look up context... without re-deriving') and how to list all keys ('omit the key argument'). Mentions pairing with remember and forget, providing 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 declare readOnlyHint=true, implying no state mutation. However, description describes mark_read parameter that flags events as read, which modifies server state. This contradicts the readOnlyHint annotation. Therefore score 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?

Description is a single paragraph with 4 sentences. Each sentence contributes distinct information: purpose, data fields, filtering options, mark_read behavior, and alternative access. No redundant or extraneous content.

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

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

Despite having no output schema, the description explains the main return fields and provides sufficient context for usage: filtering, read tracking, polling suitability, and an alternative interface. All 5 parameters are addressed, and the tool's behavior is well-scoped.

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 5 parameters have schema descriptions (100% coverage). Description adds value by giving examples for type ('sec_8k'), explaining ISO timestamp for since, and clarifying effect of mark_read on subsequent calls.

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

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

Clearly states it pulls fired events from subscription feed and specifies what data each alert carries (source, citation_uri, payload). Distinguishes from sibling list_subscriptions.

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

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

Explicitly mentions filtering by type and since, setting mark_read for read tracking, and that polling works. Also provides alternative access via HTTP GET for scripts and dashboards.

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

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

Adds substantial behavioral context beyond annotations: parallel fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, return structure (grouped changes, total count, citation URIs). No contradiction with annotations (readOnlyHint, idempotentHint).

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?

Single paragraph is dense but not overly long. Front-loaded with query examples. Information is well-organized despite lack of bullet points. Could be slightly more structured, but no wasted sentences.

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

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

Despite no output schema, description details return format (changes grouped by source, total_changes, URIs). Covers all relevant behaviors: parallel calls, fallbacks, soft-fail, parameter constraints. Complete and self-contained for tool usage.

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

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

Schema covers 100% parameters. Description adds value by explaining `since` format with examples (ISO date, relative shorthand), clarifying `type` enum limitation, and showing ticker/CIK usage. Baseline 3 due to full schema coverage, but examples and context elevate to 4.

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

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

Description clearly states tool aggregates changes (SEC, news, patents) for a company in a time window. Distinguishes from sibling 'entity_profile' by specifying when to use each. Examples of queries ('What's new with X') make purpose immediately clear.

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

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

Explicitly contrasts with entity_profile for static profile use. Provides guidance on `since` format and suggests typical values. Lists data sources with fallback behavior. Lacks explicit when-not-to-use beyond the entity_profile mention.

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

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

Annotations indicate idempotent and non-destructive. Description adds behavior: key-value scoping, persistent vs 24h memory. No contradiction.

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

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

Three sentences, no wasted words. Front-loaded with purpose, then usage, then behavior. Perfectly concise.

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

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

For a simple 2-param tool with no output schema, the description provides complete context: purpose, when, how, behavior, and pairing with siblings.

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

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

Schema covers 100% of parameters. Description adds useful example keys like 'subject_property', 'target_ticker', adding context beyond schema.

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

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

The description uses specific verbs ('Save', 'reuse') and clarifies the resource (data) and scope (across conversation or sessions). It distinguishes from siblings 'recall' and 'forget' by naming them explicitly.

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?

Clearly states when to use: 'when you discover something worth carrying forward' and pairs with recall/forget. Lacks explicit 'when not to use', but the guidance is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavior: graceful degradation when GLEIF/OpenFIGI are unavailable, `unresolved` field for missing identifiers, multiple internal endpoints, and precise handling of bond issuer names. No contradictions.

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

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

The description is long but well-organized: it opens with use cases, then breaks down supported types, then explains edge cases. Every sentence adds unique value—no fluff. It's denser than ideal but the complexity of the tool justifies the length. Front-loaded with the key action ('Use FIRST').

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

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

Given the tool's complexity—two entity types, multiple identifier sources, nested logic for bonds and ISINs—the description covers all necessary details an agent needs to call it correctly. It explains return semantics (`unresolved`, `figi_candidates`), and even though there's no output schema, the description tells what to expect. No missing 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 description coverage is 100% for both parameters, yet the description adds critical semantic nuance beyond the schema. The `value` parameter gets extensive guidance: exact formats for tickers/CIKs/ISINs, the instruction to pass only the entity name (not full noun phrases) for bonds, and examples. This exceeds the schema's minimal 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 names to canonical identifiers, lists example queries, and explicitly says 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It differentiates from siblings by positioning itself as the first tool to use when you have a name but need an ID, which is distinct and memorable.

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 an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also lists supported types and describes when to use each (company vs. drug), and notes it replaces 2-3 manual lookups. No ambiguity about when to invoke 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?

The description adds substantial behavior beyond annotations: it explains that each entity is probed with ai_visibility_check, results are ranked by score, and the first entity is treated as the subject. Annotations confirm read-only, idempotent, non-destructive behavior, and the description aligns with these, providing clear operational details.

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

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

The description is three sentences with front-loaded main action, clear explanation of internal process, and a concrete use case. Every sentence contributes meaning, 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?

Given the tool's complexity (4 params, no output schema), the description adequately describes the return format (ranked list with score, confidence, signal density) and the internal mechanism. It does not mention potential performance implications of calling multiple probes, but the agent can infer this. Overall complete enough for correct selection and invocation.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining that the first entity in 'entities' is treated as the subject for narrative, and provides an example for 'context' (e.g., 'B2B SaaS'). This enriches the schema 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 states the tool compares AI visibility across multiple entities side-by-side using ai_visibility_check, ranks them, and identifies most/least recognized. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities by specifying the internal mechanism and competitive audit 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 provides a clear use case ('competitive AI-marketing audits') and an example question, implicitly guiding when to use. However, it does not explicitly mention when not to use or list alternative tools like running ai_visibility_check separately. The context is adequate but not exhaustive.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: fans out to two services, first measurement can take 5-30s, partial failures degrade gracefully with sources_failed reporting, and lists return fields. No contradiction.

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

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

The description is a single paragraph that is dense yet clear. It is front-loaded with the purpose and every sentence adds value (use cases, limitations, return details, edge cases). No 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?

No output schema exists, so description must explain return values. It does: 'Returns a summary block (is_latest, license, ...), per-advisory detail, links, and recent alternative versions.' It also covers partial failures and timeouts. Complete 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%, so baseline is 3. Description adds extra context: package name accepts scoped packages, version defaults to latest. Also clarifies that the tool returns a summary block but does not elaborate on parameter syntax beyond schema. Justifies a 4.

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

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

The description clearly states the tool's purpose as a composite check for npm packages using deps.dev and bundlephobia. It specifies the verb 'scan/check', resource 'dependency', and distinguishes from siblings (no similar tools listed).

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes ecosystem limitations (NPM only in v1) and mentions alternatives (deps.dev:version for other ecosystems). It covers when not to use and behavior on partial failures.

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 (readOnlyHint, idempotentHint, etc.) indicate safe, non-destructive behavior. The description adds valuable details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char limit with truncation and flagging, and returns character offsets and similarity scores. No contradiction with annotations.

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

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

The description is approximately 100 words, front-loaded with the core purpose, followed by usage guidance, pairing info, and technical details. Every sentence contributes value, with no repetition or fluff.

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

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

Given the tool's moderate complexity (3 params, no output schema, rich annotations), the description covers the algorithm, chunking, limits, and output content (offsets, scores). It could be more explicit about the exact return structure, but is mostly complete.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description adds an example query and mentions the character limit for 'text', but does not significantly enhance meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it performs semantic search inside a fetched record, using verbs like 'search INSIDE' and 'get back'. It provides concrete examples (SEC 10-K, article). However, it does not explicitly differentiate from sibling tools like ask_pipeworx or ask_pipeworx_grounded, though the context of 'inside a record' distinguishes it.

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 advises use when the record is too large for the prompt and pairs with ask_pipeworx_grounded. This gives a clear usage context but lacks explicit exclusions or alternatives. It does not specify when not to use (e.g., small records).

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

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

The description goes well beyond the annotations to disclose key behaviors: the requirement for a Pipeworx OAuth account, the 10/day SMS cap, the auto-disable of webhooks after 10 consecutive failures, and the one-time return of the webhook signing secret. These details are not captured by the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false) but are critical for the agent to use the tool correctly.

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 fairly long but well-structured: it starts with the core purpose, then covers requirements, type-specific details, and delivery channels. Each sentence adds value, though a minor redundancy exists in explaining the SMS cap twice (once in description and once in delivery schema). Overall, it is front-loaded with the essential purpose and progressively adds detail.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers all essential aspects: purpose, prerequisites, type-specific parameter formats, delivery options with constraints, and behavioral notes (webhook auto-disable, one-time secret). There are no gaps; the agent can fully understand how to invoke the tool and what to expect.

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

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

The schema has 100% description coverage, but the description adds significant semantic value by explaining each type's parameters with concrete examples (e.g., items:['5.02'] = officer change for sec_8k, topic:'fed' for polymarket_edge, series_id:'UNRATE' for fred_series). It also details the delivery sub-object's constraints (E.164 phone, HTTPS URL, HMAC signing). This level of detail makes the parameters understandable beyond the schema.

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

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

The description clearly states the core action: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It also distinguishes between subscription types and delivery channels, providing specific examples for each (e.g., sec_8k for SEC filings, polymarket_edge for cross-venue mispricings). This sets it apart from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly states the prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It provides detailed guidance on when to use each subscription type (e.g., sec_8k for SEC filings matching ticker+item codes, fred_series for FRED observations) and channels (feed always on, optional email/sms with limits). While it doesn't explicitly say when NOT to use this tool, the context is clear enough given the sibling tools and the examples.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these: it returns category-bucketed example questions, includes exact tool+argument shapes, and mentions that the examples are drawn from a live catalog. This provides significant additional transparency 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, consisting of approximately 4 sentences. It front-loads common aliases and the core purpose. While it includes a detailed list of categories (company financials, drugs, etc.) that partially repeats the schema's enum examples, it remains efficient and well structured.

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

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

Given the tool's low complexity (1 optional parameter, no output schema), the description is complete. It explains what the tool returns, how to use it (with/without topic), and when to use it (first-time onboarding). The return value description (category buckets with tool examples) is sufficient without an output schema.

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

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

The schema coverage is 100% (only one parameter, 'topic'). The description adds value by listing the possible topics (finance, pharma, etc.) and explaining that omitting the parameter gives a cross-category spread. This supplements the schema's description, earning a score above baseline 3.

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

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

The description clearly states that this is the onboarding entry point for an agent wanting to know what questions to ask Pipeworx. It specifies the return value (category-bucketed example questions with tool/argument shapes) and distinguishes itself from siblings by being the first tool to use when ignorant of Pipeworx capabilities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' This provides clear guidance on when to use it. It does not explicitly mention when not to use it, but the positive guidance is strong, and context with 'first' implies alternatives exist for other situations.

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 (destructiveHint=false), description adds that the row is deactivated (not deleted) and historical events remain available via recent_alerts. No contradiction with annotations.

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

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

Three sentences, front-loaded with action, then constraint, then behavior. No redundant words; every sentence adds value.

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

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

For a simple mutation with one parameter and no output schema, the description fully covers behavior, constraints, and side effects. Annotations provide safety context.

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

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

Schema covers the only parameter 'id' with description. Description mentions 'returned by subscribe' which adds context but does not significantly enhance schema meaning beyond the baseline.

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

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

The title and description clearly state 'Cancel a subscription by id.' It specifies the verb (cancel/unsubscribe) and resource (subscription by id), and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Describes ownership enforcement ('you can only cancel your own subscriptions') and contrasts with deletion by noting deactivation. Provides clear guidance on when to use and limitations.

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 behavioral nuance beyond the read-only/idempotent annotations: it discloses that could_not_verify means the check did not happen and must not be treated as evidence, and explains unsupported as covering no source. It also details the dual pipeline (SEC EDGAR + XBRL vs grounded) and the rejection of false refutation.

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

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

The description is longer than ideal but front-loads trigger phrases and each section earns its place: routing, return types, important caveat, and value proposition. No word is wasted, though it could be trimmed slightly by dropping the 'Replaces 4–6 sequential calls' marketing phrase.

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

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

For a tool with no output schema, the description thoroughly explains verdict types, the attached value and citation, reasoning, and the error semantics of could_not_verify. It also clarifies how different claim categories are handled, making it complete for an agent to decide and interpret results.

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

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

Schema covers both claim and tolerance_pct with rich descriptions (100% coverage), so the baseline is 3. The description text doesn't add parameter-level semantics beyond the schema; the tolerance_pct behavior is already documented in the schema's description.

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

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

The description opens with varied natural-language phrasings and states 'natural-language claim verification against authoritative sources.' It clearly names the verb (verify) and resource (factual claims), and distinguishes itself from sibling research/ask tools by describing a single-call pipeline that replaces 4–6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear invocation criterion. It also differentiates between company-financial claims and other claims, describing the automatic routing. However, it doesn't name alternative tools for non-claim questions, so no explicit exclusions.

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