Slack_connect

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

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which aligns with the 'probe' action. The description adds behavioral context: it mentions scoring, per-model and combined outputs, and that the default model is free. It also notes that providing an API key triggers charges from Anthropic. 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 and well-structured: four sentences that front-load the main action and quickly cover parameters, output, and use cases. Every sentence adds value, with no redundant or vague phrasing.

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

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

Given the tool's complexity (4 parameters, no output schema), the description is complete: it explains input, optional parameters, output structure (per-model score, confidence, signals, raw_response, combined view), and use cases. No important aspect is missing.

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

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

Schema description coverage is 100%, and the description adds extra context beyond the schema: it explains that the default model is Workers AI Llama-3.3-70b (free) and that the `_apiKey` parameter is for Anthropic with direct billing. This enriches the semantic understanding of the parameters.

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

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

The description clearly states the tool's purpose: to probe LLMs for knowledge about a business/brand/product/topic and score visibility from 0-100 per model. It uses a specific verb ('probe') and resource ('LLMs for knowledge'), distinguishing it from sibling tools like 'ask_pipeworx' (which answers questions about Pipeworx) or 'scan_competitor_ai_presence' (which scans competitors).

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 usage contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default model and when to provide an API key. However, it does not explicitly state when not to use this tool or mention alternatives, which would have justified a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: routes across 5,529 tools, returns stable citation URIs, works on every tier, and is one fast call. It doesn't disclose potential failure modes, but the combination of annotations and description gives a strong safety profile.

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

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

The description is long but exceptionally dense with actionable information. It uses bolded calls-to-action and structured guidance. Every sentence adds value, though it could be slightly trimmed without losing meaning.

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

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

Given the tool's complexity and lack of output schema, the description fully covers what, when, why, alternatives, examples, and return behavior (structured answer with citations). No significant gaps remain for an agent to decide when and how to invoke it.

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

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

The input schema already documents 'question' with aliases and examples (100% coverage). The description reinforces that the user only needs to provide a natural-language question and that the tool 'fills arguments' automatically, which clarifies that no sub-tool parameters are required from the caller.

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: answer factual questions about real-world entities, events, or numbers by routing to a large array of verified sources. It uses a specific verb ('routes', 'returns') and resource ('pipeworx'), and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit 'when to use' guidance ('PREFER OVER WEB SEARCH', 'START HERE'), examples of queries, and clear escalation paths ('Step up only when needed' to grounded or deep_research). Also mentions when it handles breaking news, making alternatives 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?

The description discloses that this is a full working router with no fallback, clarifies that candidate improvements are only active when under test, and mentions that results are compared against the stable router. This goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) and adds meaningful operational context.

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

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

The description is slightly verbose but front-loaded with the key beta/universal router identity. The extra context about the current candidate status and comparison to the stable router is relevant and earns its place, though it could be tightened.

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

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

With rich annotations, a fully documented schema, and a description that covers behavior, current state, and relationship to the stable router, the tool is well contextualized for an agent to select and invoke correctly. No output schema exists, but the description sufficiently explains what to expect.

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

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

The input schema provides 100% description coverage, including the question aliases and a clear description. The description adds no parameter-level detail beyond 'same arguments,' which is acceptable since the schema already fully documents all parameters.

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, states it is a universal router with the same 5,529 tools and response shape, and differentiates it from the stable router via candidate routing improvements. The verb and resource are specific, and the experimental edge is explicit.

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

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

It advises using the tool exactly like ask_pipeworx when you want the newest routing and notes that current behavior matches the stable router. However, it does not explicitly say when to prefer the stable ask_pipeworx over the beta, nor does it mention ask_pipeworx_grounded as an alternative.

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

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

The description discloses rich behavioral details beyond the annotations: it explains the two possible return shapes (success with evidence and refusal with specific reasons), notes that answers are grounded strictly in tool results, and reveals the performance cost. The annotations (readOnlyHint, openWorldHint, idempotentHint) align perfectly, and no contradiction exists.

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

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

The description is lengthy but highly information-dense, covering success/refusal formats, use cases, and cost tradeoff. Every sentence contributes value, though it could be slightly tightened. The structure front-loads the core purpose and then details behavior, making it easy to scan.

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 must explain return values, and it does so exhaustively (both success and refusal formats). It also clarifies the routing mechanism, cost comparison, and ideal use cases. Given the tool's complexity and the absence of structured output metadata, the description is fully complete.

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

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

Schema description coverage is 100%, with all aliases (q, text, input, query, prompt) explicitly documented. The description adds no additional parameter-level meaning beyond stating that the input is a natural language question, which the schema already conveys. Baseline 3 is appropriate since the schema carries the semantic weight.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode that routes through the same tool selection as ask_pipeworx but extracts answers solely from the tool result. It explicitly distinguishes itself from the sibling ask_pipeworx by emphasizing grounding and refusal behavior, using specific verbs like 'EXTRACTS' and 'returns' with a structured response format.

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' It also mentions the cost tradeoff (one extra LLM call), offering clear criteria for when to choose this tool over its sibling.

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, non-destructive. The description adds extensive behavioral context: market resolution, classification, fan-out, confidence levels, handling of low-confidence matches, closed markets, wide spreads, cancellation rules, and blocking statuses. All consistent 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 lengthy but well-structured with clear sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and front-loads the core purpose. It could be more concise, but the structure aids readability.

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

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

Given 3 parameters, no output schema, and 100% schema coverage, the description is exceptionally complete. It covers inputs, processing steps, outputs, edge cases (low confidence, closed markets, wide spreads, cancellation rules), safety, and blocking conditions. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: explains market input types (slug, URL, question text), depth options (quick vs thorough), and include_raw (summarized vs full payloads). This adds significant value.

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

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

The description clearly states its function: research a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). This distinguishes it from siblings like ask_pipeworx or compare_entities, which are more general.

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 is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides classifiers and fan-out examples. It does not explicitly state 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 already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: data sourcing (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, return of paired data and citation URIs. 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?

Description is somewhat lengthy but front-loaded with natural language triggers that aid discoverability. Every sentence provides useful information; however, it could be slightly more concise by removing redundant phrases like 'rank these companies' as examples. 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?

Despite no output schema, description adequately explains return format (paired data + citation URIs) and sorting behavior. It covers both entity types, edge cases (off-calendar fiscal years), and the comparative advantage over sequential lookups. Comprehensive for a tool of this complexity.

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

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

Both parameters (type, values) have 100% schema description coverage. Description adds meaning by explaining that values should be tickers/CIKs for company and drug names for drug type, provides examples, and specifies min/max items (2–5). This enriches the schema beyond enum labels.

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 starts with natural language triggers ('Compare X and Y', 'X vs Y') and clearly states it performs side-by-side comparisons of 2–5 companies or drugs. It specifies data sources (SEC EDGAR for companies, FAERS for drugs) and distinguishes itself from sequential lookups. The verb 'compare' and resource 'entities' are unambiguous.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This provides clear when-to-use guidance and contrasts with alternative approaches (sequential single-pack lookups). It also explains different data sources for company vs drug types.

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?

Going well beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses substantial behavior: parallel facet routing, explicit gaps[] that are never invented, depth-dependent hop behavior, contradictions[], citation_uri fetchability guarantees, semantic excerpting, and expected latency. This gives the agent a rich, accurate mental model of what the tool actually does.

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 the tool is complex and every sentence carries substantive information. It is well front-loaded with the critical account requirement and sibling fallback. The main drawback is readability: the first sentence is dense and overloaded with parentheticals, and the overall wall-of-text format could be more scannable.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], and contradictions[]. It also covers latency expectations and the paid-tier constraint, making it complete for an agent to decide whether and how to invoke the tool.

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

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

The input schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaningful context beyond the schema: it clarifies that `question` may be broad/multi-part, that `depth:"thorough"` requires a paid plan, and it elaborates on the hop/gap-recovery semantics tied to depth values.

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

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

The description specifies a concrete verb ('research') and a precise resource ('Pipeworx's 1455 STRUCTURED data sources'), and clearly explains the tool's decomposition-and-routing mechanism. It also distinguishes itself from siblings like ask_pipeworx, making its unique value 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 states when to use deep_research ('Best for broad/multi-part questions over structured data') and when to prefer ask_pipeworx ('single lookup', 'BREAKING or colloquial CURRENT-NEWS'). It also names the account prerequisite and points to a fallback tool, satisfying the when/when-not/alternatives requirement.

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 readOnlyHint=true and idempotentHint=true. The description adds valuable context: returns top-N tools with names, descriptions, and full input schemas (with examples) ready to call directly, no second lookup needed. This goes beyond annotations.

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

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

The description is two sentences, front-loaded with purpose. The first sentence is slightly long but efficient. Well-structured and scannable.

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 (search with one required parameter), annotations cover safety, and no output schema is needed. The description explains what it does, when to use, and what it returns. 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 description coverage is 100%, so baseline is 3. The description adds examples and clarifies that query accepts multiple aliases, but does not significantly expand beyond schema details.

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: 'Find tools by describing the data or task.' It specifies a concrete verb (discover) and resource (tools), and implicitly distinguishes from siblings by being the only tool for tool discovery.

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

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

The description provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists example domains, helping the agent decide when 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?

Description adds value beyond annotations by detailing the parallel fan-out across sources, patent API soft-fail, fallback mechanism, and specific output fields including URIs. 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?

Front-loaded with example queries; each sentence contributes value. Slightly long but well-organized and informative, earning its length.

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

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

Despite no output schema, description thoroughly explains inputs, sources, return fields, and limitations. Comprehensive for a complex multi-source 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% (baseline 3). Description adds context: type must be "company", value can be ticker or zero-padded CIK, and clarifies names not supported. Provides additional helpful detail 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 creates a holistic profile of a US public company from multiple sources, with example queries. Distinguishes from chaining individual 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 to prefer over single-pack lookups for holistic views and notes names not supported, directing to resolve_entity. Provides 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?

Annotations already provide destructiveHint and idempotentHint. Description adds 'delete' and 'clear' which match annotations but no additional behavioral context beyond schema.

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 efficient sentences that cover purpose and usage without waste; front-loaded with core action.

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?

Complete for a simple delete tool with one parameter; annotations cover destruction; could mention irreversibility but not critical.

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

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

Schema coverage is 100% for the single parameter, and the description does not add meaning beyond what the schema already provides for the 'key' parameter.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb, resource, and method, and distinguishes from siblings by mentioning '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?

Provides explicit when-to-use scenarios (context stale, task done, clear sensitive data) and pairs with sibling tools, but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds process details (fetches page, extracts title/description/key links) beyond annotations, 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?

Front-loaded with core purpose, then process, output format, and use cases – 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?

No output schema, but description clearly explains output as a text blob for site-root placement. Input parameters and behavior are fully covered. Complete for this 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 description adds no further parameter-specific details beyond what schema already provides. Baseline 3 is appropriate.

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

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

Clearly states the tool generates a llms.txt file for any URL, describes the output format and use cases, and distinguishes from siblings like scan_competitor_ai_presence.

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

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

Explicitly lists three usage scenarios (client indexing, own project drafting, competitor auditing) though lacks explicit when-not-to-use examples.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by listing the returned fields and mentioning the include_inactive parameter, which annotations do not cover.

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

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

Two concise sentences: first states purpose and return fields, second gives usage guidance. 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?

The description covers purpose, return fields, usage context, and the optional parameter. It does not mention pagination or rate limits, but for a simple list tool these are minor omissions.

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 description does not need to add much. It mentions the parameter implicitly but does not expand beyond the schema definition.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the return fields (id, type, params, created_at, etc.). It distinguishes itself from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly advises when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and suggests 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 richly discloses behavioral traits beyond the annotations (which are all false/neutral): filing without an account returns a claim_token, passing it back later reads the resolution status, it's rate-limited to 5 per identifier per day, and it's free with no tool-call quota impact. No contradiction with annotations.

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

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

The description is longer than average but every sentence earns its place by covering purpose, usage boundaries, claim_token flow, rate limits, and quota semantics. It is well-structured and front-loaded, though slightly verbose.

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

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

For a tool with 4 params, a nested context object, and no output schema, the description fully covers the important operational details: what counts as valid feedback, how claiming works, rate limits, and the relationship to other servers. The absence of an output schema is compensated by the explicit claim_token explanation.

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

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

Schema description coverage is 100% and each parameter's description is self-explanatory. The tool description adds marginal context about claim_token usage and message specificity, but mostly restates what the schema already captures, so baseline 3 is appropriate.

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

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

The description clearly states the tool is for telling the Pipeworx team when something is broken, missing, or needs to exist, listing explicit use cases (bug, feature, data_gap, praise). This specific verb+resource framing clearly distinguishes it from sibling tools like ask_pipeworx or slack_send_message.

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 for each feedback category and explicitly warns against using this tool for other MCP servers' tools ('if the tool came from a different MCP server... file it with that server instead'). It also tells users how to check resolution via claim_token, giving clear context and 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?

The description adds significant behavioral context beyond annotations: it reveals caching behavior (5min-1h depending on window), data source (CF analytics-engine), and privacy (no PII). Annotations already declare readOnlyHint and idempotentHint.

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

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

The description is concise—three sentences plus a bullet-like list of use cases. Every sentence provides value, and the structure is easy to scan.

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

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

Given one optional parameter, no output schema, and comprehensive annotations, the description covers purpose, usage scenarios, caching, data source, and privacy. It is fully complete for an agent to decide when and how to invoke.

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

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

The single parameter 'window' has a clear enum with descriptions. The description adds nuanced meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps agents choose. Schema coverage is 100%.

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

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

The description clearly defines the tool as returning top tools, packs, and call volume over time windows (24h, 7d, 30d). It differentiates from sibling tools like discover_tools and ask_pipeworx by focusing on trending data rather than discovery or Q&A.

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

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

The description explicitly lists three specific use cases: discovering hot data sources, confirming canonical choices, and aligning use cases. It lacks explicit when-not-to-use guidance but provides sufficient context for appropriate usage.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: scanning logic, partition checks, semantic anchor (Jaccard similarity), partition filter (placeholder filter), fill check against CLOB depth, and response 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?

The description is long but well-structured with logical sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, explaining complex arbitrage logic. Could be slightly more concise, but the detail is justified by the tool's complexity.

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

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

Despite no output schema, the description defines the response structure (opportunities[], partition_check, fill check) and covers all aspects: usage modes, internal mechanics, edge cases (low similarity, placeholder filter), and trade viability conditions. No missing context.

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

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

Schema coverage is 100% with descriptions for both event and topic. The description enriches these with detailed explanations, examples (e.g., 'fed-decision-may-2026' for event, 'Strait of Hormuz traffic' for topic), and the internal logic behind each mode, adding significant value beyond the schema.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between no-args mode (trending scan), event mode (specific market), and topic mode (cross-event scanning), with specific verbs and resources.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It explains what cross-event catches that single-event misses. However, it does not directly compare to sibling tools like polymarket_edges or polymarket_fill_risk, which would further clarify 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 already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: model calculations, caching (KV keyed on knobs), response structure with segments, diagnostics for empty results, Fed bet handling. 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 comprehensive but verbose (multiple paragraphs). Well-structured with segment and knob sections, but some schema details are repeated. Front-loaded with purpose, but overall length could be trimmed for efficiency without losing value.

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

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

For a complex tool with 9 parameters and no output schema, description covers all necessary context: return structure (by_segment, fed_candidates, _diagnostics), edge calculation details, knob usage, and failure diagnostics. Completely sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds substantial meaning beyond schema: explains why each knob matters (e.g., min_liquidity drops thin-book opportunities, max_spread_pp ensures tight books), provides context for default values (e.g., slippage_pp default 0.3 with reasoning).

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. Specific verb 'scan' and resource 'Polymarket markets', with explicit model families and segments. Distinguishes from siblings by focusing on aggregated edge discovery.

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

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

Explicitly says 'Built for what should I bet on today' and provides guidance on when edge may be priced in. Discusses tradeable-edge knobs with usage advice. Lacks explicit comparison to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, though implicit differentiation exists.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details response structure (tracked, expired, snapshot_dates), explains snapshot gaps due to cache-miss, and specifies limitations like 60-day TTL and non-intraday decay. No contradictions with annotations.

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

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

The description is well-structured with clear sections but somewhat verbose in the response explanation. It is front-loaded with the core purpose and provides needed detail without unnecessary fluff.

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

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

Despite no output schema, the description fully explains the output structure and limitations. Combined with full parameter schema coverage, it provides a complete picture for the 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 description coverage is 100%. The description adds default values (14 days, '1wk') and constraints (max 30 days, window options) beyond the schema, including the meaning of 'window' as snapshot family.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers a specific question about edge longevity. It distinguishes from sibling tools like 'polymarket_edges' by focusing on persistence and trend analysis.

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

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

The description provides a clear usage context: 'a fresh wide edge and a 3-week-old wide edge are different trades'. It implies when to use this tool for persistence analysis but does not explicitly list alternatives or when-not-to-use scenarios.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds order-book walking behavior, return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), forced directional risk, and per-leg details. 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?

Well-structured with clear sections for single-market and basket modes, front-loaded with purpose. Slightly verbose but every sentence adds value for the 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?

No output schema, but description details all return fields and risks. Covers rationale, prerequisites, and limitations. Fully compensates for missing output schema with thorough behavioral description.

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 interpretation of size_usd as settlement notional in basket mode, explains side defaults per mode, and elaborates on return values. Adds significant meaning 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?

States 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with specific verb and resource. Differentiates two modes (single-market, basket) and explicitly ties usage to sibling tools 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Provides context on when not to use via risk of unhedged directional position, but lacks explicit 'when not to use' statement for small trades.

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

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

The description thoroughly discloses behavioral traits beyond annotations: explains why spreads exist (participant pools), when bet shapes are equivalent vs not, details safety fields (compatibility_warning, temporal_alignment, skipped counters), and warns about spread meaningfulness. Annotations indicate read-only, which aligns.

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 the core purpose, then explaining two modes, response format, and safety fields. Each sentence adds meaningful information without redundancy. Despite length, it remains focused and front-loaded.

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 compensates by detailing the response structure (leg-by-leg prices, top_spreads_pp, safety fields). It covers all aspects: purpose, modes, parameters, behavior, and limitations, making it complete for a complex tool.

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

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

The input schema already describes all three parameters (topic, kalshi_event_ticker, polymarket_event_slug) with examples. The description adds context about mode behavior (auto-fetch with topic, override with explicit) and clarifies that topic shortcuts are pre-mapped. This adds value beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It explains two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description implicitly guides usage by defining the tool's scope (cross-venue spreads) and warns that most pre-mapped topics return warnings ('Real cross-venue spreads are rarer...'). However, it does not explicitly contrast alternatives like polymarket_arbitrage for single-venue analysis.

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

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

Annotations already mark read-only, idempotent, non-destructive. Description adds behavior on omitting key (lists all) and scoping, which goes beyond annotations. 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?

Four sentences, front-loaded with action, no wasted words. Structure clearly states function, usage, scoping, and pairing.

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

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

For a simple read operation with one optional param and no output schema, the description covers retrieval behavior, listing, scoping, and pairing with siblings. Completely adequate.

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

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

Schema covers the single optional parameter with description; description adds context by explaining the key is user-saved data and pairing with remember/forget, adding 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?

Description clearly states the tool retrieves a saved value by key or lists all keys when omitted, with specific verb-resource pairing. It distinguishes from sibling tools 'remember' and 'forget' by mentioning they are complementary.

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 gives concrete examples of when to use (look up stored context like ticker or address) and mentions scoping by identifier. It does not explicitly exclude alternatives but provides sufficient context for an agent to decide.

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

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

Annotations already indicate a safe, idempotent read operation. Description adds context about returned fields (source, citation_uri, raw payload) and the effect of mark_read, enhancing understanding beyond annotations.

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

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

The description is concise and front-loaded with the main purpose. It includes necessary details in a single paragraph, though a more structured format could improve readability.

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

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

Covers key aspects: return fields, filtering options, mark_read behavior, polling suitability, and an alternative endpoint. Lacks explicit mention of limit and unread_only parameter details, but adequate for a simple read tool.

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

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

Schema coverage is 100% with descriptions, but the tool description adds value by explaining parameter usage in context (e.g., example values for type, effect of mark_read). This provides richer meaning.

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

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

The description clearly states the tool returns fired events from a subscription feed, specifying the resource and action. It distinguishes from siblings like list_subscriptions and subscribe by focusing on event retrieval.

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 guidance on filtering and marks the tool as suitable for polling. Mentions an alternative REST endpoint for scripts/dashboards, but does not explicitly state when not to use this tool versus others.

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

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

Describes fan-out behavior, fallback mechanism (GDELT to GNews), and soft-fail for USPTO due to API sunset. Annotations already declare readOnlyHint, idempotentHint, etc., and description adds valuable behavioral context 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?

Packed with information in a single paragraph, front-loaded with example queries. Slightly dense but no wasted words; could be broken into shorter sentences for readability.

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

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

Given no output schema and complex behavior (multiple sources, fallback, soft-fail), description fully explains what the tool returns (changes grouped by source, total_changes count, URIs) and handles edge cases (USPTO soft-fail). No gaps.

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

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

Schema coverage is 100%. Description adds context for `since` (ISO/relative shorthand, examples) and `value` (ticker or CIK), going beyond schema descriptions. Could provide slight more detail on `type` but it's minimal.

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 starts with example user queries and clearly states the tool provides a change feed for a company in a time window, fanning out to multiple sources. It distinguishes from sibling entity_profile by specifying what entity_profile is for.

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 provides usage examples ('What's new with X') and directly tells when to use the alternative entity_profile tool ('Use entity_profile instead when you want the static profile... regardless of window'). This gives clear guidance on tool selection.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false. The description adds context beyond annotations by explaining the persistence model (persistent for authenticated users, 24h for anonymous sessions) and the scope by agent identifier. However, it doesn't discuss potential side effects or rate limits, which are relevant for a write operation.

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 at 4 sentences, each serving a clear purpose: purpose, usage scenario, technical details, and sibling references. It could be slightly tighter (e.g., merging the second and third sentences), but overall well-structured and front-loaded.

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

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

The description covers all important aspects for a simple key-value store tool: purpose, when to use, storage mechanics, persistence, and relationship with sibling tools. No additional context is needed given the tool's simplicity and the annotations provided.

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 baseline is 3. The description adds value by providing naming conventions for keys (e.g., 'subject_property') and clarifying that values can be any text. This goes beyond the schema's generic 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: 'Save data the agent will need to reuse later.' It uses specific verb ('Save') and resource ('data'), and distinguishes itself from siblings like 'recall' and 'forget' by mentioning them explicitly.

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

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

The description provides explicit guidance on when to use the tool: 'when you discover something worth carrying forward.' It also explains the storage mechanic (key-value pair, scoped by identifier), persistence details (authenticated vs anonymous), and direct alternative tools ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that: it mentions cascading through multiple internal endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit reporting of unresolvable identifiers. These details help the agent anticipate failure modes and understand the tool's internal composition.

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 somewhat long but well-structured: it starts with real-world query examples, states the core purpose, then organizes details into 'SUPPORTED TYPES' with nested sub-bullets. Every sentence contributes unique information—no filler. It could be tightened by trimming redundant examples, but the front-loading and clear structure keep it effective.

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

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

With no output schema, the description carries the burden of explaining return values and behavior. It fully covers both supported types, states what identifiers are returned for each, how unresolved IDs are handled, and what happens during partial failures. It also provides enough context to differentiate from sibling tools and satisfies the requirements for a complex, multi-endpoint tool.

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

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

Schema coverage is 100% with descriptions for both `type` and `value`. The description significantly enriches this by explaining what each `type` returns (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug), what inputs each accepts, and how enrichment degrades. This exceeds the schema's basic enum and example hints, adding contextual meaning.

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

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

The description opens with natural-language query examples that make the tool's purpose immediately recognizable, then states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This clearly distinguishes it from sibling tools like entity_profile and compare_entities by focusing on identifier lookup rather than profiling or comparing. The explicit 'Use FIRST' guidance reinforces its specific role.

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

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

The description provides explicit 'when to use' guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives concrete example queries and notes it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: it details the probing process (invoking ai_visibility_check per entity), output structure (ranked list with score, confidence, signal density), and requirement for Anthropic API key when using that model.

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

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

Two sentences, front-loaded with purpose and key behavioral details. Every sentence is informative and concise, with a concrete use case example.

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 and no output schema, the description covers input, process, and output well. It explains the return format (ranked list with metrics). Lacks edge cases (e.g., entity not found), but overall sufficient for an agent to select 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 description coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity in 'entities' is treated as the subject for narrative, and clarifies that 'models' defaults to workers-ai and that '_apiKey' is only needed for 'anthropic'. This goes beyond 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 compares AI visibility across multiple entities side-by-side, specifying it probes each entity, ranks by score, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (more general).

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 'Useful for competitive AI-marketing audits' and gives a concrete question example. However, it does not explicitly state when not to use it (e.g., for single entity checks, use ai_visibility_check instead), but the context makes it 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 readOnly, idempotent, non-destructive. Description adds: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 thorough but front-loaded with key purpose. Every sentence adds value, though slightly long. 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?

No output schema, but description comprehensively details the return structure (summary block, per-advisory detail, links, alternative versions) and error handling (partial failures). Fully adequate for a 2-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% with descriptions. Description adds examples for scoped packages and version format, providing extra 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?

Description clearly states it is a composite check for npm packages, combining deps.dev and bundlephobia. It explicitly scopes to NPM and distinguishes from sibling tools that cover other ecosystems.

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 agent asks is X safe / popular / small' and provides exclusion: for PyPI/Maven/Cargo/Go, use deps.dev:version directly.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes beyond by detailing the implementation: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. It also describes the output format (passages with character offsets and similarity scores). This level of behavioral detail is excellent for the agent.

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 (5-6 sentences), front-loads the core purpose, and every sentence adds value: usage guidance, pairing suggestion, technical details, and output description. No redundancy or wasted words.

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

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

Given no output schema, the description adequately explains return values (passages with offsets and scores). It covers truncation behavior, embedding model, window size, and char cap. It also contextualizes with related tools. Complete for a search tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description provides examples for the query parameter and restates the char cap for text, but does not add substantial new meaning beyond the schema. The limit parameter is similarly described. Minor value added but not enough to raise the 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 performs semantic search inside a previously fetched record, using specific verbs like 'semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K body, article). It distinguishes itself from siblings by emphasizing the use case of large records that are too big for the prompt, and mentions pairing with ask_pipeworx_grounded, which differentiates it from other search or Q&A 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 explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt' and suggests a workflow with ask_pipeworx_grounded. It does not explicitly state when not to use or list alternative tools, but the context is clear enough for an AI agent to decide. The pairing guidance adds value.

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 the auto-join behavior, which is a useful trait not covered by annotations.

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

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

Two concise sentences with no wasted words. The description is front-loaded with the core purpose followed by an important behavioral note.

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 presence of an output schema and detailed parameter schema, the description provides sufficient context (auto-join). It could mention pagination, but that is covered in schema. Overall adequate.

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

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

Schema coverage is 100% with good descriptions for each parameter. The tool description adds no additional parameter meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool gets message history from a Slack channel and adds a key behavioral detail (auto-join). It is distinct from sibling tools like slack_send_message or slack_join_channel.

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 indicates usage for retrieving history but does not explicitly compare with alternatives or specify when not to use it. The auto-join note provides some implicit 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?

ReadOnlyHint annotation is set to true, but the tool performs a mutation (joining a channel), contradicting the description. The description itself does not disclose any additional behavioral traits beyond the annotations. This is a serious inconsistency that could mislead an agent.

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 sentence (12 words), front-loaded with action and purpose. No wasted words. Highly efficient.

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

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

Given low complexity (1 param, output schema present), the description is mostly complete. Could mention that the tool is idempotent (per annotation) or that joining is required for other Slack tools, but not essential.

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 one parameter. The description adds semantic value by specifying the channel must be 'public', which is not in the schema. This helps differentiate from private channels that might require an invite.

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 action 'Join', resource 'public Slack channel', and purpose 'so the bot can read history and post messages'. However, does not differentiate from sibling tools like slack_channel_history or slack_send_message, which require prior channel membership.

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 use as a prerequisite for reading history and posting messages, but no explicit guidance on when not to use (e.g., if already joined) or alternatives (e.g., slack_send_message for posting without joining, if bot is already in channel). Lacks context about permissions or channel visibility.

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, and non-destructive behavior. The description adds that it returns channel names, IDs, and metadata, which is consistent and slightly enhances transparency.

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?

Extremely concise: two sentences, 12 words, no filler. Front-loaded with the core action and output. Every word earns its place.

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

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

Given the presence of an output schema, good annotations, and full parameter schema coverage, the description adequately covers the tool's purpose and output. No missing context.

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

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

Schema description coverage is 100%, so the input schema already fully describes all parameters (limit, types, cursor). The description adds no additional meaning beyond what the schema provides.

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

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

Description clearly states the tool lists channels in a Slack workspace, with specific verb 'list' and resource 'channels'. It differentiates from sibling tools like slack_channel_history, slack_join_channel, etc., by focusing solely on listing channels.

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 usage context (listing channels) but does not explicitly state when not to use or provide alternatives. Sibling tool names help differentiate, but the description itself lacks direct guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds that it returns 'user profiles, IDs, and status,' which is not in the annotations.

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

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

Single, front-loaded sentence with no filler. Every word provides 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?

The description covers purpose and return content. Missing mention of pagination, but schema handles it. With rich annotations and output schema, description is adequate.

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 describes both parameters (limit, cursor) with clear details. Description adds no further parameter meaning, so baseline 3 applies.

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

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

Description clearly states verb 'List' and resource 'users in the Slack workspace,' and differentiates from sibling tools like slack_list_channels and slack_send_message.

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 guidance on when to use this tool vs. alternatives (e.g., search_within, entity_profile) or when not to use it.

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

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

The description adds behavioral context beyond annotations: 'Bot auto-joins the channel if needed.' This discloses a side effect (joining a channel) that is not evident from the annotations alone.

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

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

The description is two concise sentences with no wasted words. It is front-loaded with the core purpose followed by a key behavioral detail.

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

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

For a simple tool with full schema coverage and an output schema, the description adequately covers the main action and a notable side effect. It could mention error scenarios or permission requirements, but given the context, it is solid.

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 tool description itself does not elaborate on parameters, but the input schema has 100% coverage with clear descriptions (e.g., text supports Slack markdown). According to the rule, 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 specific action: sending a message to a Slack channel. It distinguishes from sibling tools like slack_join_channel (joining a channel) and slack_channel_history (reading history) by its verb and resource.

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 implicitly suggests usage by mentioning auto-join, indicating that prior channel joining is unnecessary. However, it does not explicitly state when to use this tool over alternatives or provide 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?

The description adds behavioral details beyond annotations: requires specific account type, returns subscription id, SMS cap of 10/day, webhook auto-disabled after 10 consecutive fails, and phone verification requirement. Annotations indicate idempotentHint=true and destructiveHint=false, which align with the described behavior.

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

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

The description is well-structured with clear sections for requirements, types, and delivery channels. It is comprehensive but slightly verbose; some sentences could be streamlined without losing clarity.

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

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

The description covers all necessary aspects: purpose, return value, account prerequisites, supported subscription types with examples, delivery options with constraints, and failure behavior. It is complete for a creation tool with 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?

Schema coverage is 100%, and the description adds significant meaning: explains enum values for type, provides type-specific param examples for each subscription type, and details delivery object constraints (SMS must match verified phone, webhook returns secret, email validated). It goes beyond the schema's brief descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription and returns the subscription id. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and providing specific event types and delivery channels.

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 specifies requirements (Pipeworx OAuth account, cannot use anonymous/BYO) and supported types with examples. It provides context on when to use this tool but does not explicitly state when to use alternatives or exclude specific scenarios.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. Description adds behavioral details: returns live catalog examples with tool shapes, and mentions optional topic filtering. 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 well-structured: starts with a clear summary, lists categories, and ends with usage advice. Every sentence is meaningful, 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?

For an onboarding tool, the description fully explains what it returns (category-bucketed examples with tool shapes), how to customize (topic parameter), and when to use (first interaction). No output schema is needed given the clear description.

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

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

Schema has 100% coverage for the 'topic' parameter. Description adds value by listing example topic values (finance, pharma, etc.) and explaining the behavior when omitted (full spread).

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 is for onboarding, returning example questions and tool arguments. It specifies the resource (Pipeworx) and the action (suggest questions), and distinguishes it from siblings by being the 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?

Explicitly states 'Use this FIRST' when unsure what Pipeworx can do, and gives context about returning category-bucketed examples. No explicit when-not-to-use, but the guidance 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), description reveals ownership enforcement and soft-deactivation (row deactivated, not deleted). Adds critical behavioral context.

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

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

Two sentences: first states action, second adds constraints and behavior. Front-loaded, 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 one-parameter tool with no output schema, description covers purpose, usage, and behavioral nuances completely.

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

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

Schema covers parameter fully (uuid description). Description adds no new semantic info beyond 'by id' context, which is already implied.

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

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

Title 'Unsubscribe from Alerts' and description 'Cancel a subscription by id' clearly state the action (cancel) and resource (subscription). Distinct from sibling 'subscribe'.

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 'you can only cancel your own subscriptions', setting clear usage boundaries. No alternative named, but context is sufficient.

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

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

Despite annotations already covering safety (read-only, idempotent), the description adds crucial behavioral semantics: the meaning of could_not_verify (check did not happen, must not be shown as evidence) versus unsupported, the verdict categories, and the distinction between the SEC EDGAR fast path and the grounded pipeline. This goes far beyond what annotations provide.

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

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

The description is dense yet well-structured: opens with natural-language trigger examples, defines the core purpose, explains the two routing paths, lists the return values, and provides an important caller warning. 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?

With no output schema, the description fully explains the return verdicts, the grounded or structured actual value with citation, and the reasoning field. It also clarifies error semantics (could_not_verify vs unsupported) and mentions the tolerance behavior, making it complete for a tool of this complexity.

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

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

The input schema already documents both parameters thoroughly (claim with examples, tolerance_pct with range and override behavior), so schema coverage is 100%. The description does not add new parameter-level meaning beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description clearly states it performs natural-language claim verification against authoritative sources, with a specific verb and resource. It distinguishes two paths (company-financial via SEC EDGAR, and any other factual claim via grounded pipeline), making its purpose unmistakable and distinct from sibling tools like deep_research or ask_pipeworx.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use. However, it does not explicitly name alternatives for non-verification queries or state when not to use, though the routing details and replacement of multiple calls give good context.

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