Semrush

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

Annotations already indicate read-only, idempotent, and open-world behavior. The description adds that it calls Workers AI (free) and optionally Anthropic (BYO key), and states that Anthropic calls incur direct costs. This provides valuable behavioral context beyond annotations.

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

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

Three sentences with no fluff. First sentence states purpose and output, second adds model details, third lists use cases. Front-loaded and 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?

Given 4 parameters, no output schema, and annotations present, the description covers purpose, usage, behavioral notes, and return structure (per-model fields). It lacks details on synchronicity or potential delays, but is adequate 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?

Schema covers all 4 parameters with descriptions (100% coverage). The description adds value by noting the default model and the role of the API key, but does not elaborate on each parameter beyond schema. Baseline 3 with slight improvement due to additional context.

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

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

The description clearly states the action: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies default and optional models, and differentiates from sibling tools like 'ask_pipeworx' and 'deep_research' by focusing on visibility scoring.

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

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

The description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains how to use the API key for Anthropic. While it does not explicitly mention when not to use, the context of sibling tools provides alternatives.

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

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

Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context about routing to 5,529 tools, filling arguments, returning structured answers with citations, and working on every tier. While it doesn't mention failure modes or rate limits, the provided annotations lower the burden, and the added routing/citation details go beyond them.

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

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

The description is thorough but verbose, with repeated guidance (e.g., 'START HERE' is echoed by 'PREFER OVER WEB SEARCH') and an extensive example list that could be trimmed. It is well-structured with clear paragraphs, but not tightly 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 compensates by specifying that the tool returns 'structured answer with stable pipeworx:// citation URIs'. It also covers the full scope of domains, examples, and when to escalate to alternatives, making it complete for a complex routing 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 all aliases (q, text, input, query, prompt) explicitly documented as alternatives to 'question'. The tool description adds natural-language examples and domain hints, but it does not provide additional parameter-level semantics beyond what the schema already states. Baseline 3 applies.

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

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

The description clearly states the tool's function: it routes questions to a curated set of tools and returns structured answers with stable pipeworx:// citation URIs. It uses specific verbs like 'routes' and 'returns', and explicitly distinguishes itself from sibling tools (ask_pipeworx_grounded, deep_research) by positioning itself as the default entry point.

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 with trigger phrases ('what is', 'look up', 'find', 'get the latest'), domain examples, and clear alternatives: 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also explains the exception for breaking news.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the experimental nature: candidate routing improvements may be active, currently none are active (retired 2026-07-26), and it is a full working router with no fallback. This gives the agent a clear understanding of potential variability and safety without contradicting annotations.

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

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

The description is three sentences and front-loaded with the key beta identity. It contains specific details (5,529 tools, exact date) that earn their place, but is slightly dense and could be tightened; still, there is no fluff.

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

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

Given the tool has no output schema, the description explains the same response shape and the experimental routing context, which is sufficient for an agent to select and invoke it correctly. It lacks details about what candidate routing improvements entail, but this is not critical for using the tool as a drop-in replacement.

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 all six parameters documented as aliases of 'question', so the schema already carries the parameter meaning. The description only adds 'same arguments' generically, which does little beyond the schema; the baseline of 3 is appropriate since the schema handles the semantics.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, stating it is an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by explicitly noting it carries candidate routing improvements, making the 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?

It states explicitly 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear when-to-use condition. It references the stable alternative (ask_pipeworx) and explains that results are compared against it, but it does not explicitly state when not to use it (e.g., for production or stability needs), so it falls short of a full exclusion.

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 say readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description needn't repeat safety. It adds genuinely useful behavioral traits: refusal reasons (not_in_source, no_tool_match, etc.), the extra LLM call cost, and the data-extraction guarantee. It could have clarified what 'data_truncated' means or how evidence is quoted, but it exceeds annotation-only disclosure.

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

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

A dense paragraph but every sentence earns its place: it states the mode, routing, extraction guarantee, return shape with refusal reasons, usage guidance, and cost trade-off. Front-loaded with the core purpose and crucial caveat. 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, complex tool with a rich description and strong annotations, the description covers purpose, usage, behavior, return shape, refusal reasons, and trade-offs. It lacks details like typical latency or what counts as 'directly answers', but the return schema and examples of refusal reasons fill most gaps. There is no output schema, but the description explicitly lists the response fields, making it reasonably 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% and the schema already explains 'question' plus all aliases. The description adds the phrase 'Your question in natural language' (already in schema) and no additional parameter semantics beyond 'the data' from the tool result. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and clearly states it returns cited answers or an explicit refusal. It distinguishes 'grounded' from sibling ask_pipeworx by emphasizing extraction only from tool results and structured response/refusal 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?

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples, and contrasts with casual lookups: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call 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?

Annotations declare readOnly, idempotent, non-destructive. Description adds that it consumes Semrush API units and that backlinks reports are not regional, providing useful behavioral context beyond annotations.

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

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

Single paragraph efficiently conveys purpose, return format, and key notes. No filler, but could be slightly more structured with bullet points.

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, description explains return columns and API unit consumption, covering essential context. Adequate for the tool's simplicity.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds meaning by listing response columns and clarifying default target_type, which supplements 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?

Clearly states it returns a backlinks summary for a domain or URL, listing specific columns. Distinct from siblings like domain_organic_keywords or domain_overview.

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?

Implies usage for backlinks overview, mentions absence of regional parameter and API unit consumption, but does not explicitly state when to use vs alternatives or when not to 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?

Describes extensive behavioral details including resolution confidence handling (low_confidence_match, market_closed_or_inactive), spread width warnings, cancellation rule parsing, and field explanations. Annotations (readOnly, idempotent) are consistent and description adds much more. No contradictions.

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

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

Well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Front-loaded with purpose. Long but each sentence adds necessary information for a complex tool.

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

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

Covers all relevant scenarios: low confidence, closed markets, illiquid spreads, cancellation rules, parent events, news fallback. No output schema, but description fully documents response structure and edge cases.

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

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

Schema coverage is 100%, but description adds significant value: explains market input flexibility (slug/URL/question), depth parameter semantics, and include_raw purpose with usage guidance. Goes beyond schema enum and 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?

Clearly states the tool researches Polymarket bets by pulling Pipeworx data. Provides specific inputs (slug, URL, question text) and outputs (evidence packet, comparison). Examples and use cases given. Distinguishes from siblings like polymarket_edges via specific use case descriptions.

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

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

Explicitly states when to use: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z'. Does not explicitly mention when not to use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that results are sorted by primary metric, returns paired data with citation URIs, and handles off-calendar fiscal years. No contradiction.

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

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

Description is front-loaded with trigger phrases and key guidance. Slightly wordy but each sentence contributes value. Could be more 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?

No output schema; description mentions paired data and citation URIs but does not detail structure of response. Annotations provide safety. Moderate complexity, but output details could be more explicit.

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 description adds meaning: explains type enum (company pulls 10-K data, drug pulls FAERS) and values array (tickers vs drug names with examples). Adds significant context beyond schema.

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

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

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases (compare, vs, versus, which is bigger, rank these companies). It distinguishes from siblings by noting it replaces 8-15 sequential lookups.

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

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

Explicitly says ALWAYS PREFER over sequential single-pack lookups and provides example queries. Specifies entity types and data sources. Does not explicitly mention when not to use (e.g., for single entities), but strong guidance overall.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses critical behavioral traits: paid tier for 'thorough' depth, latency expectations (15-60s, thorough up to ~90s), never-invented gaps[], conditionally present citation_uri only when fetchable, and semantic excerpting of large records. This substantially enriches the agent's understanding.

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

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

The description is long but well-structured and front-loaded with the account requirement and core purpose. Each sentence delivers distinct information, though some redundancy exists (e.g., citation details repeated across paragraphs). It is appropriately detailed for a complex tool.

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

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

With no output schema, the description fully specifies the return packet: verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], and hop fields. It also covers latency, depth behavior, and source scope, making it complete for the tool's complexity.

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

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

The schema already covers both parameters with 100% coverage, but the description adds functional nuance: the depth parameter's 'standard' performs gap recovery and 'thorough' adds iterative lead chasing, and the question parameter accepts broad/multi-part natural-language queries. This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly says 'this is NOT open-web search,' distinguishing it from sibling tools like ask_pipeworx. It also gives concrete examples ('compare X and Y's regulatory + financial exposure') that illustrate its intended use.

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 and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also notes account tier requirements and suggests ask_pipeworx if not signed in.

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 idempotentHint=true. The description adds that it returns top-N most relevant tools with full input schemas and curated examples, ready to call directly, which goes beyond annotations but is not critical. No contradictions.

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

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

The description is concise (three sentences) and front-loaded with the main action. It efficiently covers purpose, usage, and return type 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?

Despite lacking an output schema, the description fully explains what is returned (top-N tools with names, descriptions, and full input schemas with examples). It also covers parameter aliases and example queries, making it complete for a discovery 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%, providing descriptions for all 6 parameters. The description mentions the query parameter and gives examples, but doesn't add substantial meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Find' and the resource 'tools'. It provides examples of use cases (SEC filings, FDA drugs, etc.) and distinguishes this tool from siblings by specifying it returns ready-to-call tool definitions, emphasizing its role for browsing/discovery.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not-to-use (when the specific tool is already known).

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so safety is clear. The description adds value by disclosing that the tool consumes Semrush API units, which is a key behavioral cost. 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 extremely concise: two sentences that front-load the core purpose and return format, followed by a critical behavioral note. Every word earns its place with no fluff.

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

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

For a 5-parameter tool with no output schema, the description provides the column list and API unit consumption. It does not explain pagination or default limits, but these are available in the schema. Overall, it is sufficiently complete for common use.

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 clear descriptions for all 5 parameters in the input schema. The description does not add significant new meaning beyond the schema, maintaining the baseline score.

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: retrieving top organic search keywords for a domain, sourced from Semrush. It specifies the resource (domain), action (keywords), and data source, distinguishing it from paid keyword or keyword overview tools.

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

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

The description mentions that using the tool consumes Semrush API units but does not explicitly state when to use this tool versus alternatives. The sibling tool names hint at differentiation (e.g., domain_paid_keywords), but the description lacks direct usage guidance or exclusion criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it consumes Semrush API units and lists all output columns, which is useful behavioral context beyond annotations.

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

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

Two sentences: first states purpose and output format, second explains API unit cost. Front-loaded with key info, 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?

No output schema but description lists columns. Parameters well-documented. Missing error handling or rate limit info, but annotations provide safety profile. Satisfactory for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by clarifying that _apiKey is 'your own' key and domain should be without scheme, and database is a 2-letter code with default 'us'.

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

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

Description uses specific verb 'summary' and resource 'domain' with clear context (SEO/PPC). It lists exact columns returned, distinguishing it from siblings like domain_organic_keywords and domain_paid_keywords which are more granular.

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?

Description implies it's for high-level overview but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives or conditions under which to prefer other 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 signal read-only, idempotent, non-destructive behavior. Description adds that it consumes Semrush API units and details the return format (columns), providing useful context beyond annotations.

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

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

Description is compact but packs essential information. Could be slightly better structured (e.g., bullet list for columns), but every sentence adds value.

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

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

No output schema, but description lists all return columns, explains API cost, and covers all 4 parameters. Sufficient for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning for each parameter: notes that _apiKey is BYO and consumes units, gives domain example, explains database as 2-letter regional code with default, and suggests small value for display_limit.

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

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

Description clearly states it returns paid keywords (AdWords/PPC) for a domain via Semrush, specifying the type parameter and output columns. Distinguishes itself from domain_organic_keywords by explicitly mentioning paid nature.

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

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

Describes when to use (to get paid keywords), but doesn't explicitly say when not to use or list alternatives. However, sibling list includes domain_organic_keywords, providing implicit differentiation.

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 rich behavioral context beyond annotations, including fan-out across multiple sources, specific return fields, fallback mechanisms, and sunset notes for patents. Annotations already indicate read-only, idempotent, open-world, non-destructive.

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

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

The description is well-structured with trigger phrases and bullet-like output list, but is somewhat verbose with the patents sunset detail. Still, it is front-loaded and clear.

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 fully explains return values including CIK, filings with URIs, fundamentals, patents, news, LEI. It also covers limitations and fallbacks.

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

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

With 100% schema description coverage, the description adds meaning: explains that 'type' only supports 'company', and 'value' must be ticker or zero-padded CIK, with examples. This exceeds baseline.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and outputs. It distinguishes itself from sibling tools like resolve_entity and compare_entities.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use resolve_entity first if only a name.

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; description adds no behavioral details beyond 'Delete', which is consistent. Minimal additional value over annotations.

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

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

Two sentences with no waste: first sentence states purpose, second gives usage guidance. Front-loaded and 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?

Given a simple tool with one parameter, no output schema, and good annotations, the description covers purpose and usage completely.

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

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

Schema description coverage is 100% with good documentation for 'key'. Description only restates the parameter's purpose without adding new 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?

States 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly lists when to use (stale context, task done, clear sensitive data) and suggests pairing with remember and recall, providing clear context and alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavior details: fetches page, extracts title/description/key links, emits standard markdown format. No contradiction.

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

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

Two sentences plus bulleted use cases. Purpose front-loaded, every sentence adds value. No unnecessary words.

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

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

No output schema, but description explains output format (standard llms.txt markdown) and usage (drop at site-root/llms.txt). Sufficient for a simple read-only tool.

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

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

Schema coverage is 100% so baseline 3. Description does not add new parameter meaning beyond what schema already provides (url and 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?

Clearly states 'Generate a production-ready llms.txt file for any URL' with specific verb and resource. Distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence which focus on analysis rather than file generation.

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

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

Lists explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor. Does not explicitly state when not to use, but context clearly differentiates from siblings.

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

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

Annotations declare readOnly, idempotent, openWorld. Description adds important cost info 'Consumes your Semrush API units' and details returned columns, exceeding 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?

Three sentences, no verbosity: purpose, return format, cost. Front-loaded and every sentence adds value.

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

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

For a simple tool with 3 params and no output schema, description explains purpose, columns, and cost. Could optionally include an example value, but complete enough.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). Description adds no extra meaning beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states the verb 'search metrics' and resource 'single keyword phrase', and distinguishes from sibling tools like domain_overview which focus on domains.

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?

Implied usage for single keyword phrase, but no explicit when-to-use or when-not-to-use compared to alternatives like domain_organic_keywords.

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, idempotent, non-destructive. Description adds that it returns specific fields and scopes to caller's subscriptions, but doesn't disclose other details like pagination or performance.

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 concise sentences, front-loads purpose and includes actionable 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?

Describes return fields, and parameter is simple. Without output schema, the description provides enough context for an agent to understand output, but lacks potential details like ordering or limits.

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%; the description doesn't explain the 'include_inactive' parameter beyond what's in the schema, so baseline 3.

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

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

Clearly states it lists the caller's active subscriptions and specifies returned fields (id, type, etc.). Distinguishes from siblings 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?

Explicitly suggests using it to review before adding more or to find an id to cancel, providing clear when-to-use guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds that it consumes Semrush API units and details the returned columns (Dn, Cr, etc.), which informs about output structure. No contradictions.

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

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

Two sentences, clear and front-loaded: first sentence states purpose and output, second adds cost context. No unnecessary words.

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

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

No output schema, but description lists all returned columns and their meanings. Also explains the API type and cost. Adequate for a data retrieval tool with well-annotated 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 covers all 4 parameters with descriptions. The description does not add new semantic information about parameters beyond the schema, but the baseline is 3 due to high schema coverage.

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

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

The description clearly states the tool finds organic search competitors for a domain, specifies the Semrush API type, and lists the output columns. It is distinct from sibling tools like domain_organic_keywords or domain_overview.

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

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

No explicit guidance on when to use this tool versus alternatives like domain_organic_keywords or backlinks_overview. Only mentions API unit consumption, which is a cost note, not usage 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?

The description discloses the claim_token workflow, rate limit ('5 per identifier per day'), and that it's free and doesn't count against tool-call quota. Annotations only provide false hints for readOnly/destructive, so the description adds meaningful behavioral context about side effects and limits.

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

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

The description is longer than average but each sentence adds distinct information—purpose, use cases, exclusions, token mechanics, rate limits, and cost. It is front-loaded with the core purpose and avoids empty filler, though it could be slightly tighter.

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 optional parameters and no output schema, the description covers all key aspects: submission types, scoping rules, message framing, and the claim_token feedback loop. It also notes the team's daily digest and roadmap impact, giving the agent a full picture.

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

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

While schema descriptions cover all parameters, the description adds valuable semantic guidance: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' for the message parameter, and explains the claim_token round-trip usage. This goes beyond the schema's basic 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the tool's purpose as submitting feedback. It distinguishes from sibling tools by limiting scope to 'tools served by this Pipeworx connection,' making it distinct from ask/research tools.

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

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

It explicitly states when to use: for bugs ('wrong/stale data'), feature requests ('tool you wish existed isn't in catalog'), and praise. It also provides a clear when-not-to-use by telling users to file with the other server if the tool is from a different MCP server, and even suggests checking 'Pipeworx tool names are the ones this connection lists.'

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 idempotent, read-only, and non-destructive behavior. Description adds that data is self-aggregating from CF analytics, PII-free, and cached 5min-1h. No contradictions.

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

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

Concise, well-structured: purpose first, then use cases, then additional details. Every sentence adds value without redundancy.

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

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

Given low complexity (1 param, no required fields, rich annotations), description fully covers return format, data source, caching, and use cases. No output schema needed.

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

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

Schema coverage is 100% (single parameter with enum). Description adds semantic guidance: shorter windows for hot topics, longer for steady-state demand.

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

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

Description explicitly states the tool returns top tools, packs, and call volume over a recent window, clearly differentiating from sibling tools that focus on search or entity discovery.

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

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

Provides three specific, actionable use cases: discovering hot data sources, confirming canonical tool choice, and aligning use case with agent needs. Implicitly suggests when not to use (e.g., when needing detailed search).

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

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

Discloses important behaviors: fill check logic, semantic anchor for cross-event pairs, partition filter for placeholders, and response structure. Annotations confirm read-only, idempotent, and non-destructive behavior; description adds context beyond annotations.

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

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

Description is detailed but not overly verbose. It front-loads the main purpose and uses clear sections for different modes. Minor redundancy in explaining fill check but overall well-structured.

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

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

Given the tool's complexity, the description fully covers modes, edge cases (placeholders, similarity), response fields, and integration with fill risk. No output schema but response is well documented.

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

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

Schema already provides 100% coverage for both parameters. Description adds significant value by explaining each mode's purpose, examples of valid inputs (event slugs, topic phrases), and the additional processing (fill check, similarity filter).

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

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

The description clearly states the tool finds arbitrage opportunities using monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by specifying the method and scope.

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

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

Explicitly explains when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Provides guidance on when not to trade via fill check and references sibling tool for custom sizing.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, etc., and the description adds extensive behavioral context beyond annotations: it details the three model families, edge calculations, caching (1h at KV level), and diagnostics for empty segments. No contradictions with annotations. The description fully discloses the tool's 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 very long (approximately 500 words) and contains detailed explanations. While it is well-structured with clear sections, it could be more concise. Every sentence adds information, but the verbosity reduces efficiency for an AI agent. A 3 reflects moderate conciseness.

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

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

Given the complexity of the tool (9 parameters, three segments, caching, diagnostics), the description is remarkably complete. It covers the response structure (by_segment, fed_candidates, diagnostics), the tradeable-edge knobs, and edge calculation details. No output schema exists, but the description explains return fields sufficiently.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond schema: it explains the rationale for parameters like min_kelly, slippage_pp, and min_partition_leg_kelly, including why min_kelly doesn't filter partition opportunities. The added context is valuable but the schema descriptions are already quite detailed.

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 specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes the tool's purpose by focusing on disagreement opportunities, and it explains the three model families. While it doesn't explicitly differentiate from sibling tools like polymarket_edge_tracker, the purpose is specific and actionable.

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

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

The description provides clear context for when to use this tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It gives usage guidance through knobs but does not explicitly state when not to use it or list alternative tools. The context is strong but lacks explicit exclusions.

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

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

Annotations already indicate read-only, open-world, idempotent. Description adds details like snapshot TTL (60-day), data gaps, decay computation from daily closes. No contradictions.

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

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

Well-structured with clear heading, bulletized response fields, and limits section. Slightly verbose but each part adds value. Front-loaded with the key question.

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, description fully explains return types (tracked, expired, snapshot_dates) and their fields. Covers limits and assumptions. Complete for a tool with optional params.

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 describes both parameters with default and constraints. Description reinforces defaults (days=14, window=1wk) and adds max lookback (30). Schema coverage is 100%, so description adds marginal 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?

Clearly states it measures edge persistence and decay, distinguishing from sibling tools like polymarket_edges by focusing on time-series analysis. Answers specific question about edge age and shrinkage.

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 context on when to use: for evaluating edge longevity vs freshness, especially comparing a 3-week-old wide edge to a fresh one. Does not explicitly list alternatives or when not to use, but the context is clear.

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

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

Annotations readOnlyHint=true, destructiveHint=false etc. are present. Description adds significant context: returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and warns about forced_directional_risk. No contradiction.

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

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

Description is well-structured with headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Front-loads key info. Slightly verbose but every sentence earns its place given 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?

Comprehensive for a tool with 4 params and no output schema. Covers both modes, explains return values, usage context, and risks. No gaps identified.

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%. Description adds some context (e.g., meaning of size_usd in each mode) but schema descriptions are already detailed. Baseline 3 is appropriate as description adds marginal value beyond schema.

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

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

The description clearly states the tool checks 'Realizable-vs-theoretical edge against live CLOB order-book depth.' It distinguishes between single-market and basket modes, differentiating it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidance given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why (thin books not capturable, partial fills create directional risk). No alternatives mentioned but context is clear.

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

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

Annotations indicate read-only, non-destructive, idempotent. Description richly adds behavioral details: leg-by-leg price comparison, compatibility_warning conditions (bet shape mismatch, semantic mismatch), temporal_alignment check, and skipped leg counters. No contradictions.

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

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

Description is longer than average but every sentence adds value. Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Could minorly tighten some phrases, but overall efficient for the amount of information conveyed.

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

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

Despite no output schema, the description thoroughly explains the response structure: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. Covers all edge-cases the agent needs to 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%, but description adds significant context: lists all 10 topic shortcuts, explains override behavior for explicit tickers, and provides example values. This goes well beyond the schema's property descriptions.

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

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

The description clearly states it calculates cross-venue spread between Kalshi and Polymarket for the same resolving question, with two distinct modes (topic shortcuts and explicit tickers). It differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue rather than intra-venue arbitrage.

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: topic mode for 10 pre-mapped macros, explicit mode for custom pairings. Warns that most pre-mapped topics currently return compatibility warnings, setting expectations correctly. Includes safety fields explaining when spreads are meaningless.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds contextual details about scoping and pairing, but no contradictions.

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

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

Three concise sentences that front-load purpose, provide examples, and state scope. 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?

The description covers the tool's purpose, usage, scoping, and pairing with siblings. Given the simple parameter schema and annotations, it is quite complete, though no return format is specified.

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

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

Schema coverage is 100% and baseline is 3. The description adds real-world examples and clarifies the 'omit to list all' behavior, providing extra meaning over 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?

Clearly states the tool retrieves saved values or lists all keys, using specific verbs and distinguishing from sibling tools 'remember' and 'forget'.

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

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

Explicitly describes when to use (look up stored context, avoid re-deriving) and scoping, though no explicit when-not-to-use instructions are given.

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 annotations: it explains the side-effect of mark_read, confirmsa idempotency through polling advice, and details return fields. No contradiction with annotations.

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

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

The description is a single efficient paragraph, front-loaded with purpose, then return fields, filters, side-effect, and finally alternative access. Every sentence adds value, no fluff.

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

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

For a read-only query tool with 5 optional parameters and no output schema, the description covers return fields, all parameter behaviors, polling safety, and an alternative endpoint. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaningful context for each parameter: gives examples for type ('sec_8k'), explains ISO format for since, clarifies mark_read effect and unread_only behavior, plus default values for limit.

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 pulls fired events from the user's subscription feed, using specific verb+resource. It distinguishes from sibling tools like 'list_subscriptions' by focusing on events/alerts rather than subscription management.

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 good usage context, including polling suitability and an alternative URL for scripts/dashboards. However, it doesn't explicitly compare to other sibling tools or state when not to use this tool, leaving some gaps.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds rich detail: parallel calls, source fan-out, fallback mechanisms (GDELT→GNews), and soft-fail for USPTO. No contradictions with annotations.

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

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

The description is well-structured, starting with example queries, then detailing sources and parameter behavior. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description covers return structure (changes[], total_changes, citation URIs), source behavior, and fallbacks. It is fully adequate for an agent to use the tool correctly.

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

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

Schema coverage is 100%. The description adds value by explaining the 'since' parameter format (ISO or relative) with recommendations, and clarifies 'type' is limited to 'company' and 'value' accepts ticker or CIK.

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 provides a change feed for companies, listing recent updates across multiple sources. It explicitly distinguishes from the sibling tool 'entity_profile', which is for static profiles.

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

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

The description gives concrete query examples like 'What's new with X' and explicitly advises when to use 'entity_profile' instead for static data. This provides clear usage boundaries.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false; description adds persistence details per authentication status and scoping by identifier, going beyond annotations 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?

Three sentences, front-loaded with purpose, then usage, then technical details; 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?

No output schema, but description explains persistence and retrieval pairing, which is sufficient for this simple write operation.

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

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

Schema coverage is 100%, so description adds little to parameter understanding, but provides context on how key and value are used in memory storage.

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

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

Description clearly states verb ('save') and resource ('data'), provides examples of use cases, and distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and references complementary tools for retrieval and deletion, but does not explicitly state when not to 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 (read-only, idempotent), the description discloses key behaviors: identifiers are labeled with their source, unresolved ones are explicitly listed under 'unresolved', enrichment degrades gracefully when upstream sources are unavailable, and each call internally cascades through multiple endpoints. This gives the agent important expectations about edge cases 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 every sentence contributes value: user examples, supported types, identifier details, fallback behavior, and the cascade note. It is well-structured with clear sections, though a slightly more compact phrasing could improve scannability without losing information.

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

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

Given there is no output schema, the description compensates by explaining what each type returns (identifiers, sources, ownership details, RxCUI citation). It covers input formats, failures, and degradation, making the tool's behavior fully comprehensible for an agent deciding whether to call it and how to interpret results.

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

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

While the schema already provides 100% parameter coverage, the description adds significant semantics: for 'company' it explains the cross-source identity spine (CIK, LEI, FIGI) and accepted input forms; for 'drug' it specifies RxNorm outputs. It also gives concrete examples like 'AAPL' and 'ozempic', enriching the schema's terse descriptions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It uses specific verbs ('resolve') and resources ('ticker', 'CIK', 'LEI', 'RxCUI'), and distinguishes itself as the go-to first step when an ID is needed. Example queries in the description make the 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 'Use FIRST whenever you have a name but need an ID', providing a clear usage rule. It does not name alternative tools, but the context implies this is the primary resolver, and siblings like compare_entities or entity_profile serve different purposes. The guidance is strong enough for correct 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?

Adds significant context beyond annotations: discloses probing each entity with ai_visibility_check, ranking by score, and returning a ranked list with specific fields (score, confidence, signal density). No contradiction with annotations.

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

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

Four sentences, each earning its place: first states purpose, second explains process, third provides use case, fourth describes output. No fluff.

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

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

Covers key aspects: purpose, process, output structure, and example use. Lacks mention of entity count limit (2-8, present in schema) and potential error conditions, but adequate given no 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?

Adds value beyond the schema by explaining that the first entity is treated as the 'subject' for narrative and the rest as competitors. Also clarifies relationship between models and _apiKey. Schema already covers 100% of parameters with 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, with specific verbs like 'probes', 'ranks', and 'surfaces'. It distinguishes from sibling ai_visibility_check by focusing on multi-entity 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?

Provides a concrete example use case ('does Claude know about us as well as our competitors?') implying competitive audits. Does not explicitly state when not to use it or mention alternatives, but context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds rich context: composite fan-out, bundlephobia's first measurement delay (5-30s), graceful degradation with sources_failed, and detailed return fields. No contradictions.

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

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

The description is well-structured and front-loaded with the core purpose and use cases. It is slightly verbose but every sentence adds value (composite nature, return fields, fallback behavior). Could be trimmed marginally.

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 complexity (composite tool, no output schema), the description covers return fields, failure behavior, and ecosystem scope. It does not explain how to interpret results, but fields are self-explanatory. Adequate completeness.

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 clear parameter descriptions. The description does not add significant extra meaning beyond the schema; it restates that version defaults to latest. Baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for adding npm packages, combining deps.dev and bundlephobia. The verb 'scan' and resource 'dependency (npm package)' are specific, and the scope is well-defined. It distinguishes from siblings by being a unique composite tool for npm packages.

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

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

The description explicitly advises when to use: when an agent asks about safety, popularity, size, or cost of adding a package. It also notes limitations (NPM only in v1, partial failures) and provides alternatives for other ecosystems.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char windows, has a 200K char cap with truncation flagging. 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, well-structured paragraph. It front-loads the core purpose and use case, then adds technical details and limits. Every sentence contributes actionable information 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?

Despite no output schema, the description covers what is returned (passages with offsets and scores) and internal mechanics. It also explains pairing with another tool. However, the exact output format (e.g., array of objects) is implied but not explicitly structured, leaving slight ambiguity.

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

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

Schema coverage is 100%, so the schema already documents parameters well. The description adds value by providing example queries for the 'query' parameter (e.g., 'supply-chain risk') and restates the char limit for 'text', effectively reinforcing meaning 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 'Semantic search INSIDE a fetched record' with specific verbs and resources. It distinguishes itself by focusing on searching within already-fetched text as opposed to full-document QA, and provides concrete examples like SEC 10-K or 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?

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt.' It also suggests an alternative workflow by pairing with ask_pipeworx_grounded, giving clear context for use vs. alternatives.

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

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

The description discloses behavioral traits beyond annotations: persistence requirement (OAuth account), SMS daily cap (10/day), webhook auto-disable after 10 failures, and webhook signing secret one-time return. No contradictions with annotations (readOnlyHint=false, destructiveHint=false).

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 purpose and well-organized into usage, types, and delivery details. While slightly long, every sentence adds value. Minor redundancy (e.g., delivery details repeated in schema description and top-level description) but overall 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?

Given no output schema, the description mentions 'Returns the new subscription id' but doesn't detail the response structure. However, it fully covers the complex input schema with nested objects and multiple types, including edge cases (e.g., SMS cap, webhook failure). Adequate for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds substantial meaning: concrete examples for each type's params (e.g., sec_8k items, polymarket_edge topic), delivery channel details (SMS verification, webhook HMAC signing), and constraints. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies different subscription types (sec_8k, polymarket_edge, etc.) and distinguishes this from sibling tools like unsubscribe and list_subscriptions.

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

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

The description explains when to use this tool ('Create a proactive monitoring subscription...') and includes prerequisites ('Requires a Pipeworx OAuth account; anonymous + BYO cannot persist subscriptions'). It provides examples for each type but does not explicitly state when not to use it or compare to alternatives like recent_alerts.

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 that the tool returns category-bucketed example questions with tool+argument shapes, and explains the behavior of topic filtering. No contradiction.

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

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

The description is moderately long but well-structured, front-loading common user questions and using a dash to punctuate the output summary. Every sentence adds value, though it could be slightly more 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?

Given the tool's simplicity (1 optional param, no output schema, no nested objects), the description is complete. It covers the return format, usage scenarios, and topic filtering. No missing context for an agent to invoke it correctly.

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

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

Schema coverage is 100% (1 parameter with description). The description adds context: the optional focus area values (finance, pharma, etc.) and the behavior when omitted (full spread). This goes 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 clearly states that the tool returns category-bucketed example questions with exact tool and argument shapes, serving as an onboarding entry point. It distinguishes itself from sibling tools like 'ask_pipeworx' by being the first tool to use when the agent doesn't know 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 instructs to use this tool FIRST when unsure of Pipeworx's capabilities or to learn meta-tools. Provides guidance on calling with no arguments for full spread or passing a topic (e.g., 'finance', 'pharma') to focus. Clear when-to-use and when-not-to-use.

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

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

The description adds beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This explains the non-destructive nature and side effects.

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

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

Two concise, front-loaded sentences with no wasted words. Every sentence is informative.

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 fully explains the behavior (deactivation, historical availability), making it complete for a single-parameter 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%, and the description reinforces that 'id' is the subscription id returned by subscribe, adding context beyond the schema.

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

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

The description clearly states the action 'Cancel a subscription by id,' specifying the verb, resource, and method. It distinguishes from siblings like 'subscribe' and 'list_subscriptions.'

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

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

It explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. No explicit alternatives mentioned, but the constraint is valuable.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive traits. The description adds substantial behavioral context: the two-path routing, the exact meaning of could_not_verify (crucial caller warning not to treat it as evidence), the meaning of unsupported, and the inclusion of verification_error. This goes well beyond annotations and is essential for correct interpretation.

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

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

Although the description is long, every sentence earns its place: example queries aid recognition, the purpose is stated clearly, the two paths are explained, the return values and critical verdict semantics are disclosed, and the efficiency benefit is noted. It is front-loaded and highly structured, making it easy for an agent to parse.

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

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

There is no output schema, so the description carries full responsibility for explaining return values. It lists all six verdicts, details the meaning of the two ambiguous ones, explains verification_error, and describes both processing paths. For a complex verification 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 input schema already provides full descriptions for both parameters (claim and tolerance_pct) with examples and rules, so schema coverage is 100%. The description adds only a minor phrase 'exact percent-delta math' which doesn't materially enhance parameter understanding 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 opens with concrete example queries and then states a specific purpose: natural-language claim verification against authoritative sources. It clearly distinguishes the tool's scope (verifying factual claims) from general tools, and even describes the two internal pipelines (SEC EDGAR fast path vs. grounded pipeline), making the purpose unmistakable.

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

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

The description gives an explicit when: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains that all factual claims are covered, effectively ruling out the need for alternatives. However, it does not explicitly name when-not to use it or mention specific sibling tools, so it doesn't fully meet the 'alternatives' criterion for a 5.

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