Findymail

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

Disclosures beyond annotations: return format includes score, confidence, signals, raw_response per model plus combined view. Notes that _apiKey is passed directly to Anthropic, ensuring security transparency. 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?

Four sentences, front-loaded with main purpose. Every sentence adds value (model details, return format, use cases). No waste.

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

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

Despite no output schema, description details return shape. All parameters explained with semantics. Annotations cover safety. 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?

100% schema coverage but description adds critical context: default model is Workers AI Llama-3.3-70b, _apiKey enables Anthropic probing, and context parameter helps disambiguate. Adds 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?

Clearly states the tool probes LLMs for knowledge about entities and returns visibility scores (0-100). Distinguishes from sibling 'scan_competitor_ai_presence' by focusing on per-model scoring and specific models (Workers AI, Anthropic).

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Explains when to use model selection (default free, Anthropic with API key). Does not mention alternatives like scan_competitor_ai_presence but still 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds behavior beyond them: delegation to thousands of downstream tools, automatic argument filling, and stable pipeworx:// citation URIs. No contradiction with annotations; a small deduction for not disclosing confidence or failure behavior for a router of this scope.

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?

Long but every sentence earns its place: the highest-value decision rule ('PREFER OVER WEB SEARCH') is front-loaded, followed by mechanism, trigger phrases, examples, then sibling routing. For a tool spanning 1,517 sources, this length is appropriate and nothing reads as filler or repetition.

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

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

This is a broad-scope router with no output schema, and the description compensates fully: it states the return format (structured answer with pipeworx:// citations), source scope, trigger conditions, and sibling boundaries. Invocation complexity is low (one free-text natural-language parameter), and nothing needed for correct selection or call formation 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 coverage is 100% — the question parameter and all five aliases (q, text, input, query, prompt) have descriptions plus schema examples, so the baseline is 3. The description lifts it to 4 by specifying what constitutes a good value: factual questions about real-world entities/events/numbers, trigger phrases, and six concrete sample queries. A 5 would require clarifying nuances such as single-question-per-call limits.

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

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

The description states a specific verb-resource mechanism: 'Routes the question to the right one of 5,798 tools across 1517 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It is clearly distinguishable from sibling tools because it names ask_pipeworx_grounded and deep_research as the alternatives with different behaviors.

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?

Opens with an explicit 'PREFER OVER WEB SEARCH' directive, enumerates trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), lists covered domains, and provides concrete example questions. It also gives when-not guidance by routing to ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part fan-out, so selection between siblings is unambiguous.

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

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

The annotations already provide the read-only, open-world, and idempotent profile, and the description adds meaningful mutable behavior: candidate routing improvements may be enabled live, none are active right now, and the last one was retired on a specific date. This gives an agent realistic expectations about experimental variability and confirms there is no hidden fallback.

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

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

The description is compact but dense: every sentence contributes either identity, current behavior, usage direction, or a critical clarification about fallback. It is front-loaded with the core identity and immediately orients the agent.

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 what the tool is, when to use it, its experimental nature, current state, and lack of fallback. The only minor gap is that the response contract is stated only as 'same response shape' rather than concretely described, and there is no output schema to fill in that detail.

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

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

All six parameters are fully documented in the schema as natural-language question text or aliases, so description-level parameter guidance is not necessary. The description only says 'same arguments as ask_pipeworx' without adding semantics beyond what the schema already provides, which matches the baseline for high schema coverage.

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

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

The description immediately identifies the tool as a beta version of ask_pipeworx and specifies that it is an identical universal router with the same 5,798 tools, arguments, and response shape. This clearly communicates the function and distinguishes it from the stable ask_pipeworx sibling via the experimental edge.

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 to use it exactly like ask_pipeworx when you want the newest routing, and it explains that results are compared against the stable router. It also clarifies that no candidate is currently active, so the tool currently matches ask_pipeworx exactly, and that it does not fall back to anything because it is a full working router.

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 goes well beyond this by explaining the refusal contract: explicit refusal_reason enum ('not_in_source', 'no_tool_match', 'tool_error', 'data_truncated', 'llm_error'), the success payload shape including verbatim evidence, and the extra LLM call cost. It also states that answers are extracted only from tool results, which is a meaningful behavioral guarantee not present 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?

Each sentence earns its place: purpose and grounding mechanism, success/refusal return contract, explicit use cases, and cost tradeoff with a routing recommendation. The most critical information is front-loaded, and the structure is highly scannable despite the density.

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 one meaningful parameter and no output schema, this description is comprehensive: it specifies the exact success response shape, all possible refusal reasons, when to use vs avoid, and the cost implication. Nothing an agent needs to correctly invoke and interpret this tool is missing.

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

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

The input schema covers all six parameters with 100% coverage, describing the main 'question' field and listing five aliases. The description references the question implicitly but adds no new parameter-level semantics. Baseline 3 is appropriate because the schema already handles parameter meaning completely.

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

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

The description opens with a specific, distinctive purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clarifies the verb (answer), resource (Pipeworx data across thousands of sources), and the grounding mechanism ('EXTRACTS the answer using ONLY what the tool result contains'). It is clearly differentiated from the sibling ask_pipeworx by emphasizing evidence and refusal behavior.

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 criteria are provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives an explicit exclusion: 'prefer ask_pipeworx for casual lookups.' This directly contrasts with the sibling tool and leaves no ambiguity about when to choose grounded mode.

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 extensively discloses behavioral traits beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details fan-out behavior, response shapes, resolver contract, parent_event extraction, news field fallbacks, safety mechanisms, and resolution-rule risk. No contradictions with annotations.

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

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

The description is extremely verbose, running hundreds of words without clear structural breaks. While highly informative, it lacks conciseness and front-loading of key information. Critical details are buried in a dense paragraph, making it harder for an agent to quickly parse.

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

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

Despite no output schema, the description comprehensively explains all return fields: result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields, safety conditions, and resolution-rule risk. It covers edge cases like closed markets, low-confidence matches, and wide spreads, making the tool's behavior fully predictable.

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 acceptable input formats for 'market', depth options ('quick' vs 'thorough'), and the 'include_raw' parameter's impact on response size. Provides examples and clarifies default behavior.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, fanning out to data packs, and returning evidence. It uses a specific verb ('Research') and resource ('Polymarket bet'), distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say', 'is there edge in Z') and includes many examples. It also mentions when the tool short-circuits (low-confidence, closed markets, wide spreads). However, it does not explicitly contrast with sibling tools or state when to use 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 adds significant behavioral context beyond annotations: it details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, sorting by primary metric, and return of citation URIs. Annotations already indicate read-only, idempotent, non-destructive, and open-world, and the description aligns well.

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 comprehensive but slightly verbose; however, every sentence adds value. It is well-structured with example queries up front. Could be marginally tighter, but overall efficient.

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

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

For a tool with no output schema, the description adequately describes the return format (paired data + citation URIs, sorted by primary metric). It covers both entity types and mentions edge cases (off-calendar fiscal years). No critical gaps are apparent.

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

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

Although the input schema covers both parameters (100% coverage), the description enriches understanding by explaining what data each entity type pulls (financials vs. adverse events), specifying the format for values (tickers/CIKs for company, names for drug), and enforcing bounds (2-5 items). 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 performs side-by-side comparisons of 2-5 companies or drugs, citing specific query examples like 'compare X and Y' and 'which is bigger'. It distinguishes itself from sequential single-pack lookups, making its purpose distinct from sibling tools.

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

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

The description explicitly states when to use this tool (comparisons, ranking, head-to-head) and when to prefer it over alternatives, saying 'ALWAYS PREFER over sequential single-pack lookups'. It effectively guides the agent to choose this tool over sequential single-entity lookups.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description goes well beyond that: account/paywall caveats, parallel decomposition into 5,798 tools, gap[] behavior ('never invented'), contradictions[] on certain depths, hop semantics, citation_uri fetchability guarantees, semantic excerpting rather than head-truncation, and realistic latency expectations. This is rich behavioral disclosure that materially affects invocation decisions and result interpretation.

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

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

The description is long but every sentence carries actionable information: requirements, alternatives, core mechanism, output structure, failure behavior, latency. It front-loads the critical gate (account required, use ask_pipeworx otherwise) before diving into mechanics. For a tool this complex, the density is justified and there is little fluff or repetition.

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

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

Despite having no output schema, the description fully explains what the agent will receive: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It also covers prerequisites, pricing tiers, latency, and sibling alternatives. Nothing an agent needs to safely invoke this tool or interpret its results 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 coverage is 100%, so baseline is 3, but the description adds significant value: it explains the practical behavioral differences between depth values (quick=3 single hop, standard=3 with gap recovery and contradictions scan, thorough=6 paid with iterative chase), and it clarifies that 'question' is free-form, natural language, and explicitly supports broad/multi-part input. This goes beyond the enum labels and parameter names.

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

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

The description states a specific verb and resource: 'grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call, and explicitly distinguishes itself from open-web search and from ask_pipeworx. It also enumerates concrete use cases and example questions, so an agent can immediately understand what this tool does and how it differs from siblings.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and explicit when-not-to-use recommendations: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx', plus a current-news caveat. It even names the alternative and the reasoning, leaving no ambiguity for tool selection.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This informs the agent about the return format and readiness for subsequent calls.

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 for its content: it states purpose, use case, domain list, return format, and a 'call this first' recommendation. It avoids unnecessary words but could be slightly shorter without losing meaning. The front-loading is good (first sentence gives the 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?

Given the tool's complexity (6 parameters, no output schema), the description covers the return format sufficiently: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)'. It also lists example queries. Since there is no output schema, this explanation is necessary and adequately 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 the schema already documents all 6 parameters, including aliases for 'query'. The description adds minor value by noting that 'limit' has default 20 and max 50, and that aliases like 'task', 'q', 'search', 'description' are accepted. This is helpful but not essential beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a detailed list of domains (SEC filings, financials, etc.), making the resource scope explicit. This distinguishes it from sibling tools like 'deep_research' or 'validate_claim' which have different purposes.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to invoke this tool, including a priority hint relative to other tools.

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

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

The description goes far beyond the readOnly/idempotent annotations by explaining real behavioral nuances: empty sections are genuine 'no data' rather than bugs, sources_used/sources_failed report per-company results, patents API soft-fails during sunset, and private companies return resolved:false with an explicit notes line. This is exceptional transparency for 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?

The description is long but dense and front-loaded, starting with example queries and the core purpose before moving into sources and edge cases. Each section adds meaningful operational guidance; the main flaw is modest redundancy with the input schema, re-listing accepted value shapes that are already documented.

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 what the agent will receive. It names the data sources, returned sections, resolved_from/resolved_to fields, recent_filings URI format, fundamentals examples, and source_failures semantics. An agent can confidently call the tool and interpret its response without further 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 baseline is 3, but the description still adds value by emphasizing that 'company' and 'ticker' are interchangeable and that names resolve via SEC EDGAR's company-name match. It also clarifies the private-company fallback behavior tied to the value parameter. This goes beyond simple schema restatement, though some repetition exists.

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: a full cross-source profile of a US public company in one parallel call, with concrete trigger phrases like 'Tell me about X' and 'brief me on Tesla'. It also distinguishes itself from chained single-pack lookups and notes that person/place support is not yet available, so an agent can tell it apart from neighboring tools.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a direct when-to-use rule. It also explains what inputs are accepted and what happens for private companies, so the agent knows not to expect a profile for those.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds details about output (verified business email, job title, LinkedIn) which enriches behavioral understanding 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?

Two sentences plus an example, all essential and front-loaded. No redundant information.

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

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

Description covers purpose, inputs, and output format. While no output schema, the description hints at return fields. Missing details on error handling or rate limits, but overall adequate for a simple lookup tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds an example with actual values and clarifies domain format ('no protocol'), providing additional context beyond the schema descriptions.

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

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

Description clearly states the tool finds work emails for a person given name and company domain, with specific output including job title and LinkedIn. It distinguishes itself from the sibling 'findymail_reverse_email' implicitly by focusing on forward lookup.

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 provides context 'B2B prospecting / outreach' and an example, making usage clear. However, it does not explicitly contrast with the sibling tool 'findymail_reverse_email' or mention when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds minimal behavioral context beyond the purpose (e.g., it does not mention rate limits, auth requirements beyond the API key parameter, or that results may be incomplete). It does not contradict annotations.

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

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

The description is concise: two sentences that immediately state the action and outputs, followed by an example. Every part adds value, and there is no unnecessary text.

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 (2 parameters, no output schema, no nested objects), the description covers what is needed. It states input, output, and provides an example. No missing context given the tool's complexity.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description adds an example call with realistic values, which helps clarify how to use the parameters. This addition slightly improves understanding beyond the schema's 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: 'Look up the person/LinkedIn profile behind an email address'. It specifies the input (email) and outputs (name, company, job title, LinkedIn URL). The verb 'Look up' and resource 'person/LinkedIn profile' are specific. The tool name includes 'reverse_email', which contrasts with the sibling 'findymail_find_email', providing implicit distinction.

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

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

The description includes an example call and explains what the tool does. However, it does not explicitly state when to use this tool over its sibling 'findymail_find_email' or other tools. The naming implies the direction, but explicit guidance would be clearer.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; description adds 'clear sensitive data' context but does not disclose additional behavioral traits 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?

Two sentences, front-loaded with purpose, followed by usage guidance. No redundant or unnecessary words.

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

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

For a simple delete operation with one parameter and no output schema, the description covers the essential aspects: action, when to use, and related tools.

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 'key' described as 'Memory key to delete'. The description adds no extra semantic meaning beyond the schema, 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?

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

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

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

Explicitly says when to use (stale context, task done, clear sensitive data) and pairs with remember and recall, providing clear 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 declare it as read-only and idempotent. The description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format. This explains the behavioral traits beyond the annotations.

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

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

The description is concise, with two clear sentences and a bullet list of use cases. It is front-loaded with the main action and is free of 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?

Given the simple parameters and no output schema, the description provides sufficient context: input, process, output format, and use cases. It covers what is needed for the agent to invoke the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description does not add significant meaning beyond the schema for the parameters (url and max_links). It mentions extraction but not how max_links impacts behavior.

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 generates a production-ready llms.txt file for any URL, specifying the extraction process and output format. It distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description lists explicit use cases: indexing a client's site, drafting for own project, auditing competitors. While it doesn't explicitly state when not to use it, the use cases provide clear 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 and idempotentHint. The description adds that it lists active subscriptions by default and mentions the returned fields, which is consistent and slightly extends transparency. No contradictions.

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

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

Two sentences, no unnecessary words. Purpose and usage are front-loaded. Every sentence adds value.

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

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

For a simple read-only list tool with no pagination parameters, the description covers purpose, output fields, and parameter behavior. Lacks details on sorting or limits, but this is acceptable given the tool's simplicity.

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

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

Schema coverage is 100% for the single parameter include_inactive, and its description explains usage. The tool description adds context about default behavior, but this is already implied by the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List', resource 'subscriptions', and scope 'caller's active', which distinguishes it from sibling tools like subscribe and unsubscribe. The returned fields are listed, providing specific value.

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

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

The description explicitly states when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context and implies alternatives (subscribe, unsubscribe).

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 are all false, so the description carries full behavioral burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and the token-based async workflow ('Filing without an account returns a claim_token... pass it back later'). No contradiction with annotations.

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

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

The description is long but every sentence earns its place: purpose is front-loaded, usage triggers are enumerated, exclusions are explicit, and workflow/limits are included. No redundant or filler content.

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

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

For a feedback tool with 4 parameters, nested context, and no output schema, the description fully covers what the agent needs to know: when to use, what to include, how claim_token works, rate limits, and intended audience. The lack of a structured return value is mitigated by describing the claim_token response behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond schema by explaining the claim_token's usage in context ('pass the pwfb_… token that filing returned, with no other arguments'), and by advising not to paste the end-user's prompt, which clarifies the message field's intended content.

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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by scoping it to feedback about Pipeworx tools/packs and explicitly contrasting with tools from other MCP servers.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear exclusion—do not report issues for tools from other MCP servers—and explains the claim_token workflow for follow-ups.

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. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior, and that it's self-aggregating. 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?

Every sentence adds value. The description is front-loaded with the main result, uses bullet points for use cases, and is concise without being terse.

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

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

The tool is simple with one optional parameter and no output schema. The description explains what is returned (top tools, packs, volume) and caching. It could be more explicit about the exact output structure, but overall it's complete enough.

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

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

Schema covers the single parameter with an enum and description. The description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches beyond the schema's basic description.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window'. The verb 'returns' and resource 'trending signals' are specific. It distinguishes from siblings like 'discover_tools' by focusing on usage trends rather than tool listing.

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?

Three explicit use cases are listed, guiding when to use the tool. It does not explicitly state when not to use it or name alternatives, but the use cases provide clear context for selection among siblings.

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

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

Annotations indicate read-only, idempotent, open-world. The description adds extensive behavioral details: walking child markets, checking date-axis/threshold-axis ordering, partition checks with 3pp threshold, semantic anchor with 0.30 Jaccard similarity, placeholder filter, and fill check with realizable edge. This far exceeds what annotations provide.

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

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

The description is well-structured with clear sections for each mode, semantic anchor, partition filter, response, and fill check. It is somewhat lengthy but every sentence conveys necessary detail, making it earn its length. Slightly tighter could be possible.

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

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

Given the tool's complexity (multiple modes, internal algorithms, response structure), the description is remarkably complete. It explains the response format (opportunities array with fields), partition_check object in event mode, and fill check behavior. No output schema exists, but the description compensates fully.

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

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

Schema coverage is 100%, baseline 3. The description adds significant value by explaining event mode expects a slug or full URL, topic mode expects a seed question, and provides examples. It also describes internal behavior of each parameter, greatly aiding correct usage.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between no-args trending scan, event mode, and topic mode, and provides specific examples for each, making its purpose completely clear.

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

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

The description explicitly recommends when to use each mode: event for a specific market, topic for cross-event scanning, and no args for trending scan. It explains the rationale (cross-event catches patterns single-event misses) and even suggests using polymarket_fill_risk for custom sizing, providing excellent guidance.

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

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

The description adds extensive behavioral context beyond annotations: it details caching (1h at KV level keyed on knobs), the three model families with their internal mechanics (e.g., lognormal barrier, GDELT ratio, partition overround with sport-specific alpha), response structure (by_segment, fed_candidates, _diagnostics), and edge attributes (edge_pp_net, kelly_fraction, 24h-move warning). Annotations already declare readOnlyHint and idempotentHint, which this description fully supports without contradiction.

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

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

The description is lengthy but well-organized with sections for each model family, knobs, and response structure. It uses clear labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and bullet-like formatting. Some repetition (e.g., explaining partitions multiple times) could be trimmed, but overall it is front-loaded with purpose and efficiently packs detailed information.

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

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

Given 9 parameters (all fully described in schema), no output schema, and high complexity (three segments, multiple filters, diagnostics), the description is remarkably complete. It covers caching, the exact attributes returned per opportunity (edge_pp_net, kelly_fraction, etc.), the fed_candidates exclusion, and diagnostic counters. An agent has sufficient information to invoke the tool and interpret results correctly.

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

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

All 9 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds value by explaining knobs like max_spread_pp ('tight books'), min_liquidity ('walk the book past breakeven'), and min_partition_leg_kelly (why min_kelly doesn't apply to partition arbs). For slippage_pp, it adds context about zero fees but typical bid/ask impact. This extra explanation justifies a score above baseline.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, using the phrase 'what should I bet on today'. It specifies the action (scan, return), the resource (Polymarket markets), and the scope (discrepancies with Pipeworx data). This distinguishes it from sibling tools like polymarket_edge_tracker which tracks edges over time.

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

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

The description implies usage for discovering betting opportunities without paging through hundreds of markets, and explains the three response segments and adjustable knobs. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage or polymarket_fill_risk, leaving some ambiguity for an agent.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: snapshots have a 60-day TTL, decay is computed from daily closes (not intraday), and gaps occur when no scan ran. 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 detailed and front-loaded with the key question. It could be slightly more concise, but every sentence adds value, especially for the output structure. The length is justified given the output schema absence.

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

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

No output schema exists, so the description fully explains return values (tracked[], expired[], snapshot_dates[]) with field details and limitations (TTL, decay computation). It is comprehensive for a telemetry tool.

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

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

Schema coverage is 100%, with both parameters already described. The description adds minor context (e.g., default values and allowed values) but mostly repeats schema info. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' answering the question of how long an edge has existed and whether it is shrinking. It specifies the resource (daily polymarket_edges snapshots) and distinguishes from sibling tools like polymarket_edges by focusing on time-series and decay.

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

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

The description gives clear context on when to use the tool: when you need to know if an edge is persistent or decaying, and contrasts fresh vs old edges. It implicitly guides usage by describing the output structure, though it does not explicitly state when not to use or list alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are present and consistent. Description adds behavioral details beyond annotations: requires one of market/event, walks ladder, returns verdict and forced_directional_risk, and warns about dominant loss mode. No contradiction.

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

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

Description is lengthy but well-structured with clear sections for single-market and basket modes. Uses bold and uppercase for emphasis. Every sentence adds value, but could be slightly more concise without losing 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?

No output schema, but description fully explains return fields for both modes (top_of_book, vwap, slippage, shares_filled, max_fillable, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional, forced_directional_risk for basket). Also covers caveats and loss mode. Very 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%, but description adds important context: explains size_usd interpretation (spend vs proceeds for single-market; settlement notional for basket), side defaults (auto for basket), and parameter roles. Adds value beyond schema.

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

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

Description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explains two modes (single-market and basket) with specific outputs. Distinguishes from siblings like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable, partial fills cause directional risk), providing clear when-to-use and implicit when-not-to-use with 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 behavior beyond the annotations: it explains that matching is by keyword overlap, that pairing remains unverified, that compatibility warnings can coexist with matched pairs, that Kalshi fees are not modeled, and that spreads are gross not net. It also explains skipped/unclassified legs and the meaning of null temporal alignment. This is exemplary 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?

The description is long, but it is densely informative and organized into labeled sections covering modes, response fields, safety codes, fees, and skipped comparisons. Every section earns its place given the tool's complexity and the absence of an output schema, though some sentences could be tightened without loss of 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?

For a tool with three optional parameters, no output schema, and complex cross-venue semantics, the description is remarkably complete. It covers return-value structure, warning codes, edge cases, fee treatment, matching limitations, and the meaning of null/unknown values. An agent has nearly everything needed to invoke the tool and interpret its output safely.

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

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

Although the schema already documents all parameters at 100% coverage, the description adds substantial meaning: it enumerates the topic shortcuts, clarifies that explicit params override the mapped side, explains that both modes use the same matching logic, and warns about the tradeability implications. This goes well beyond the schema's basic descriptions.

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

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

The description clearly identifies a specific function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It describes the resource, the comparison, and the two modes of operation. However, it does not explicitly differentiate itself from related siblings like polymarket_arbitrage or polymarket_edges, stopping short of a full 5.

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

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

The description gives clear usage context: it explains when to use the topic shortcuts versus explicit event pairings, and warns that pre-mapped topics often return compatibility warnings and are not necessarily tradeable. It does not explicitly name alternative sibling tools or state when this tool should be preferred over them, so it lacks exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping details but does not significantly expand beyond annotations.

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

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

Three sentences, front-loaded with core purpose. Could be slightly tighter, but no waste.

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

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

Given the simple 1-param schema and clear annotations, the description covers function, scoping, and pairing with siblings. Lacks return format details but they are likely inferable.

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. The description adds meaning by explaining that omitting the key lists all keys and the purpose of retrieval.

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

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

The description clearly states the verb (retrieve/list) and resource (saved memory). It distinguishes from siblings by specifying pairing with remember and forget.

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

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

The description explains when to use (look up context stored earlier without re-deriving) and mentions scoping and pairing, but does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral details beyond annotations: it explains that mark_read:true flags events as read so the next call shows only newer ones, and it lists the fields returned. 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 a single, dense paragraph but front-loaded with the core purpose. Every sentence adds value, though it could be slightly more organized (e.g., bullet points for fields). It is efficient at 5 sentences.

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

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

Given the absence of an output schema, the description fully explains what is returned. All 5 parameters are addressed, and behavioral aspects like mark_read polling are covered. The tool's complexity is low, and the description is complete.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by providing examples ('sec_8k' for type, ISO timestamp for since) and explaining the effect of mark_read:true, which is not fully detailed in the schema.

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

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

The description clearly states the verb 'Pull' and resource 'fired events from your subscription feed', specifying what is returned (source, citation_uri, raw payload). It differentiates from siblings by focusing on a specific feed-reading action, not general search or subscription management.

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

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

The description mentions that polling works fine and provides an alternative HTTP endpoint for scripts/dashboards. While it does not compare to all siblings, it gives clear context for when to use this tool (to read the feed) and implies it is suitable for repeated calls.

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

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

Discloses fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback behavior, and return structure (changes[], total_changes, pipeworx:// URIs). Adds value beyond annotations which only indicate read-only, open-world, idempotent.

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, then details internal logic. Slightly long but well-organized. Every sentence adds value.

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

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

Given complexity (multiple sources, fallback, date handling, return format), description covers all needed context. No output schema, but return structure is described.

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

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

Schema coverage is 100%, but description adds practical context: explains 'since' with examples (ISO date vs relative shorthand, suggests defaults) and 'value' as ticker or CIK.

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

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

Description clearly states it provides a change feed for a company (e.g., 'What's new with X') and contrasts with sibling tool 'entity_profile' for static profiles. Uses specific verbs 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?

Explicitly provides example queries and states when to use vs. entity_profile. Gives practical guidance on 'since' parameter (e.g., 'Use "30d" or "1m" for typical monitoring').

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, which is consistent. Description adds behavioral details beyond annotations: authenticated vs anonymous session persistence (24 hours). No contradictions noted.

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

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

Single paragraph of 4 sentences, front-loaded with purpose and usage. Every sentence adds value with no redundancy. Extremely concise for the information conveyed.

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

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

Given simple tool (2 params, no output schema), description sufficiently covers persistence, scope, and pairing with other tools. Minor gap: does not mention error behavior or size limits, 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 covers 100% of parameters with descriptions. Description adds example patterns for key/value but does not provide substantial new meaning beyond the schema. Baseline score of 3 applies.

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

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

The description clearly states the tool saves data for reuse across sessions, using a key-value store. It distinguishes itself from siblings 'recall' and 'forget' explicitly, earning top marks for specific verb+resource and sibling differentiation.

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

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

Provides explicit when to use (discover something worth carrying forward) and mentions complementary tools (recall, forget). Lacks explicit 'when not to use' but context is sufficient 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 only declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes far beyond this: it details internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit behavior such as returning `figi_candidates` on ambiguous matches and placing unresolved identifiers under `unresolved`. It also discloses that certain securities (non-equity) resolve here, and that ISINs map to legal entities. This rich behavioral transparency is fully consistent with annotations and adds substantial value.

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 extremely well-structured: it opens with query examples and a priority instruction, then breaks down supported types with clear sub-bullets, and even includes a parameter-specific gotcha. No sentence is filler; every clause adds operational value. The structure front-loads the most critical usage guidance (when to use) and progressively details edge cases. It earns 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?

Given the tool's complexity (multiple entity types, multiple external sources, ambiguous matches, graceful fallbacks), the description covers all necessary aspects: supported input formats, output contents ('figi_candidates', 'unresolved', source labelling), failure modes, and performance implications (replaces 2-3 manual lookups). There is no output schema, so the description adequately explains what the agent can expect. An agent has everything needed to call this correctly.

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

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

The schema already describes both parameters at 100% coverage, but the description adds crucial semantic depth. For `value`, it explains that for bonds the issuer name must be passed exactly as printed and warns that trailing security-class words match nothing—critical detail not in the schema. For `type`, it details what each type returns (CIK, LEI, FIGI, RxCUI) and the sources. This transforms the parameter understanding from basic to operationally precise.

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

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

The description states a precise verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), with concrete example queries ('What's the ticker for…', 'find the CIK for…'). It clearly positions this tool as the identifier-resolution entry point, distinct from siblings like compare_entities or entity_profile by saying 'Use FIRST whenever you have a name but need an ID.' This makes the purpose unambiguous.

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

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

It explicitly instructs when to use: 'Use FIRST whenever you have a name but need an ID.' It also provides scenarios for each supported type (company, drug) and explains edge cases like bonds that never have a ticker, and the correct behavior for issuer names that match multiple instruments. While it doesn't list exclusions, the instruction to use 'FIRST' implies it precedes other tools. This is clear, actionable 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, idempotentHint, etc. The description adds behavior beyond annotations: it probes each entity with ai_visibility_check, returns a ranked list with score, confidence, signal density. 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 four sentences, front-loaded with purpose, and each sentence adds value. It is concise with no wasted words.

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

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

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density) and clarifies entity ordering. Given parameter count and annotations, it is 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%, and the description adds meaning: first entity is the subject, others are competitors; context disambiguates; models parameter options explained. This goes beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description explicitly frames the tool for competitive AI-marketing audits and implies use when comparing multiple entities rather than a single one (which would use ai_visibility_check). It provides clear context but does not explicitly list 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?

Annotations confirm readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral details: partial failure handling, bundlephobia's first measurement taking 5-30s, and sources_failed listing timeout. This goes beyond annotations and provides 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?

Two sentences, densely packed with purpose, data sources, return details, usage guidelines, and failure behavior. Front-loaded with the composite check concept. No superfluous 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?

Covers all necessary context: composite nature, data sources, return structure (summary, advisories, links, alternatives), partial failure, ecosystem limitation. Even without an output schema, the description explains what the tool returns in sufficient detail.

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 parameters are already well-documented. Description confirms that version is optional and defaults to latest, and mentions scoped packages are accepted. Adds marginal value over schema.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages using deps.dev and bundlephobia. It specifically mentions the verb 'scan' (composite check) on resource 'dependency' (npm package). The description distinguishes itself from siblings by specifying NPM ecosystem only and directing other ecosystems to deps.dev directly.

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

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

Provides explicit when-to-use guidance: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' Also gives a clear when-not-to-use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' No explicit alternatives among siblings, but the guidance is sufficient.

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

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

Beyond annotations, the description discloses embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character limit (200K chars), and behavior on truncation (flag). 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 front-loaded with purpose, uses bold for keywords, and every sentence adds value. No extraneous information. Approximately 100 words, well-structured.

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

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

Given no output schema, the description explains return format (passages with offsets and similarity scores), technical details, and truncation behavior. All necessary information for an agent to use the tool correctly.

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

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

Schema coverage is 100% (all params described). The description adds context like 'pass the text you already pulled' and example queries, providing richer guidance than the schema alone. Baseline 3, raised to 4 for added 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 'Semantic search INSIDE a fetched record' and provides specific examples (SEC 10-K, article). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and focusing on search within a single record.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It mentions a complementary tool (ask_pipeworx_grounded) but does not explicitly list 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?

Description adds significant behavioral context: authentication requirement (Pipeworx OAuth), delivery channel specifics (always-on feed, optional email/SMS with phone verification and 10/day cap, webhook with HMAC signing), and example configurations. Annotations indicate idempotentHint=true but description implies each call creates a new subscription (returns new id), which could be ambiguous but not a direct contradiction.

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

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

The description is a single dense paragraph; it front-loads the main purpose and key requirements. However, it could be more scannable with bullet points or separate sections for types and channels. No wasted sentences, but structure 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?

Given the complexity (multiple subscription types, delivery channels, authentication) and no output schema, the description covers the core functionality: it explains what the tool does, what it returns (subscription id), prerequisites, and examples. It lacks mention of failure modes or idempotency behavior, but is generally complete for an initial understanding.

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 coverage, the description still adds substantial value: for each type enum, it provides concrete examples and explains parameters (e.g., sec_8k with ticker and items, polymarket_edge with topic). For delivery, it elaborates on webhook signing and SMS cap, which are not in the schema. This goes well beyond the schema descriptions.

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

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

Title 'Subscribe to Alerts' and description 'Create a proactive monitoring subscription to a live-data event stream' clearly state the verb (create) and resource (subscription). It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of a subscription.

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 explicitly mentions requirement for a Pipeworx OAuth account, notes that anonymous and BYO accounts cannot persist subscriptions, and lists supported types and delivery channels. It implicitly guides when to use: when you need proactive monitoring. However, it does not explicitly state when not to use or alternative options beyond the type list.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context that it is safe and returns example questions, not performing any mutations. No contradiction.

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

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

The description is relatively long but front-loaded with purpose and includes necessary details. Every sentence adds value, though it could be slightly more structured.

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

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

Given no output schema, the description fully explains what is returned (category-bucketed example questions with tool calls). Covers parameter, usage context, and outcome. Complete for an onboarding 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. The description adds value by listing the topic options and explaining the effect of omitting it. This goes beyond the schema's brief description.

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

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

The description clearly states the tool is the onboarding entry point, returning category-bucketed example questions with exact tool calls. It uses specific verbs ('returns') and distinguishes from sibling tools like ask_pipeworx and discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains how to call with/without the topic parameter. Does not explicitly state when not to use, but context with siblings 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?

Adds helpful details beyond annotations: ownership enforced, deactivation not deletion, and link to recent_alerts. Consistent with idempotentHint and destructiveHint.

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 verb and resource, no extraneous content.

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

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

For a single-parameter tool without output schema, description covers effect, constraints, and relation to sibling tool (recent_alerts). Complete.

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

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

Schema coverage is 100% (parameter 'id' well documented). Description adds ownership enforcement context but no parameter-specific semantics 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?

Clear verb 'Cancel' and resource 'subscription by id'. Distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation semantics.

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?

States when to use (cancel a subscription) and hints at prerequisites (id from subscribe). No explicit exclusions or alternatives, but context is sufficient given sibling tools.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral details: the exact verdict enums, the meaning of "could_not_verify" (that the check did not happen) versus "unsupported" (no source covered), and the inclusion of verification_error details. This adds substantial transparency about failure modes and return semantics.

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 front-loaded with trigger phrases and the core purpose. Each sentence contributes useful information, including routing logic, output details, error semantics, and performance benefits. It is somewhat dense but appropriately detailed for a tool with complex behavior.

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, evidence citation, reasoning, and two distinct error conditions. It also covers the two main claim categories and how they are processed, making the description complete enough for an agent to invoke and interpret results correctly without extra context.

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

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

The input schema already covers both parameters with 100% description coverage, including examples and default behavior. The description adds practical guidance for tolerance_pct—such as setting 1–2 for hallucination detection and clarifying that it overrides the wording-implied tolerance—which gives it more value than a bare baseline of 3.

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

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

The description clearly identifies the tool as a natural-language claim verification/fact-checking tool with specific trigger phrases like "Is it true that…" and "verify the claim that…". It also distinguishes its scope from other tools by describing the structured SEC EDGAR path for company-financial claims and the grounded pipeline for all other factual claims.

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

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

The description explicitly states "Use whenever the agent needs to check whether something a user said is factually correct," providing clear when-to-use context. It also outlines how different claim types are routed, but it does not explicitly say when not to use this tool or name alternative tools, so it lacks a formal exclusion criterion.

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