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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond those: it routes to 5,529 tools, fills arguments automatically, returns stable pipeworx:// citation URIs, and emphasizes a single fast call with broad tier compatibility. This goes well beyond what annotations alone convey.

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

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

The description is dense but well-structured: it opens with a critical preference directive, explains the mechanism, gives examples, and then maps to related tools. Every sentence contributes to agent understanding, and the length is justified given the tool's routing complexity.

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

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

The description fully covers the tool's role, its relationship to sibling tools, expected input style, examples, and output characteristics (structured answer with citation URIs). Combined with solid annotations and high schema coverage, nothing critical 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%, with all parameters documented as aliases for 'question'. The description adds practical meaning by providing concrete example questions and describing what the 'question' should contain (natural language requests about real-world entities), but does not fundamentally extend the schema definitions.

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

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

The description clearly states the tool routes factual questions to a large set of verified sources and returns structured answers with citation URIs. It specifically distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

Explicit guidance is given: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with clear escalation paths to ask_pipeworx_grounded (single hallucination-resistant answer) and deep_research (broad/multi-part questions). It also clarifies that breaking-news queries still go through this tool.

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

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

The description adds valuable behavioral context beyond the annotations, such as the fact that candidate routing improvements are enabled live whenever under test, and that currently no candidate is active so it matches ask_pipeworx exactly. This explains the dynamic nature of the tool without contradicting the readOnly and idempotent hints.

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

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

The description is well-structured and front-loaded with key information about being a beta version. It is slightly verbose with three sentences, but each sentence carries distinct value, such as the current state of no active candidate and the usage instruction.

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 sufficiently covers the tool's purpose, relationship to siblings, current behavior, and usage. It addresses the lack of an output schema by stating the response shape matches ask_pipeworx, making the tool's behavior complete and 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?

The input schema has 100% description coverage for all parameters, including aliases, so the description does not need to add parameter-level details. It only references that arguments are the same as ask_pipeworx, but this does not meaningfully enhance the schema information.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, stating it is an identical universal router with the same 5,529 tools, arguments, and response shape. This distinguishes it from siblings like ask_pipeworx and ask_pipeworx_grounded by emphasizing its experimental status.

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

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

The description explicitly states when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it is not a fallback but a full working router, and that results are compared against the stable router, giving clear guidance on its role.

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, but the description adds substantial context: details on the verification process (only uses tool result), the specific return shape including evidence and refusal reasons, and the explicit refusal behavior when data doesn't answer. 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 dense but every sentence earns its place: it explains mode, routing, extraction process, return structure, usage cases, and cost tradeoff. It is front-loaded with the core purpose and structured logically.

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, but the description fully specifies the return object on success (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and the refusal object with enumerated reasons. It also covers failure modes and differentiates from sibling tools, making it sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100% for all 6 parameters, all aliases for 'question' are documented in the schema. The description does not add additional parameter semantics, but the schema already fully covers meaning, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads' and specifies the mechanism: it routes like ask_pipeworx, fetches data, and extracts answers only from tool results. It explicitly distinguishes from sibling ask_pipeworx by the grounded/refusal behavior and the return structure.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and contrasts with casual lookups by saying 'prefer ask_pipeworx for casual lookups.' It also notes the extra LLM call cost, enabling a cost-benefit decision.

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 indicate readOnly/openWorld/idempotent hints, and the description adds substantial behavioral detail: returns a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[] for unanswered facets, contradictions[] for deeper depths, and explicit 'never invented' guarantee. Also discloses latency ranges (15-60s, up to ~90s) and semantic excerpting behavior.

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

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

The description is long but densely packed with necessary caveats, depth mechanics, and output details. It is front-loaded with account requirements and alternatives, but contains some redundancy (e.g., repeated mentions of ask_pipeworx and contradictions) that could be tightened without losing meaning.

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

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

Given the tool's complexity and absence of an output schema, the description fully covers what is returned (findings packet with citations, gaps, contradictions), behavior of each depth tier, latency, prerequisites, and limitations for news topics. Nothing essential is omitted.

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

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

Schema coverage is 100% but the description enriches both parameters: 'depth' is explained with counts and hops (quick=3, standard=5, thorough=8) and default behavior; 'question' is specified as 'Broad/multi-part is fine — decomposition is the point', adding guidance 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 uses a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It clearly distinguishes from siblings by stating 'this is NOT open-web search' and naming ask_pipeworx as an alternative for different use cases.

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

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

Provides explicit when-to-use and when-not-to-use: 'Best for broad/multi-part questions over structured data' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also states account prerequisites and that ask_pipeworx works on every tier, covering both positive and negative usage guidance.

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

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

Annotations 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?

Annotations indicate read-only, idempotent, open-world. Description adds specifics: fans out across multiple APIs, returns structured data fields, mentions patents API sunset with soft-fail, and GDELT→GNews fallback. 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 dense but not overly verbose. Front-loads example queries and then details behavior. Could be slightly more concise, but every sentence adds value.

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

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

Given the tool's complexity (multiple sources, fallbacks, limitations), the description covers all relevant aspects: return fields, patent API status, name limitation, parallelism. No output schema, but description sufficiently explains return values.

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

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

Schema coverage is 100% with descriptions for both parameters. Description reinforces that names are not supported and clarifies value formats (ticker or zero-padded CIK). Adds context beyond schema.

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

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

Description clearly states the tool fetches a full cross-source profile for US public companies, with explicit verbs like 'tell me about' and 'research'. It differentiates from chaining single-pack lookups and lists specific data sources (SEC, XBRL, USPTO, news, GLEIF).

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

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

Explicitly says 'ALWAYS PREFER' over chaining lookups for holistic views, and warns that names are not supported—use resolve_entity first. Provides clear context for when to use and when to avoid.

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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description discloses how spreads are computed, when they are comparable (temporal alignment), and when they are not (compatibility_warning). It reveals internal logic about skipped cross-type/subtype counters, providing rich behavioral context.

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

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

The description is comprehensive but somewhat verbose. It front-loads the core purpose, then details modes and safety fields. All sentences are valuable, but could be tightened. Still well-structured and informative.

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

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

Given the tool's complexity (cross-venue, multiple modes, safety fields, pre-mapped topics) and no output schema, the description covers return values, edge cases, and limitations thoroughly. It leaves no major gaps for an agent to misunderstand.

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 means parameters are already documented, but the description adds deep context: it explains the topic values, how explicit tickers override defaults, and how the two modes interact. This goes well 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by focusing on cross-venue analysis and explicitly mentions that most pre-mapped topics return compatibility warnings, setting clear expectations.

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 two modes (topic shortcuts and explicit pairings) and provides clear when-to-use guidance. Safety fields (compatibility_warning, temporal_alignment) tell agents when spreads are not meaningful, and it explicitly warns that real spreads are rare, helping to prevent misuse.

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 indicate readOnly and idempotent hints, but the description adds significant behavioral context: graceful degradation of LEI/FIGI enrichment, explicit handling of unresolved identifiers, internal cascading lookups, and source attribution. 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 and opens with a lengthy list of example queries before stating the core purpose. While every section adds substantive detail, the structure is not front-loaded. It could be reorganized to state purpose first, then examples, for quicker scanning.

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

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

With no output schema, the description thoroughly explains return values for both entity types, including source attribution, unresolved field behavior, and fallback mechanisms. It also covers edge cases like GLEIF/OpenFIGI unavailability, making it complete for a 2-parameter tool.

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

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

The schema covers both parameters well (100% coverage), but the description adds extra meaning by explaining accepted input formats for each type (ticker, CIK, name for company; brand/generic for drug) and providing concrete examples, enhancing 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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists specific examples, supported types, and output details, distinguishing it from sibling tools like compare_entities or entity_profile.

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

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

The description provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It gives clear context for when to use the tool, but does not explicitly mention alternatives or exclusion cases. Still, the guidance is actionable and well-placed.

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.