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, idempotentHint, and openWorldHint. The description adds valuable behavioral context beyond annotations: it routes across 5,529 sources, returns pipeworx:// citation URIs, works on every tier, and makes one fast call. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: it front-loads the critical directive ('PREFER OVER WEB SEARCH'), lists supported data categories, gives examples, and explains escalation paths. No filler or redundancy.

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

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

Given the tool's broad scope and absence of an output schema, the description is remarkably complete. It covers purpose, usage contexts, alternatives, examples, and limitations (when to step up). Combined with rich annotations and a fully documented schema, it leaves no critical gaps.

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

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

Schema description coverage is 100%, with all six parameters documented (including aliases). The description itself does not add parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate; examples in the schema and description illustrate usage but don't introduce new semantics.

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

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

The description clearly states the tool's function: it routes questions to one of 5,529 tools across verified sources and returns structured answers with citation URIs. It also explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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' and 'START HERE for most questions.' It also provides when-not-to-use criteria, naming alternatives for hallucination-resistant answers (ask_pipeworx_grounded) and broad multi-part questions (deep_research), plus example queries.

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 beta status, live candidate routing, no active candidate currently, and comparison against the stable router. Adds meaningful context beyond the annotations (readOnly, idempotent, non-destructive). No contradiction with annotations. The description does not detail response format, but that is consistent with 'same response shape' reference.

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

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

Four sentences packed with necessary information: beta status, equivalence, current state, usage, and comparison purpose. No filler, though the first sentence is lengthy. Each clause earns its place, and the structure is logical.

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

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

For a beta variant of a router, the description covers what it is, when to use, current behavior, and how it relates to ask_pipeworx. It mentions the same response shape, which is sufficient given no output schema. Slightly thin on what kind of questions to ask, but that is inherited from ask_pipeworx.

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%: every parameter (question and 5 aliases) has a description. The description itself adds no parameter-specific semantics, but the schema fully documents them. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

Clearly identifies as a beta version of ask_pipeworx, a universal router with 5,529 tools. Distinguishes from siblings by beta status and candidate routing improvements, but relies on the reader knowing what 'ask_pipeworx' does. The core function (answering questions via routing) is implied rather than explicitly stated.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. Implies it is for experimental use, but does not explicitly state when NOT to use it (e.g., for production/stable needs). Mention of 'Falls back to nothing' clarifies it is a working router, not a stub.

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, openWorldHint, idempotentHint) already indicate reads, but the description adds crucial behavior: returns an explicit refusal with specific refusal_reason values, includes verbatim evidence, and explains that it only uses the tool result. It also discloses the extra LLM call cost. No contradiction with annotations — the read-only, idempotent nature aligns with 'reads' and 'fetches the data.'

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

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

Though lengthy, every sentence serves a purpose: it front-loads the core value proposition ('Hallucination-resistant answer mode'), then covers mechanics, return format, refusal reasons, use cases, and cost. No redundant or filler content; the structure is logical and efficient for the complexity.

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

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

Given no output schema, the description fully specifies the return object (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal modes. It also explains when to use it and the tradeoff vs. the sibling tool. The integration with annotations provides a complete picture for an agent to invoke correctly.

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

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

The input schema has 100% coverage: all six parameters are aliases for 'question' with descriptions. The description adds no parameter-specific details beyond the schema, so it does not exceed baseline. It doesn't explain how the question is routed or formatted beyond natural language, but the schema already handles that.

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

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

The description clearly states a specific function: a 'hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing grounded, high-stakes use and explicitly routing to 5,529 tools across 1,455 sources. The verb+scope is precise and unique.

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

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

Explicitly says when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides the alternative: 'prefer ask_pipeworx for casual lookups,' and notes the cost tradeoff ('Costs one extra LLM call'). This is clear when-to-use and when-not-to-use guidance.

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

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

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich context: account/paywall details, the 'never invented' honesty guarantee, the citation URI only present when actually fetchable, semantic excerpting, latency expectations, and the contradictions[]/gaps[] behaviors. No contradiction with annotations.

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

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

The description is long but dense with actionable information. It front-loads the account requirement and alternative tool advice early. While it could be tightened, most sentences add value (e.g., citation fetchability, hop field, latency). Minor redundancy such as repeating 'contradictions[]' could be trimmed, but overall structure is effective.

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

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

With no output schema, the description fully describes the return packet: 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]'. It also covers edge cases (gaps for news topics, citation_uri only when resolvable), depth behaviors, latency, and multi-step resolution. This is highly complete for a complex research tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds practical meaning beyond the schema: it explains the depth enum values in plain terms ('quick=3 (single hop)', 'standard=5... adds a gap-recovery hop', 'thorough=8 (paid)...') and clarifies that the question can be broad/multi-part. This earns a 4.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the mechanism: 'Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL.' It explicitly distinguishes itself from the sibling ask_pipeworx by contrasting the one-call research paradigm versus a single lookup, earning a 5.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even states the account requirement ('ACCOUNT REQUIRED') and fallback ('If you are not signed in, use ask_pipeworx instead'). This is exemplary usage guidance.

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

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

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 indicate read-only, open-world, idempotent, non-destructive. The description adds behavioral details: fans out across multiple sources, returns specific fields, and notes that patent data may soft-fail due to USPTO sunset. 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 informative and well-structured, front-loaded with example queries, but slightly verbose. Every sentence adds value, though some redundancy could be trimmed for brevity.

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 pulling data from multiple sources with potential failures, the description covers all key aspects: constrained inputs, return fields, fallback behavior (patents soft-fail), and usage context. No output schema, but return structure is sufficiently described.

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

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

Schema coverage is 100% for both parameters, but the description adds meaningful context: type only supports 'company', value must be ticker or zero-padded CIK, and names are explicitly unsupported. This exceeds the schema's brief descriptions.

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

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

The description clearly states it provides a holistic cross-source profile for US public companies, listing specific data sources and return fields. It distinguishes itself from sibling tools like resolve_entity and compare_entities by specifying when each should be used.

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: 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view.' Also specifies that names are not supported, advising to use resolve_entity first. This clearly delineates when to use 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 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds detailed behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped counters) explain when spreads are meaningful and when they are not, going well beyond annotations.

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

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

The description is long but well-structured with clear sections (modes, response, safety fields). Every sentence adds value, though some sections are dense. Given the complexity, it is appropriately scoped.

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 the response structure (leg-by-leg prices, top_spreads_pp, safety fields). It covers agent needs for interpretation and highlights real limitations of pre-mapped topics, making the description 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% with descriptions for each parameter. The description adds meaning by explaining the two modes and listing the 10 topic shortcuts, and providing examples for explicit parameters (e.g., 'KXFED-26OCT'). This adds value beyond the schema.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolution question, distinguishing it from single-venue tools like polymarket_edges. It specifies the verb (compute/comparison) and resource (spread).

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 describes two modes (topic shortcuts vs explicit tickers) with conditions for when each applies. Warns that pre-mapped topics often return warnings, so agents should not assume tradeability. Lacks explicit 'when not to use' compared to siblings, but is clear overall.

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?

Beyond the annotations (readOnly, idempotent, openWorld), it discloses graceful degradation of LEI/FIGI enrichment, the explicit 'unresolved' field instead of omission, source-labelling of identifiers, and internal cascading through multiple endpoints. These are valuable operational behaviors an agent would not otherwise know.

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

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

The description is lengthy but well-organized: query examples, purpose, usage instruction, then detailed supported types. Each section earns its place for a two-mode tool, though a few phrases (e.g., 'using resolve_entity replaces 2-3 manual lookups') are somewhat redundant with the overall message.

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

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

With no output schema, the description fully explains return values (source-labelled identifiers, unresolved list, RxCUI citation) and behavior under partial availability. It also covers input formats for both entity types and the expected result of cascading lookups, leaving few gaps for an agent to make an informed call.

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

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

The schema already documents both parameters at 100% coverage, but the description adds meaningful detail about what each entity type resolves to (e.g., CIK/ticker/LEI/FIGI for company, RxCUI/brand for drug) and clarifies accepted input examples. It doesn't add new syntax beyond the schema but reinforces and enriches the semantics.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with concrete query examples ('What's the ticker for…'). It names the resource (entity) and the specific outcome (IDs for other tools), and the mention of 'Use FIRST…' distinguishes it as an entry-point lookup tool among siblings.

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

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

It provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also enumerates supported types and input forms. However, it doesn't name alternative sibling tools or explicitly state when not to use it, stopping just short of full exclusion guidance.

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

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

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.