Giphy

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

The description adds rich behavioral context beyond the annotations: it explains the default model (Workers AI free), the optional Anthropic key usage and associated costs (BYO key, pay directly), and details the return structure (per-model score, confidence, signals, raw_response plus combined view). This goes well beyond the readOnly/idempotent hints and provides the agent with actionable expectations.

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

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

The description is compact and well-structured: first sentence states the core action and output, second sentence explains defaults and optional key, third sentence lists return fields and use cases. Every sentence earns its place with 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?

For a tool with 4 params, no output schema, and moderate complexity, the description is complete: it covers invocation details, API key handling, result format, and use cases. It provides enough context for an agent to select and invoke the tool without further research.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by clarifying the default model behavior, the necessity of _apiKey only when Anthropic is included, and in-text examples for entity and context. This enriches the schema descriptions, making the parameters more actionable.

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

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

The description explicitly states the tool's function: probing LLMs and scoring visibility. It uses a specific verb+resource ('Probe one or more LLMs... score visibility 0-100 per model') and clearly distinguishes it from siblings by emphasizing per-model visibility scoring and the default model. This makes the purpose unambiguous.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the tool. It does not explicitly mention alternatives or exclusions, but the context is sufficient to infer appropriate usage compared to sibling tools like scan_competitor_ai_presence.

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 as false, so the agent knows it's safe and idempotent. The description adds substantial value by explaining the tool's internal routing to 5,563 tools across 1,462 sources, its ability to fill arguments, and that it returns structured answers with stable citation URIs. It also clarifies that it works on every tier and is a single fast call. A slight deduction because it doesn't explicitly discuss rate limits or any other potential limitations.

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 substantial but every sentence adds value—usage guidance, examples, comparisons to siblings, and behavioral notes. It is front-loaded with the key 'prefer over web search' directive. Slightly longer than necessary for a simple tool, but the complexity and breadth of the tool justify the length.

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

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

Given this tool has 6 parameters (all aliases for one required question), 100% schema coverage, detailed annotations, no output schema, and a large sibling set, the description is remarkably complete. It covers what the tool does, when to use it, what kinds of questions it handles, its internal routing mechanism, and when to choose alternatives. There is no missing information that an agent would reasonably need.

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% coverage: each property (q, text, input, query, prompt, question) is described as an alias for 'question', and the 'question' property itself is well-documented. The description adds meaning by explaining what kinds of questions to ask, supplementing the schema with concrete examples. The examples in the schema are also provided, so the param semantics are strong. A slight deduction because the description could explicitly note that only one parameter is needed and the rest are just aliases, though this is well implied.

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 routes questions to a vast ecosystem of verified sources for authoritative structured data with citations. It gives a specific verb-resource pairing ('ask' + 'Pipeworx') and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, as well as web search.

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

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

The description provides explicit guidance on when to prefer this tool over web search (e.g., for structured data with citations), when to use it (e.g., for factual questions about real-world entities), and when to step up to alternatives (grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). Multiple examples illustrate appropriate use cases.

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

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

The annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds beyond that: it explains the beta nature, that no candidate is currently active (as of a specific date), and that the tool is a full working router with experimental edge. This is useful context not covered by annotations.

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

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

The description is compact and front-loaded with the most critical information: it's a beta version of the universal router. Every sentence adds value—explaining the relationship to ask_pipeworx, the experimental nature, the current status, and usage guidance. No wasted words.

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

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

Given the tool's simplicity (a single required parameter, no output schema, and rich annotations), the description is complete. It explains the purpose, usage context, and current state, leaving no significant gaps. The annotations cover safety, and the schema covers input fully.

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

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

Schema coverage is 100%, so the schema already documents the required 'question' parameter and its aliases. The description does not add new parameter-level details, but given full schema coverage, a baseline of 3 is appropriate. The description is elevated to 4 because it clarifies that the tool accepts a natural language question and that the aliases are exactly equivalent, reinforcing the schema's documentation.

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

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

The description clearly states that this is a beta version of the same universal router as ask_pipeworx, with the same 5,563 tools and arguments. It distinguishes itself from the stable version by indicating it may have candidate routing improvements enabled, and it notes that currently no candidate is active, so it matches the stable version exactly. This is a specific verb+resource with clear sibling differentiation.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains that results are compared against the stable router to decide what merges, and it clarifies that it falls back to nothing—it is a full working router, just the experimental edge. This tells the agent when to use it and what to expect in terms of experimental nature.

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 significant value beyond these: it explains the exact refusal mechanism with 5 specific refusal_reason values, the return format with {answer, evidence, confidence, source, fetched_at, refusal_reason}, and the cost implication (one extra LLM call). No contradictions with annotations.

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

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

The description is a single paragraph that front-loads the most critical information (hallucination-resistant, high-stakes reads) and then efficiently covers mechanism, return format, use cases, and cost trade-off. Every sentence earns its place with no redundancy.

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

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

Given the tool's complexity (routing across 5,563 tools with 1,462 sources, refusal mechanism, cost trade-off), the description is remarkably complete. It explains what the tool does, when to use it, what it returns on success and failure, and the cost implication. No output schema exists, but the description explicitly lists the return fields, which is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the question parameter accepts multiple aliases (q, text, input, query, prompt) and gives context on how the question is used ('routing...fills arguments, fetches the data'). This is useful but doesn't go beyond what the schema already describes.

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 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism: it extracts answers using only the tool result, returning explicit refusals when data doesn't directly answer. This distinguishes it from ask_pipeworx and other sibling tools.

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

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

Explicitly tells when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). Also states when NOT to use it: 'prefer ask_pipeworx for casual lookups' due to extra cost.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses extensive behavioral details: fan-out to category-specific data packs, resolver confidence mechanics, parent-event extraction, news fallback behavior, low-confidence short-circuiting, and cancellation-rule parsing. It even warns agents to inspect match confidence before trusting analysis, which goes far beyond annotation hints.

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

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

The description is long but well-organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.). It is front-loaded with purpose and use cases, and while dense, each section contributes meaningful behavioral context; still, the length keeps it from being maximally 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?

With no output schema, the description carries the full burden of explaining return shapes and edge cases. It covers result.market, result.analysis, result.evidence, resolver contract, parent-event data, news fallbacks, wide-spread warnings, and resolution-rule risk, making it highly complete for the tool's complexity.

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

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

The input schema already documents all three parameters with 100% coverage, including depth and include_raw. The description adds no new parameter-specific semantics beyond what the schema provides (e.g., it doesn't elaborate on depth behavior), so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists concrete use cases ('should I bet on X', 'what does the data say about Y', or 'is there edge in Z'), clearly distinguishing it from generic ask/research tools among the 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?

The description explicitly frames when to use the tool with the 'Use for...' sentence. It also details blocking conditions (low_confidence_match, market_closed_or_inactive) that prevent misuse, but it stops short of naming sibling tools or stating explicit 'do not use when...' alternatives, so it warrants a 4 rather than a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the data source (SEC EDGAR/XBRL for companies), how off-calendar fiscal years are handled, and that results are sorted by primary metric. This significantly enriches behavioral 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?

Despite its length, every sentence provides value—trigger examples, entity count limits, data specifics, and scheduling behavior. The information is front-loaded with the purpose before diving into details.

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

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

The tool has no output schema, but the description compensates by explaining return characteristics: paired data with citation URIs, sorted by primary metric, and the data fields per type. This gives the agent a complete mental model for selection and invocation.

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

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

Although the schema already documents the two parameters with full coverage, the description adds critical semantics: for type='company' it specifies exactly which financial metrics are retrieved, and for drug it specifies FAERS counts. This helps the agent anticipate the tool's output based on chosen values.

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

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

The description opens with concrete trigger phrases ('Compare X and Y' / 'X vs Y') and clearly states the tool performs side-by-side comparisons of 2–5 entities. It explicitly distinguishes itself from sequential single-pack lookups, making its purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. It also breaks down use cases by type (company vs drug), eliminating ambiguity about applicable scenarios.

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

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

Annotations already declare readOnlyHint=true (non-destructive), openWorldHint=true (non-deterministic), and idempotentHint=true (safe to retry). The description adds essential behavioral context: it can take 15-60s (up to ~90s for thorough), returns gaps[] for unanswered facets, never invents findings, and includes contradictions[] for standard/thorough depths. It explains hop fields and citation URIs with fetchability guarantee. This far exceeds what annotations alone convey.

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

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

The description is dense with information but front-loaded with the most critical preconditions (account requirement, alternative for non-signed-in users). Every sentence serves a purpose—account prerequisites, behavioral promises, depth behavior, limitations, iteration details. However, it could be slightly more scannable by grouping the output packet description and side effects more distinctly; it runs a bit long.

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 (2 params, one with 3 enum values, no output schema, 32 sibling tools), the description is remarkably complete. It covers prerequisites, output structure (findings packet with fields), edge cases (empty gaps[], contradictions[]), performance expectations, and iteration behavior across depths. The absence of an output schema is compensated by the detailed description of what is returned.

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

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

Schema description coverage is 100%, so the schema already defines formats and constraints cleanly. The description adds rich semantic context: explanation of the depth enum (quick=3 facets, standard=5 with gap recovery+contradictions, thorough=8 with iterative chasing), and reinforces that broad/multi-part natural language questions are the expected input. This turns mechanical parameter definitions into actionable usage guidance.

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

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

The description precisely states the tool performs 'Grounded multi-source research' across Pipeworx's structured data sources, contrasting it with open-web search. It specifies the verb (research/decompose), resource (Pipeworx structured data sources), and the parallel tool invocation mechanism, clearly distinguishing it from the sibling tool ask_pipeworx.

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

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

The description provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For BREAKING or colloquial CURRENT-NEWS...prefer ask_pipeworx'), and an alternative tool ('use ask_pipeworx instead' for those not signed in). It also notes account requirements and limits on paid features, giving the agent clear decision criteria.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds useful behavioral details about return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'no second schema lookup needed.' This goes beyond the annotations and helps the agent understand what to expect.

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

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

The description is moderately long but each sentence contributes value: purpose, usage context, domain list, return details, and when-to-use priority. It is well-structured and front-loaded with the core purpose. Slightly dense but not wasteful.

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

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

Given the tool's complexity (6 params, no output schema in structured data), the description covers the key aspects: what it does, when to use, what it returns, and an example of query style. It does not explain edge cases (e.g., no matches), but overall it is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already fully explains all parameters, including aliases for 'query'. The description does not add additional parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Find tools') and resource ('by describing the data or task'). It distinguishes itself from sibling tools by positioning itself as the first step for exploration, and the list of domains (SEC filings, financials, FDA drugs, etc.) provides concrete context.

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: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance and an alternative (calling a specific tool directly).

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

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

Beyond the annotations (readOnly, idempotent, non-destructive, open-world), the description reveals significant behavioral details: it fans out in one parallel call, includes a patent API sunset with soft-fail behavior, uses a GDELT→GNews fallback for news, and returns specific structured fields. This is far more transparent than the annotations alone.

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 front-loaded with a clear purpose and user intents. Each subsequent sentence adds substantive detail (data sources, return fields, fallbacks, unsupported inputs). It is well-structured despite its length, though it could be tightened by removing some redundant examples.

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 accounts for what the tool returns: CIK, company name, recent filings (with URIs), fundamentals (LATEST 10-K values), patents, news mentions, and LEI. It also covers input restrictions, fallback behavior, and alternatives. For a complex federated-profile tool, this is exceptionally complete.

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

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

The schema already covers both parameters 100% (type enum company; value ticker/CIK/name-not-supported). The description repeats the value format and even uses the same phrase "use resolve_entity first if you only have a name." It adds only concrete examples ("AAPL", "0000320193"), which is helpful but marginal 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 a specific verb+resource: "full cross-source profile of a US public company in ONE parallel call." It provides multiple user phrasings ("Tell me about X", "research Acme", "brief me on Tesla") and enumerates the exact data sources returned (SEC EDGAR, XBRL, USPTO, news, GLEIF). This distinguishes it from siblings like compare_entities or resolve_entity.

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

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

Explicit usage guidance is given: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also names an alternative for unsupported inputs: "use resolve_entity first if you only have a name." These clear when/when-not instructions are strong.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds value by explaining what gets deleted (previously stored memory) and why (stale context, done task, sensitive data). It does not contradict the annotations and provides useful behavioral context beyond the structured hints.

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

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

The description is two sentences, front-loaded with the core action, and every word contributes to understanding purpose and context. It is concise without being under-specified.

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 parameter, full schema coverage, and strong annotations, the description is complete. It explains the action, when to use it, and how it relates to sibling tools, leaving no significant gaps.

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

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

The schema already covers the single 'key' parameter at 100% coverage with a description 'Memory key to delete.' The tool description simply restates 'by key' without adding new semantics, so the baseline score of 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key' with a specific verb and resource, clearly distinguishing it from sibling tools like remember and recall. It also names those siblings directly, reinforcing its unique role.

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

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

Provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also instructs to 'Pair with remember and recall,' giving context on alternatives without needing 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the tool's behavior: it fetches the page, extracts key fields, and produces a markdown output. This adds valuable process context without contradicting the annotations.

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

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

The description is three sentences, front-loads the core purpose, and then adds output details and use cases. Every sentence contributes value, with no filler or unnecessary 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?

For a tool with no output schema, the description clearly states the return format ('single text blob') and covers process, use cases, and safety profile through annotations. It is sufficiently complete for an agent to understand what the tool does and when to invoke it.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description does not add meaningful parameter semantics beyond what the schema already provides; it only subtly aligns 'any URL' with the url parameter and 'key links' with max_links.

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

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

The description uses a specific verb ('Generate') and a clear resource ('llms.txt for any URL'), and goes on to explain the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This distinctly positions the tool against siblings such as ai_visibility_check or scan_competitor_ai_presence, which serve different purposes.

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 'Useful for:' section gives concrete scenarios like getting a client's site indexed by AI, drafting llms.txt for a project, or auditing competitor visibility. This provides clear context on when to use the tool, but does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, so the safety profile is covered. The description adds the caller scoping ('the caller's active subscriptions') and a return field list, which is useful but not extensive behavioral detail. No additional constraints like pagination or rate limits are disclosed.

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 with no filler. First sentence states purpose and return format; second sentence gives usage guidance. Highly efficient.

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

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

For a simple read-only list tool with one optional parameter, the description is complete: it states what it does, what it returns, and when to use it. The lack of an output schema is compensated by listing return fields. Minor omissions like pagination are acceptable given the tool's simplicity.

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

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

The schema describes the only parameter (include_inactive) with 100% coverage. The description does not elaborate on it, but the schema is clear. Baseline 3 is appropriate since the schema carries the meaning.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe/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 provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies using it before subscribing or unsubscribing, giving clear context. It doesn't explicitly name alternatives, but the context is 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?

Beyond the annotations (which are generic false hints), the description discloses specific behaviors: rate-limiting ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token flow for follow-up, and the internal processing ('Team reads digests daily and signal directly affects roadmap'). This is rich, non-obvious behavioral context.

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

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

The description is long but every sentence provides essential guidance: purpose, exact use cases, exclusions, claim_token mechanics, rate limits, and quota impact. It is front-loaded with the main verb and resource, and the structure flows logically from what to when to how. 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 complexity (multiple feedback types, optional context object, token-based follow-up, no output schema), the description fully covers what it does, when to use it, what inputs are misleading, what returns occur, and operational constraints. No significant gaps remain.

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

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

The input schema already provides 100% coverage with detailed descriptions for each parameter, so the baseline is 3. The description adds extra operational guidance, such as not pasting the end-user's prompt into the message, and correctly demonstrates how to use claim_token for follow-up queries ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). This exceeds the schema's raw definitions.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team about broken, missing, or needed things. It uses a specific verb and resource ('Tell the Pipeworx team') and distinguishes itself from all siblings by being the only feedback-dedicated tool, with explicit categories for feedback types.

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

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

The description provides explicit when-to-use scenarios ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and clearly excludes other MCP servers ('if the tool came from a different MCP server... file it with that server instead'). This directly guides the agent away from inappropriate 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?

Beyond the annotations (readOnly, idempotent), the description discloses that data is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This adds behavioral context about freshness and privacy that annotations do not cover.

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

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

The description is about 80 words, front-loaded with the core purpose, and uses bullets to organize use cases. Every sentence adds either purpose, output details, use-case guidance, or data provenance, with no filler.

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

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

For a read-only trend query with one optional parameter and no output schema, the description covers the return content (top tools, top packs, call volume), the data format (pack, tool, count), staleness, and use cases. This is sufficient for an agent to select and invoke the tool without further documentation.

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

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

The schema already documents the window enum at 100% coverage, but the description adds interpretive meaning: shorter windows surface what's hot right now, longer windows show steady-state demand. It also confirms 24h as default, which is an extra semantic layer beyond the schema.

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

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

The description opens with a specific question 'What other AI agents are calling on Pipeworx right now' and clearly states it returns top tools, top packs, and total call volume. This distinguishes it from sibling tools like discover_tools by focusing on aggregate usage trends. The verb 'Returns' and resource are explicit.

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

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

The description provides three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical choices, and checking alignment with agent needs. It also explains window semantics for choosing 24h vs 7d vs 30d. However, it does not explicitly name exclusions or alternatives among siblings, so it falls slightly short of full 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?

Even with annotations declaring readOnlyHint=true and destructiveHint=false, the description adds extensive behavioral context: it explains what the tool does with signals (fill check, 'do not trade it'), filtering logic (partition filter, placeholder slug removal), and edge cases (skipped_low_similarity). These details are not in the annotations and significantly enhance transparency beyond safety hints.

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

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

The description is quite long, but it is well-structured with clear sections (modes, semantic anchor, partition filter, fill check) and every sentence contributes to understanding the complex behavior. It is front-loaded with the main purpose and usage. Slight over-length prevents a 5, but it remains highly readable and purposeful.

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

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

With no output schema, the description fully explains the response structure ('opportunities[]... partition_check{...}') and includes fill check details, cutoff thresholds (>3pp, ≥0.30 Jaccard), and null-return conditions. It covers both normal cases and edge cases, making it self-sufficient for an agent to invoke and interpret results correctly.

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

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

The input schema already has 100% coverage for both parameters, but the description goes far beyond: it provides concrete example slugs ('fed-decision-may-2026'), explains the semantic difference between event and topic modes, and clarifies how each mode affects the scan. This adds meaning beyond the schema's simple type/description fields.

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

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

The description opens with a clear, specific statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by naming its unique method (monotonicity + partition checks) and offering three distinct modes (trending_scan, event, topic). This makes the tool's purpose unmistakable.

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

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

Usage is explicitly documented: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also gives clear recommendations ('event (recommended for a specific market)') and an explicit alternative ('For custom sizing use polymarket_fill_risk'). This goes beyond mere description to guide tool 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond this by detailing model families, edge metrics, response segmentation, tradeable-edge knobs, the 24h-move warning, Fed bets exclusion, and 1-hour caching at the KV level. It fully exposes output behavior 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 long but tightly structured with clear section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and every sentence contributes substantive detail. It is front-loaded with the purpose and remains scannable despite its length, fitting the complexity of a 9-parameter tool with no output schema.

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

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

The description fully compensates for the absent output schema by enumerating the response structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and behavioral caveats. It also explains why segments may be empty via diagnostics, leaving little ambiguity for the caller.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by grouping min_liquidity/max_spread_pp as 'TRADEABLE-EDGE KNOBS' and explaining why min_kelly never filters partition_overround opportunities while min_partition_leg_kelly applies per-leg. This supplements the already-detailed schema descriptions.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states what the tool does and distinguishes it from brute-force market paging or generic scanning, with the situational tagline 'what should I bet on today.'

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

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

It gives clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This implies use for opportunity discovery rather than manual scanning, but it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail: snapshots written only on cache-miss causing gaps, history bounded by a 60-day TTL, decay computed from daily closes not intraday, and the semantics of expired opportunities (closed, resolved, arbed away). This goes well beyond the annotation safety profile.

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

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

The description is well-structured into purpose, args, response, and limits sections. Although long, each sentence earns its place by explaining response fields, edge direction signing, and data caveats—especially valuable given there is no output schema. It is appropriately sized for a telemetry tool with this 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?

With no output schema, the description fully documents the response structure (tracked[], expired[], snapshot_dates[]) and field meanings, including trend classification, decay_pp_per_day, lifespan_days, and how edge_pp_net is signed. It covers data gaps, TTL, and calculation methodology, making it complete for a read-only telemetry 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 clear descriptions for both days (default 14, clamp 2-30) and window (allowed values and default). The description reinforces these and adds context that window is a 'snapshot family' and states max 30, which is a slight addition, but mostly repeats schema 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 purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly answers 'how long has this edge existed and is it shrinking?' It distinguishes itself from its likely sibling polymarket_edges by emphasizing historical tracking rather than current edge values.

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 a strong use case by contrasting fresh vs. 3-week-old wide edges, implying this tool is for assessing edge persistence and decay. The LIMITS section offers practical constraints (TTL, snapshot gaps) but no explicit 'use X instead' alternative is named, leaving room for slight ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral depth: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and warns about the risk of partial basket fills converting an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is front-loaded with a one-sentence summary, then structured into SINGLE-MARKET and BASKET modes. It is long but every sentence adds critical information (mode requirements, output fields, usage directive). No filler or repetition; the length is justified by the tool's complexity.

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

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

With no output schema, the description must enumerate return values, and it does: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk for basket. It also explains the meaning of `size_usd` in both modes and the verdict categories. The description is self-sufficient for an agent to know 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% coverage, so baseline is 3, but the description goes beyond: it explains the mode-dependent meaning of `size_usd` (max spend on buys vs target proceeds on sells vs settlement notional S in basket), the default for `side`, and the requirement that `market` or `event` should be provided. This adds significant semantic value.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade feasibility/risk check. It also distinguishes two modes (single-market and basket), making the purpose unambiguous.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' — an explicit when-to-use directive. It also explains the rationale (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), giving clear context for choosing this tool over alternatives.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses significant behavioral details: compatibility_warning fires under two specific conditions, temporal_alignment indicates whether calendar periods match, and skipped_cross_type/subtype counters explain dropped comparisons. This adds rich context about what the tool checks and how it reports incompatibilities, exceeding what annotations alone 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 long and dense, but every sentence serves a purpose: core definition, modes, response format, safety fields, and a cautionary note. It is structured as a single paragraph but flows logically; it could be tightened with bullet points, but the density is justified by the tool's complexity.

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

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

With no output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spread[], compatibility_warning, temporal_alignment, skipped counters). It covers both normal and failure conditions, making the tool's behavior predictable even without a formal output schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds interaction semantics: it explains that topic auto-fetches a pre-mapped event, while kalshi_event_ticker and polymarket_event_slug override the mapped sides. This clarifies the mode-based relationship between parameters, which is not immediately obvious from the schema alone.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes the tool from siblings like polymarket_arbitrage by focusing on cross-venue comparison for the same resolving question, and outlines two concrete modes (topic shortcuts and explicit tickers).

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

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

The description provides explicit when-to-use context: it explains that the spread is a real signal only when bet shapes are equivalent, and when they aren't, 'the tool says so.' It also includes a clear warning that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return compatibility_warning, guiding users to not expect arbitrage. No explicit alternatives are named, but the conditions for not using the spread as a signal are strongly 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, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral context by enumerating the return fields (title, URL, rating, image URLs), which complements the annotations and gives the agent an idea of what to expect.

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 efficient sentence that front-loads the main action and includes an example and return values. Every word is informative, with 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 simplicity (one optional parameter, no required fields, output schema present), the description fully covers purpose, filtering option, and return structure. The presence of an output schema means return values are already documented, and the description adds value without being verbose.

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 for the single parameter 'tag' is 100%, with a clear description and example. The description's mention of tag filtering also reinforces its purpose, but it does not add additional semantic detail beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Get') and resource ('random GIF'), and explicitly mentions optional filtering by tag. The word 'random' effectively distinguishes it from sibling tools like search_gifs and trending_gifs, which have different purposes.

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

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

The description implies when to use this tool: when a random GIF is needed, with optional tag filtering. It does not explicitly contrast with alternatives such as search_gifs or trending_gifs, but the random selection nature provides sufficient context for basic usage without requiring 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 mark it readOnly and idempotent. The description adds valuable context about scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID),' which goes beyond annotations. It also clarifies the dual mode of 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 three well-structured sentences with no filler. The main action is front-loaded in the first sentence, and scoping and companion tools are efficiently mentioned without redundancy.

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

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

The description covers purpose, usage, scoping, and companion tools, which is complete for a simple tool with one optional parameter. It does not mention behavior for missing keys, but given the annotations and schema, this is a minor gap.

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 fully describes the single optional 'key' parameter with 100% coverage. The description echoes this behavior ('omit the key argument') and adds the connection to 'remember,' but it doesn't add substantial new semantic meaning beyond what the schema already provides.

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

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

The description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument),' which is a specific verb+resource. It also distinguishes from sibling tools by naming remember and forget and their roles.

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 to look up context the agent stored earlier' and provides concrete examples like 'user's target ticker, an address, prior research notes.' It also names alternatives by saying 'Pair with remember to save, forget to delete.'

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, but the description states that setting mark_read:true flags returned events read, which mutates read state. This directly contradicts the read-only annotation, so the score is 1 per the rubric.

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 four sentences with no fluff. It front-loads the core purpose, then covers return format, filtering, side-effect, and alternative access in an efficient, well-structured manner.

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 return fields (source, citation_uri, raw payload), covers all parameter semantics with examples, and discusses polling behavior and alternative access. It is complete for a read-oriented retrieval 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 the schema already describes each parameter. The description adds value with example values ('sec_8k'), format clarification (ISO timestamp), and explains the side-effect of mark_read, going beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It explains the returned alerts carry source, citation_uri, and raw payload, distinguishing it from sibling tools like list_subscriptions or recent_changes.

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

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

The description explains filtering by type and since, notes that polling works fine, and provides an alternative REST endpoint for scripts/dashboards. This gives clear when-to-use context, though it doesn't explicitly contrast with sibling tools.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals significant behavioral details: it fans out to multiple external APIs in parallel, uses GDELT with GNews as fallback on rate limits or 5xx, acknowledges the PatentsView API sunset and resulting soft-fail, and describes the return shape (changes[] grouped by source, total_changes, pipeworx:// citation URIs). This adds real transparency 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 dense but every sentence earns its place: user intents, source fanout, fallback behavior, `since` syntax, return structure, and the alternative tool. It is front-loaded with example queries and avoids 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 multi-source complexity and absence of an output schema, the description adequately covers sources, fallbacks, failure modes, input formats, return values, and the distinction from entity_profile. It is self-contained for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter guidance already present in the schema (ISO date vs. relative shorthand, ticker vs. CIK, only 'company' supported) without adding substantive new meaning. The extra context about sources is behavioral, not parameter-specific.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with concrete user intents ('What's new with X', 'updates on Acme'). It specifies the resources targeted (SEC EDGAR, GDELT/GNews, USPTO) and explicitly differentiates it from entity_profile, a direct sibling, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool vs. the alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also provides practical guidance on the `since` parameter ('Use "30d" or "1m" for typical monitoring') and explains the fallback behavior, giving the agent clear selection and invocation context.

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

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

The description adds meaningful context beyond the annotations: storage as a key-value pair scoped by identifier, persistence differences for authenticated vs anonymous sessions (24 hours), and cross-session reuse. It does not contradict the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). Minor gap: it doesn't state whether writing an existing key overwrites the value, but the idempotent hint partially covers this.

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 four sentences long, front-loaded with the core purpose and followed by usage, storage semantics, and pairing guidance. Every sentence adds value, though some redundancy exists between 'across this conversation or across sessions' and the subsequent authentication/retention detail. It's structured and readable, but slightly more verbose than strictly necessary.

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

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

Given the simple two-parameter schema with full descriptions and strong annotations, the description covers all essential aspects: purpose, when to use, storage behavior, retention policy, and complementary tools. No output schema is needed, and no critical information is missing for the agent to invoke this tool effectively.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds extra meaning by explaining that the key-value pair is scoped by the agent's identifier and giving real-world examples (resolved ticker, target address) that illustrate how to use the key and value. This elevates it slightly above just repeating schema information.

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

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

The description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource, and distinguishes itself from sibling tools 'recall' and 'forget' by explicitly pairing with them. This is a clear, specific purpose that leaves no ambiguity about what the tool does.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also names the alternative/complementary tools ('Pair with recall to retrieve later, forget to delete'), giving the agent clear direction on when to use this tool versus others.

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 behavioral context beyond annotations: it explains graceful degradation for LEI/FIGI enrichment when services are unavailable, the internal cascading through multiple lookups, and how unresolved identifiers are explicitly marked rather than omitted. No contradiction exists.

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

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

The description is thorough but slightly wordy, with some technical details that could be condensed (e.g., the full identifiers list for company type). However, it front-loads example queries and the core purpose, making it easy to scan. Every sentence adds value, but brevity could improve.

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

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

Given that there is no output schema, the description compensates by explaining return format (identifiers with source labels, explicit unresolved field). The tool has only 2 parameters with 100% schema coverage and simple validation (enum for type). The description explains graceful degradation and replaces manual lookups, providing full context for the 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%, so the schema already documents both parameters. The description adds meaning by explaining input formats ('accepts ticker, CIK, ISIN, or company name') and example values for each type. However, it does not explicitly map which parameter-specific behaviors are covered, so a 4 is appropriate rather than 5.

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

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

The description starts with concrete example queries and clearly states it resolves names to canonical identifiers. It explicitly lists two entity types (company, drug) with their specific identifier systems, making the purpose immediately clear and distinguishable 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID', setting clear usage priority. It also implies when not to use (if you already have an ID), and the sibling context shows many tools like compare_entities that accept IDs, making this the prerequisite step.

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 useful behavioral context beyond that: it discloses the internal probing mechanism, ranking logic, and the return structure (ranked list with score, confidence, signal density). This gives the agent a clear model of the tool's side effects and output.

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

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

The description is three sentences, front-loaded with the primary purpose, and includes essential usage context and output details without unnecessary fluff. Every sentence earns its place.

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

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

Despite no output schema, the description clearly states it returns a ranked list with score, confidence, and signal density per entity. It also covers the input semantics, internal behavior, and use case. With strong annotations and a moderate-complexity tool, this is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema: it explains that the first entity in the array is the 'subject' and the rest are competitors, and clarifies that specifying 'anthropic' in models requires an API key. This enriches the parameter understanding beyond the field descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and identifies the most/least recognized. This specific verb+resource combination distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides clear context for when to use the tool: competitive AI-marketing audits, with an example question. It implicitly separates this from single-entity checks by referencing ai_visibility_check internally, but does not explicitly exclude alternatives or mention when not to use it.

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

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

The description adds significant behavioral context beyond the annotations: it warns about a 5-30s first measurement from bundlephobia, explains graceful degradation via 'sources_failed', and clarifies the NPM-only limitation in v1. This complements the readOnly and idempotent hints without contradiction.

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

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

The description is dense but every sentence earns its place: it covers purpose, usage, return structure, failure behavior, and latency in a compact, well-organized format. The use of em-dashes and semicolons keeps it scannable despite its length.

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

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

Despite the lack of an output schema, the description enumerates all return fields, describes partial failure behavior, and notes the latency edge case. It also names the external services and ecosystem boundaries, making the tool's behavior fully understandable in 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?

The input schema already fully documents both parameters (package and version) with clear descriptions and an example. The description does not add any additional parameter-level semantics beyond restating the NPM ecosystem, so the baseline of 3 applies given 100% schema coverage.

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

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

The description opens with a concrete, specific purpose: 'Composite "should I add this npm package to my project" check in ONE call'. It names the exact resources (deps.dev, bundlephobia) and data points (license, advisories, bundle size, etc.), making it unmistakably distinct from sibling tools like scan_competitor_ai_presence.

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

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

Explicit guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states a clear exclusion for non-NPM ecosystems and points to deps.dev:version as an alternative, which demarks when not to use this tool.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds return content (title, URL, rating, multiple image sizes), providing useful context beyond annotations. No rate limits or other behavioral nuances are mentioned, but the added return info earns it a middle score.

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

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

The description is two sentences long, front-loaded with the core action, and every word adds value. It is concise and well-structured without redundancy.

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

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

With an output schema present and annotations declaring read-only/idempotent behavior, the description covers the essential purpose and return fields. It does not need to explain return structure in detail, so the description is adequately complete for this simple 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%, with both query and limit fully documented. The description does not add parameter-specific meaning beyond what the schema already provides, so it stays at the baseline of 3.

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

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

The description clearly states "Search Giphy for GIFs by keyword," specifying the verb (search), resource (Giphy), and method (by keyword). This distinguishes it from siblings like random_gif and trending_gifs, which serve different Giphy use cases.

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

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

The description implies usage for keyword-based GIF searches but does not explicitly mention alternatives or exclusions. It lacks any reference to when to use this tool versus random_gif or trending_gifs, so guidance is only implied through the clear purpose.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and has a 200K char cap with truncation flagged. This greatly exceeds what annotations provide.

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

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

The description is three sentences, front-loaded with the core purpose, then usage justification, then technical implementation details. Every sentence contributes distinct value without redundancy or filler.

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

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

Given there is no output schema, the description sufficiently explains what the agent gets back (top-N passages with offsets and similarity scores), the truncation cap, and how it integrates with ask_pipeworx_grounded. This is a complete picture for a semantic search tool with non-trivial behavior.

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

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

Schema coverage is 100%, but the description adds useful context beyond the schema: examples of valid text inputs (SEC 10-K, article, long tool result), clarifies the 200K character cap, and reinforces the query-as-natural-language concept with examples in the schema. Limit is fully specified in the schema, so no extra credit needed there.

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

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

The description clearly states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings like ask_pipeworx_grounded by emphasizing it searches within already-pulled text rather than querying a broader system, and it provides concrete examples (SEC 10-K body, article).

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

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

It gives explicit guidance: 'Use when the record is too big to cram into the prompt' and directly names the alternative/companion tool ask_pipeworx_grounded, explaining how to pair them. This clearly communicates when to choose this tool over alternatives.

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

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

Beyond annotations (readOnly=false, idempotent=true), the description discloses account requirements, persistence limitations, feed delivery behavior, and SMS verification/caps. It also mentions the return of the subscription id. However, it omits webhook delivery entirely (including the one-time signing secret and auto-disable behavior), though the schema covers that. Since annotations are present and the description adds meaningful behavioral context, a 4 is appropriate rather than 5.

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 it is front-loaded with the primary purpose and then systematically covers requirements, types, and delivery channels. Every sentence carries useful information; no filler or redundancy. It could be improved with bullet points for the type examples, but the current structure is acceptable for the information density. A 4 reflects efficient, purposeful writing.

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

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

For a tool with three parameters, nested objects, and five enum types, the description covers most critical aspects: account requirements, return value, type examples, and delivery options. It omits webhook from the description text and does not provide examples for patent_grant and clinical_trial, but the schema's rich descriptions compensate for these gaps. Overall, the description is sufficiently complete for effective tool selection and invocation, though not exhaustive.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond by providing concrete examples for three of five types (sec_8k with item codes, polymarket_edge with topic, fred_series with series_id) and explaining delivery channel semantics (email/sms JSON formatting). It does not cover patent_grant or clinical_trial in the description, but the schema already documents those. The added examples and delivery details justify one point above baseline.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb+resource combination that clearly distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. It also states the return value (new subscription id) and enumerates supported subscription types, leaving no ambiguity about the tool's core function.

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

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

The description provides substantial usage context: requires a Pipeworx OAuth account (anonymous + BYO cannot persist), explains the always-on feed with retrieval methods, and details optional delivery channels with prerequisites (verified phone, 10/day SMS cap). It does not explicitly name alternatives or when-not-to-use cases, but the context and sibling names make the appropriate use clear. A 4 is warranted for strong contextual guidance without explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations by explaining the output structure (category-bucketed example questions with exact tool + argument shape) and that results are drawn from the live catalog of thousands of tools. This helps the agent understand what to expect without needing an output schema. No contradiction with annotations.

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

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

The description is longer than necessary but well-structured: it opens with example user phrasings to help trigger the tool, then explains what it returns and how to use the optional parameter. Every clause serves a purpose, though the list of trigger phrases could be trimmed. Front-loaded content helps the agent quickly identify use cases.

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

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

Despite lacking an output schema, the description fully explains return format, data source, and parameter usage. It covers the tool's single choice (omit or topic) and even mentions it helps learn meta-tools. For a simple, read-only tool with one optional parameter, this is complete and self-contained.

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

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

Schema description coverage is 100%, with the `topic` parameter already well-documented (enum values and omit-for-spread behavior). The tool description adds no new parameter semantics beyond what the schema provides—it merely repeats 'focus' and examples like 'finance', 'pharma', 'betting' which are already in the schema. Baseline 3 is appropriate when schema fully covers parameter meaning.

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

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

The description clearly states it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by specifying it teaches how to call meta-tools like ask_pipeworx, entity_profile, and compare_entities, not just discover tools. The verb+resource is specific: suggest example questions for what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides alternative usage: call with no arguments for full spread or pass topic to focus. This gives clear when-to-use guidance and differentiates from sibling tools like discover_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 declare read-only, idempotent, and non-destructive behavior, so the description does not need to repeat safety traits. It adds value by specifying the return contents (title, URL, rating, multiple image sizes), which sets expectations beyond the schema. No contradictions found.

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, direct sentence that begins with the action verb and clearly states the resource and return contents. It has no filler or redundant information, making it extremely concise and well-structured.

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

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

For a simple read-only tool with one optional parameter, strong annotations, and an output schema, the description is fully adequate. It explains what the tool does and what is returned, leaving no critical gaps for an agent to invoke it correctly.

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

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

Input schema covers 100% of the one parameter (limit) with clear range and default, so the description does not need to add parameter details. The mention of 'multiple image sizes' pertains to output rather than parameters, and the description does not enhance parameter 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 it retrieves currently trending GIFs from Giphy, using a specific verb and resource. It distinguishes itself from sibling tools like search_gifs and random_gif by focusing on the 'currently trending' scope, making the purpose unambiguous.

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

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

The description implies usage for trending GIFs but does not explicitly mention alternatives or when-not-to-use. Sibling tools like search_gifs and random_gif are not referenced, so guidance is only implied through the phrase 'currently trending'.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description reveals key behavioral traits: ownership enforcement and soft-delete semantics ('row is deactivated, not deleted'). This adds significant context about side effects and data preservation, which is crucial for an agent deciding to invoke the tool.

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

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

Two sentences, front-loaded with the action, and every clause adds value—ownership, deactivation, and data availability. There is no redundancy or filler.

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

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

For a single-parameter tool with an idempotent annotation, the description covers purpose, behavioral constraints, and post-condition (historical events remain accessible). It is self-contained and sufficient for an agent to invoke correctly 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 already fully describes the id parameter (uuid returned by subscribe). The description adds the ownership constraint, clarifying that the id must belong to the caller. This enriches the parameter's meaning beyond the schema's basic format, though not extensively.

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

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

The description opens with a clear verb-action pair—'Cancel a subscription by id'—and specifies the resource (subscription). It differentiates from siblings like subscribe (opposite action), list_subscriptions (listing), and recent_alerts (historical events). The deactivation note further clarifies the exact operation.

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

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

The description implies use when canceling a subscription, stating ownership enforcement ('you can only cancel your own subscriptions'). It also references recent_alerts for historical events, implicitly guiding users to that tool for history. However, it does not explicitly name alternative tools or provide exclusions, so it stops short of fully explicit guidelines.

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 mark readOnly, openWorld, and idempotent, but the description adds crucial behavioral nuance: it defines the meaning of could_not_verify (caller failure, not evidence), distinguishes it from unsupported (no source), and mentions the verification_error field. This prevents the agent from misusing ambiguous verdict states and clarifies what the tool does under the hood.

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 info-dense yet well-structured: it starts with natural-language triggers, explains the two processing paths, lists return values, and adds critical callers guidance about could_not_verify. Every sentence earns its place, and the structure is logical and front-loaded with the most essential usage signal.

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

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

Even without an output schema, the description fully specifies the verdict enum (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), the citation mechanism, and the difference between error and unsupported. It also mentions the replacement of 4–6 sequential calls, giving agents enough context to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description substantially enhances parameter understanding. It provides concrete examples for the claim parameter and explains that tolerance_pct overrides the claim wording's implied tolerance, with a specific recommendation (1–2) for hallucination detection. This goes well beyond 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 concrete natural-language triggers ("Is it true that…", "fact check") and defines the tool as "natural-language claim verification against authoritative sources." This gives a specific verb (verify) and resource (claims) while clearly distinguishing it from sibling tools by noting it replaces 4–6 sequential calls, consolidating the purpose.

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

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

Explicit guidance states "Use whenever the agent needs to check whether something a user said is factually correct." It further divides usage into a structured SEC EDGAR/XBRL fast path for company-financial claims and a grounded pipeline for all other factual claims, offering clear context and the alternative of a single call versus a multi-step pipeline.

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