Gmail

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive; the description adds scoring range (0-100), per-model return structure, and cost implications for Anthropic API key, providing useful context beyond annotations.

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

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

Single dense paragraph with all key information front-loaded, 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?

No output schema, but description clearly details return values (per-model score, confidence, signals, raw_response) and combined view, fully covering what the agent needs to know.

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, baseline is 3; the description adds value by explaining default model, when _apiKey is needed, and how context disambiguates, going beyond the schema.

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

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

The description explicitly states it probes multiple LLMs for visibility scoring of a business/brand/product/topic, distinguishing it from sibling tools like compare_entities or scan_competitor_ai_presence.

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

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

Clear use cases are given (AI-marketing audits, pre-launch brand checks, competitive monitoring) and default model behavior is explained, though alternatives like compare_entities are not explicitly excluded.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: routing to one of 5,529 tools, filling arguments, returning structured answers with pipeworx:// citations, being a single fast call that works on every tier. 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 effectively front-loaded with 'PREFER OVER WEB SEARCH' and every sentence adds value. It uses structured guidance (examples, alternative steps) without unnecessary fluff, though a slightly tighter version could exist.

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 is fully sufficient for a router tool with no output schema. It explains what it does, when to use it, what it returns (structured answer + citations), and how to step up to alternatives. Combined with the rich annotations and schema, no critical context is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic value by framing the question as a factual real-world query and providing examples of what constitutes a good 'question' (e.g., 'current US unemployment rate'), though it could more directly discuss the aliases.

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: it routes factual questions to the right specialized tool and returns structured answers with citations. It distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, and it positions itself as the default entry point.

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

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

The description provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...') and exclusions ('Step up only when needed...'). It names specific alternative tools (ask_pipeworx_grounded, deep_research) and gives examples of query types, making usage context unmistakable.

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 hints, and the description adds behavioral context beyond them: candidate routing improvements are enabled live when under test, currently no candidate is active so behavior matches stable, and it 'falls back to nothing' as a full working router rather than a thin wrapper. This exposes the experimental edge and comparison workflow.

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 compact paragraph but front-loads the beta identity and uses each sentence to clarify state, usage, and experimental comparison. It is slightly verbose but every sentence adds value, so it remains 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?

Covers what it is, current state, usage instructions, fallback behavior, and how results are compared with the stable router. This makes it fully contextual for a beta router with no output schema, and the 'same response shape' reference handles return format indirectly.

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

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

Schema has 100% coverage with six alias parameters for 'question', all described. The description only says 'same arguments, same response shape' as ask_pipeworx, which adds no new syntactic or semantic details beyond the schema; the high coverage baseline 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 states it is a 'Beta version of ask_pipeworx' with an 'identical universal router' featuring the same 5,529 tools, arguments, and response shape. It clearly distinguishes from siblings like ask_pipeworx by highlighting the experimental routing improvements and its current identical behavior.

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

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

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that no candidate is active, so it currently matches ask_pipeworx exactly. It contrasts with the stable router by explaining results are compared to decide merges, providing clear when-to-use context.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: it returns verbatim evidence, explicit refusal reasons (not_in_source, no_tool_match, etc.), and the cost tradeoff. There is no contradiction with annotations; it enriches them.

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

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

Three dense sentences: the first states the core value, the second details output and refusal behavior, the third gives usage context and cost tradeoff. No fluff, front-loaded with purpose, and every sentence earns its place.

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

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

For a complex tool with no output schema, the description covers purpose, underlying routing mechanism, success/failure output shapes, refusal reason enum, use cases, cost implications, and alternative tools. It is remarkably complete for the tool's complexity.

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

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

Schema coverage is 100% with six parameters (five aliases plus question), each described as natural language input. The description adds no extra parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema fully documents the parameters.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' immediately specifying a distinct purpose. It clearly differentiates from the sibling ask_pipeworx by stating it 'EXTRACTS the answer using ONLY what the tool result contains' and lists the return/refusal structure. This is a specific verb+resource with 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?

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also provides exclusions and an alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is clear when/when-not guidance with a named alternative.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral details: fan-out, response shapes, safety mechanisms (low-confidence match, closed markets, wide spreads), resolution-rule risk, and more. No contradictions.

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

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

Description is very long and detailed, almost a specification. Front-loaded with purpose, but then extensive. While density of information is high, conciseness is sacrificed. Could be slightly more succinct.

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 input format, process, output shapes, edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. No output schema, but response shapes are thoroughly explained. 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 coverage is 100%, so baseline is 3. Description adds context on 'market' parameter (slug, URL, question text) and explains 'depth' and 'include_raw' purpose. Good augmentation beyond schema.

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

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

The description clearly states it researches Polymarket bets by pulling Pipeworx data, resolving markets, and returning evidence. It distinguishes from siblings by being specific to Polymarket and Pipeworx, with a unique fan-out mechanism.

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

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

Explicitly states when to use ('should I bet on X', 'what does the data say about Y') and provides examples of fan-out for various categories. Lacks explicit exclusion of when not to use, but context implies it's for research, not trading.

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, open-world, idempotent, non-destructive behavior. Description adds valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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?

Single paragraph is dense but well-organized: starts with query examples, then explains function, data sources, sorting, and return format. Could benefit from bullet points, but all content is relevant and no word is wasted.

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 explains return format (paired data + citation URIs). Covers entity types, data sources, sorting, count limits, and use case. Thorough for a comparison 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?

Input schema covers 100% of parameters with descriptions. The tool description enriches semantics by explaining what each type does in practice and giving examples for the 'values' parameter (tickers vs drug names). 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 explicitly states it performs side-by-side comparisons of 2-5 companies or drugs. Uses specific query examples ('compare X and Y', 'X vs Y') and distinguishes itself from sequential lookups, making its purpose unmistakable.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong usage guidance. Also explains what data each entity type retrieves, helping the agent decide when to use this tool.

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

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

Adds substantial context beyond the annotations: account requirements, paid plan, parallel routing to 5,529 tools, citation resolvability guarantees, gaps[] and contradictions[] fields, semantic excerpting of large records, and expected latency. These disclosures are consistent with the readOnlyHint, openWorldHint, and idempotentHint annotations, so there is 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 long but every sentence carries substantive information, from account requirements to latency. It is front-loaded with the account requirement and the core distinction from ask_pipeworx. However, the dense single block of text could be more scannable with bullet points or headings.

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 and complex behavior, the description is remarkably complete: it describes the findings packet (evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop field, citation resolvability, latency, and account tiers. It also covers limitations regarding current news and alternatives, making it self-sufficient.

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

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

The schema already describes both parameters thoroughly, but the description goes further by explaining the depth parameter's behavioral implications (quick=3 facets, standard=5 with gap recovery, thorough=8 with lead chasing) and clarifying that the question can be broad/multi-part. This adds meaningful context beyond the enum 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 function with a specific verb-resource pairing: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources'. It also explicitly contrasts with siblings by noting 'this is NOT open-web search' and naming ask_pipeworx as the alternative for single lookups.

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

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

Provides explicit when-to-use/when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and for breaking news 'prefer ask_pipeworx'. The description names concrete alternative tools and gives examples of suitable questions.

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

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

Adds significant behavioral context beyond annotations: returns top-N tools with full schemas ready to call. Annotations already indicate readOnly and idempotent; description complements them.

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

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

Front-loaded with purpose and list of domains. Slightly long but every sentence is informative. Could be tightened slightly.

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

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

Comprehensive for a discovery tool: describes what is returned, when to use, examples, aliases. No output schema needed; description fills in return format effectively.

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

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

Schema coverage is 100% and description adds value by explaining aliases and natural language usage. Provides examples and clarifies that multiple parameter names are accepted.

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 states it finds tools by describing data or task, lists many domains, and distinguishes from siblings as a meta-tool.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use context. Does not mention exclusions.

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

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

The description adds significant behavioral context beyond annotations: it performs parallel fan-out across multiple sources, returns specific data fields, notes soft-failure for patents, and provides pipeworx URIs. Annotations already indicate read-only and idempotent, and the description aligns perfectly with 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 dense but efficient: it front-loads example queries, explains the behavior, lists return fields, and notes limitations—all without redundant text. Every sentence serves a purpose.

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 data sources) and no output schema, the description comprehensively lists what is returned (cik, filings, fundamentals, patents, news, LEI) and includes important context like patent API sunset and URI format. It fully equips the agent to use the tool correctly.

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

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

Schema coverage is 100% with both parameters described. The description adds value by stating that 'value' accepts ticker or zero-padded CIK (not names), and 'type' is currently only 'company'. This goes beyond the schema's enum and description fields.

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

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

The description explicitly defines the tool's purpose as generating a full cross-source profile of a US public company in one parallel call, with examples like 'Tell me about X' and 'research Acme'. It clearly distinguishes from sibling tools like resolve_entity for name resolution and advises against chaining single-pack lookups.

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

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

The description provides explicit guidance on when to use this tool (holistic view of a company), when not to (names not supported; use resolve_entity first), and contrasts it with chaining other tools. It also states the input format (ticker or CIK) and limitations.

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 confirms destructive nature (matches destructiveHint) and adds context about clearing sensitive data, going beyond annotations. IdempotentHint is not contradicted.

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

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

Two concise sentences front-loaded with action. 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?

Simple tool with one parameter and no output schema. Description fully covers purpose, usage, and behavioral hints, making it complete for an agent.

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

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

Schema coverage is 100% with clear parameter description. Description does not add further semantics beyond the schema, meeting baseline but not exceeding.

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 action ('Delete a previously stored memory by key') with specific verb and resource. Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task done, or clearing sensitive data. Also mentions pairing with remember and recall.

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 safe, non-destructive behavior. The description adds valuable process details: fetches page, extracts title/description/key links, outputs standard markdown. It doesn't contradict annotations. Slightly more precision (e.g., rate limits, depth of extraction) would elevate to 5 but is not required.

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-load the purpose, process, and use cases with zero redundancy. Every sentence carries distinct value, making it easy to scan and act upon.

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 params, no output schema, straightforward output), the description fully covers what the tool does, how it works, and when to use it. No gaps remain for the intended use cases.

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

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

Schema coverage is 100%, but the description adds practical context beyond parameter descriptions: 'max 50' constraint, example URL format, and the notion of 'production-ready' output. This helps the agent understand parameter intent beyond the schema's dry 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 action ('generate'), resource ('llms.txt file for any URL'), and purpose ('so AI crawlers... can index the site cleanly'). It distinguishes from sibling tools by focusing on file generation rather than analysis or scanning.

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 three concrete use cases (client site indexing, personal project, competitor auditing) which effectively guide when to use. However, it does not explicitly state when NOT to use or provide alternatives, missing a chance to contrast with sibling tools like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds value by specifying what is returned (headers, body, labels, etc.), which is not covered by annotations.

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

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

Single sentence that front-loads the action and lists return contents. No filler words; every part earns its place.

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

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

With output schema present, description does not need to detail return values. All necessary context (what it does, what it returns) is covered. No gaps.

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

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

Schema description coverage is 100% and includes descriptions for both parameters (message_id and format with enum). The description does not add new semantic information beyond what the schema provides, so baseline 3.

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

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

The description clearly states 'Fetch full email details by message ID' and enumerates returned components (headers, subject, body, etc.), distinguishing it from siblings like gmail_list_messages which lists messages.

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

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

No guidance on when to use this tool versus alternatives (e.g., gmail_search, gmail_list_messages). Agent must infer that it requires a known message ID.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds context that system folders are included and the tool returns labels for identification. 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?

Single sentence with two concise clauses that front-load the purpose and immediately detail output. No unnecessary words.

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

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

Given no parameters and existence of an output schema, the description fully covers all aspects: purpose, content, output details, and usage context. Complete for a simple retrieval tool.

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

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

No parameters exist, so the description correctly provides no additional param info. Baseline for zero parameters is 4, and the description meets that without needing to elaborate.

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 retrieves all labels (system and custom) and specifies the output (names and IDs). It differentiates adequately from sibling tools like gmail_list_messages which list emails.

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

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

The description indicates the tool is for 'filtering or organizing', providing a clear use case. It doesn't explicitly mention when not to use, but given the no-parameter simplicity and distinct purpose, 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?

Annotations already declare readOnlyHint and destructiveHint false, so the safety profile is clear. The description adds that the tool returns message IDs, thread IDs, and preview text, which is useful behavioral context beyond annotations. However, no additional constraints like pagination limits or rate limits are mentioned.

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

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

The description is two sentences, perfectly front-loaded: first sentence states the core functionality and output, second sentence provides usage guidance for an alternative. 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?

For a simple list tool with 3 optional parameters and existing output schema, the description covers what the tool does, what it returns, and when to use an alternative. Combined with rich annotations and schema, this is fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description mentions filtering by label or read status, which overlaps with the schema's query parameter description. While the description adds a user-friendly summary, it doesn't significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists messages in the inbox with optional filtering by label or read status. It contrasts with gmail_search for complex queries, distinguishing the tool's specific purpose. The verb 'list' and resource 'messages' are specific and unambiguous.

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

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

The description explicitly directs to use gmail_search for complex queries like date ranges or attachments, providing a clear when-not-to-use scenario and an alternative tool. This gives excellent guidance on tool 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 already declare readOnlyHint=true, destuctiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds that the tool returns message IDs, which is useful. No contradictions. Missing details like rate limits or authentication needs, but annotations compensate.

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

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

Two sentences with no unnecessary words. Purpose and syntax examples are front-loaded. Efficient and well-structured.

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

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

Given only 2 parameters with full schema coverage, annotations, and an output schema (not shown but context confirms), the description is complete. It explains the query syntax and return type clearly.

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 documented. The description provides Gmail query syntax examples, adding marginal value beyond schema. 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 searches emails using Gmail query syntax and returns message IDs. It uses a specific verb ('search') and resource ('emails'), and distinguishes from sibling tools like gmail_get_message, gmail_list_messages, and gmail_list_labels by focusing on a query-based search.

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

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

The description provides examples of valid query syntax, implying usage context (e.g., for filtering emails). However, it does not explicitly state when to use this tool vs siblings like gmail_list_messages (for simpler listing without query) or give any exclusion criteria.

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

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

Annotations already convey readOnlyHint=false, destructiveHint=false, idempotentHint=true, so the description adds limited behavioral insight. However, it misleadingly mentions 'reply-to address, and file attachments' as optional parameters, which are absent from the input schema. This inaccuracy reduces transparency.

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

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

The description is a single sentence, but it includes extraneous details about parameters not in the schema, making it less efficient. It could be more concise by sticking to schema-supported features.

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

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

The tool has 5 parameters (3 required) and an output schema (presumably present). The description fails to mention the output behavior and introduces non-existent parameters. This omission and inaccuracy make it incomplete for reliably invoking the tool.

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

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

Input schema has 100% coverage with descriptions for all 5 parameters. The description adds no meaningful detail beyond the schema for the existing parameters, and it introduces fictitious parameters ('reply-to', 'file attachments'), creating confusion. Baseline 3 is lowered due to misleading additions.

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 'send' and resource 'email', and lists key fields (recipient, subject, body). It effectively distinguishes this tool from siblings, which are primarily read operations for Gmail (e.g., gmail_get_message, gmail_search).

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

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

The description implies the tool is for sending emails, and the sibling context (all other Gmail tools are read-oriented) provides clear usage context. However, it does not explicitly state when not to use it or provide alternative tools for non-sending needs.

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, destructiveHint. Description adds context about what data is returned and suggests cancellation use, adding moderate value beyond annotations.

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

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

Two concise sentences, front-loaded with purpose, then usage guidance. No wasted words.

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

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

No output schema, but description enumerates return fields. Parameter is fully documented. For a simple list tool, it is complete enough to inform the agent.

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

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

Schema coverage is 100% with a well-described parameter (include_inactive). Description does not add extra semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. Differentiates from siblings like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit when not to use, but context is clear.

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

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

Despite annotations being all-false (offering no safety hints), the description discloses the claim_token workflow (returned when no account, can be passed back to read resolution), rate limiting (5 per day), and that it doesn't consume tool-call quota. These behavioral traits go far beyond what annotations 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 longer than average but every sentence carries distinct, actionable information. It front-loads the core purpose, then logically flows through use cases, exclusions, behavioral notes, and constraints. No filler or repetition; it earns its length.

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

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

No output schema exists, yet the description explains the return value (claim_token) and the exact follow-up invocation. It also covers rate limits, quota impact, and roadmap influence, giving the agent a complete picture of when and why to invoke the tool, and what to expect.

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

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

While the input schema documents all four parameters with 100% coverage, the description adds meaningful semantics: maps type values to real scenarios, instructs agents to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts, and explains the claim_token follow-up pattern. This elevates the parameter understanding 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 opens with a clear, specific directive ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates concrete feedback types (bug, feature/data_gap, praise). It also differentiates from sibling tools by explicitly scoping to tools served by this Pipeworx connection, not 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 for each feedback category and an exclusion clause: if the problematic tool came from a different MCP server, report it there instead. This directly answers 'when to use vs alternatives' and even tells the agent how to disambiguate Pipeworx 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 annotations (readOnlyHint, idempotentHint), the description adds important behavioral context: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). 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 concise with front-loaded purpose and structured use cases. Every sentence adds value without repetition. No unnecessary words.

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

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

Given single optional parameter, no output schema, and rich annotations, the description is fully complete. It explains return values (top tools, packs, volume), data derivation, and caching. No gaps.

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

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

Schema coverage is 100% with description for 'window', but the tool description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides actionable meaning beyond the enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' with specific verb 'Returns' and resource. It distinguishes from sibling tools like 'discover_tools' by focusing on trending/call volume data.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking use-case alignment. It also explains window choices and caching, giving clear context for when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: semantic anchors (Jaccard similarity), partition filters (placeholder rejection), fill check integration, and return format. 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 verbose and packed with details but remains well-organized. It front-loads the core purpose and then systematically explains modes, filters, and checks. However, it could be more concise for an AI agent to parse quickly.

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, partition checks, fill risk integration), the description thoroughly covers all aspects. It explains the response structure, references the sibling tool for custom sizing, and compensates for lack of output schema with detailed return field descriptions.

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. The description goes beyond by providing concrete examples of event slugs and topic queries, and explaining the effects of each parameter (e.g., event triggers partition_check).

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 three modes (no args, event, topic) with specific behaviors, making the purpose very clear and distinct from siblings.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for single-event (recommended), topic for cross-event. It lacks explicit when-not-to-use guidance, but the context is strong enough to guide an AI 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral detail beyond annotations: caching at KV level with 1h TTL, response structure with segments and diagnostics, risk warnings like 24h-move indication, and detailed explanation of edge computation and model families.

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

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

The description is lengthy but well-structured, with clear sections (model families, opportunity fields, tradeable-edge knobs, response top-level). It front-loads the core purpose. Some technical details could be condensed, but the structure aids readability.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the three response segments, nested diagnostics, every field in opportunities, edge calculation details, caching behavior, and parameter usage. It leaves no major gaps for an agent to interpret the tool's 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% with descriptions for all 9 parameters. The description adds value by grouping parameters into 'tradeable-edge knobs' and explaining their behavioral impact and typical use cases (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). This contextual guidance enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings by being discovery-oriented ('what should I bet on today') versus other tools like polymarket_edge_tracker or polymarket_fill_risk.

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 targets the 'what should I bet on today' use case and mentions that agents can discover opportunities without paging hundreds of markets. While it doesn't explicitly state when not to use it, it provides enough context to infer its primary scenario, and the sibling list includes alternatives for more specific tasks.

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

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

The description goes far beyond the annotations (which already declare readOnly, idempotent) by detailing the response structure (tracked[], expired[], snapshot_dates[]), computation of trends and decay, explanation of data gaps, and limitations. 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 well-structured with a clear front-loaded purpose, followed by args and response details. It is somewhat verbose due to the lack of output schema, but every sentence adds value. Could be slightly more concise, 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?

The description is comprehensive for a telemetry tool with no output schema. It explains the data source, computation, response fields, and limitations. The agent gets a complete picture of what to expect.

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

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

Schema coverage is 100% with both parameters already described. The description restates the parameters slightly (days lookback, window family) but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking and decay analysis.

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

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

The description implicitly guides usage by explaining the context (fresh vs old edges) and providing limitations (TTL, start date). It does not explicitly state when to use this tool over alternatives, but the clear purpose and limitations are 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it returns a verdict (clean|degraded|cannot_fill), details on thin legs, forced directional risk, and how slippage is calculated. It also warns about the 'dominant loss mode in real arb-bot P&L'. 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 well-structured with sections (SINGLE-MARKET, BASKET) and uses bold for emphasis. However, it is quite long (around 200 words). Every sentence adds value, but a slightly more condensed version might be more quickly scannable. No wasted words, but length is borderline.

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 thoroughly explains return values: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. It also addresses edge cases like partial fills and thin books.

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 4 parameters described). The description goes far beyond the schema by explaining the difference between single-market and basket modes for each parameter (e.g., side interpretation differs, size_usd interpretation differs). It also clarifies defaults and constraints (e.g., size_usd clamp). This adds substantial meaning.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes itself from sibling tools (polymarket_arbitrage, polymarket_edges) by stating it should be used before acting on their signals, and it explains two distinct modes (single-market and basket). This provides a specific verb+resource+scope.

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

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

Explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb to directional position). No when-not-to-use stated, but the positive directive is sufficient.

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

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

Despite annotations already providing safety cues (readOnlyHint, idempotentHint), the description adds extensive behavioral details: two modes, response structure (leg-by-leg prices, matched spreads), safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons. It even notes that most pre-mapped topics return a warning, setting expectations accurately.

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 yet efficient. It uses bullet-like phrases (bolded terms, all-caps mode labels) and is structured logically: purpose, modes, response, safety. Every sentence conveys crucial information without redundancy.

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

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

Given the tool's complexity (cross-venue, multiple modes, compatibility checks), the description covers all necessary aspects: input modes, output expectations, error conditions, and caveats. The absence of an output schema is compensated by detailed explanation of response fields.

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

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

With 100% schema description coverage, the description still adds value by explaining the interaction between parameters: topic vs explicit tickers, overriding behavior, and the list of valid topic values. It also provides examples 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 tool computes 'cross-venue spread between Kalshi and Polymarket for the same resolving question'. It distinguishes itself from siblings like `polymarket_arbitrage` by focusing on cross-venue comparison. The verb 'compute' is implied and the resource is specific.

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 explains two modes: topic shortcuts for common macros and explicit ticker/slug for custom pairings. It warns when spreads are not meaningful (compatibility_warning cases) and when temporal mismatch occurs. This provides clear guidance on when to use and when not to.

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, destructiveHint. Description adds scoping info (identifier-based) and clarifies behavior when key is omitted. 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?

Relatively concise, front-loaded with main action. Every sentence adds value, though could be slightly tighter. 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?

For a simple read-only tool with one optional parameter, the description is complete. It covers retrieval, listing, scope, and pairing with related tools. No output schema needed.

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

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

Schema covers 100% with description for key. Description adds meaning: retrieving saved values, listing all keys, and pairing with remember/forget. Explains when to omit key.

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

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

Clearly states the tool retrieves a value saved via remember or lists all keys when omitted. The verb 'retrieve' and resource 'memory' are specific, and it distinguishes from siblings like 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?

Tells when to use: to look up context stored earlier without re-deriving. It explains omitting key to list all keys. No explicit when-not-to-use but provides good context for usage pattern.

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 claims mark_read:true modifies state ('flag returned events read'), but readOnlyHint annotation indicates the tool is read-only and never modifies state. This is a direct contradiction, severely undermining 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?

Five compact sentences, front-loaded with main action, no redundant information. Each sentence serves a clear purpose.

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

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

Describes return fields (source, citation_uri, payload) and filter options. Lacks pagination notes or error handling, but no output schema exists; content is otherwise sufficient for a read tool.

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

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

Schema covers all 5 parameters (100% coverage). Description adds value beyond schema by explaining mark_read effect and giving an example for type (sec_8k). Limit and unread_only are not elaborated but schema descriptions suffice.

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

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

Description uses specific verb 'Pull' and resource 'subscription feed', clearly stating it returns recent alerts with details. Distinguished from sibling tools like list_subscriptions.

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

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

Provides guidance on filtering by type and ISO timestamp, mentions polling suitability, and notes alternative HTTP endpoint. Lacks explicit when-not-to-use but contextually adequate.

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

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

Annotations already mark readOnlyHint, idempotentHint, destructiveHint. The description adds parallel fan-out behavior, fallback from GDELT to GNews, soft-fail for USPTO, and citation URI output.

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

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

Single paragraph is info-dense but front-loaded with usage examples. Could be broken into bullet items for readability, 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 complexity (multiple sources, fallback, soft-fail), description covers behavior, parameters, return format, and differentiates from sibling entity_profile. No output schema but return structure is explained.

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

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

Schema covers all parameters with descriptions (100% coverage). Description adds value by explaining `since` shorthand ('30d', '1m'), recommending values, and how `value` accepts ticker or CIK.

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

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

Description clearly defines the tool as a change feed for a company, enumerating sources (SEC EDGAR, GDELT→GNews, USPTO) and return structure. It distinguishes from entity_profile explicitly.

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

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

Provides example queries ('What's new with X', 'latest on Y') and explicit alternatives: 'Use entity_profile instead when you want the static profile'.

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 provide basic hints (idempotent, not destructive, not read-only). The description adds valuable behavioral details: key-value pair scoped by identifier, persistence differences (authenticated vs anonymous, 24-hour retention), and pairing with companion tools. 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 with no filler. First sentence states purpose, second covers usage, third adds technical context, fourth mentions companion tools. Efficient and well-structured.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description is complete: it covers purpose, when to use, behavioral traits, parameter semantics, and interaction with related tools. No gaps.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds meaning beyond the schema by explaining scoping and providing example key formats ('subject_property', 'target_ticker'), which aids selection and invocation.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and provides specific examples like resolved ticker, target address, user preference. It distinguishes from sibling tools recall and forget by mentioning them explicitly.

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

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

The description explains when to use ('discover something worth carrying forward') and pairs with recall/forget. Although it doesn't give explicit when-not scenarios, the context is clear and sufficient.

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

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

Beyond the readOnly/idempotent annotations, the description discloses key behavioral details: identifiers are labeled with their source, unresolved identifiers are explicitly listed under `unresolved`, and LEI/FIGI enrichment degrades gracefully when upstream sources are unavailable. It also reveals internal cascading lookups, which is non-obvious and valuable. These details go far 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 long but dense, with no fluff. The trigger phrases first may delay the core statement, but they serve a clear purpose in helping the agent recognize user intent. The structure flows from examples to purpose to type-specific details, and each sentence adds useful information. Could be slightly more front-loaded, but overall appropriately sized for the tool's complexity.

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

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

Given no output schema, the description thoroughly covers what the agent needs to know: return contents for both entity types, source labeling, unresolved identifier handling, graceful degradation, and the multi-lookup nature. It even hints at the tool's role in an ecosystem ('other tools require as input'). This is highly complete for a complex resolution 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?

While the schema already describes both parameters, the description substantially deepens their meaning. It explains exactly what each `type` returns, including source provenance and specific identifier details (e.g., LEI with parent/ultimate-parent for companies, RxCUI with ingredient/brand for drugs). This transforms bare parameter names into a rich semantic model of expected outputs.

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 resolves user-spoken names to canonical/official identifiers needed by other tools. It lists specific resources (CIK, ticker, LEI, FIGI, RxCUI) and supported entity types, distinguishing it from sibling tools like entity_profile. The trigger phrases and 'Use FIRST whenever you have a name but need an ID' make the purpose unmistakable.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID' and illustrates typical user queries. It also notes that the tool replaces 2-3 manual lookups, implying when to prefer it over multiple calls. However, it does not explicitly state when not to use it or name alternative sibling tools, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds behavioral value by revealing the internal mechanism (probing each entity via 'ai_visibility_check') and the return structure (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?

Three sentences, front-loaded with primary action, then details, then use case example. Every sentence is informative and concise. No filler.

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

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

For a multi-entity comparison tool without output schema, the description adequately explains the return format (ranked list with score, confidence, signal density per entity). Covers key aspects: number of entities, indexing, shared context, result ranking. No missing critical info.

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 important nuance: 'First entry treated as the 'subject' for narrative; rest are competitors.' This goes beyond the schema and helps agents understand the ordering requirement.

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 specific verbs ('Compare', 'Probes', 'ranks') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes from sibling tool 'ai_visibility_check' which is single-entity, and mentions returning a ranked list, making the purpose unambiguous.

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

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

States the tool is 'Useful for competitive AI-marketing audits' and gives an example query. Though it doesn't explicitly list exclusions or contrast with 'compare_entities', the context of side-by-side multi-entity comparison is clear. Slight room for improvement in stating when not to use.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), description reveals composite nature, partial failure behavior (bundlephobia timeout, sources_failed list), and performance note ('first measurement can take 5-30s'). All traits are accurately disclosed.

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

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

Single, dense paragraph with clear front-loading of purpose. Information is well-organized but could be slightly more structured (e.g., bullet points for return fields). No redundancy.

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

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

Despite no output schema, description fully enumerates return fields (summary block, advisory details, links, alternative versions) and covers error handling (partial failures, timeout). All relevant context is present.

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

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

Schema already covers both parameters with 100% description coverage. Description adds no additional syntactic or semantic detail about parameters beyond context that the tool operates on npm packages. Baseline 3 is appropriate.

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

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

Description clearly states it's a composite check for deciding on npm packages, listing specific checks (license, advisories, bundle size, etc.) and includes usage examples ('is X safe / popular / small'). It distinguishes from other ecosystem tools by specifying 'NPM ecosystem only' and directing to deps.dev for other systems.

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 on when to use ('Use whenever an agent asks...') and what to expect. Also clarifies exclusions ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), helping agents select 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing safety. The description adds important behavioral details: uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows', a 'cap is 200K chars (longer inputs are truncated and flagged)'. No contradiction with annotations.

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

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

The description is a single paragraph but front-loads the core purpose and usage, then adds technical details. Every sentence contributes value (purpose, usage, pairing advice, algorithm, limits). No wasted words, but could be slightly more structured (e.g., separate sentences for constraints).

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 adequately describes the return structure: 'top-N passages with character offsets and similarity scores'. It covers input constraints (200K char cap, truncation flag), algorithm, and usage pairing. For a semantic search tool, this is comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates schema info (max chars for 'text', default/range for 'limit'). It provides helpful example values for 'query', adding marginal value. No parameters require enum clarification, and the description does not significantly expand beyond schema.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record'. It specifies the verb 'search', the resource 'text inside a record', and the return type (top-N passages with offsets and scores). It also distinguishes itself from sibling tools like 'ask_pipeworx_grounded' by explaining their complementary roles.

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

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

Explicitly advises when to use: 'when the record is too big to cram into the prompt'. Also indicates a complementary tool ('Pairs with ask_pipeworx_grounded') and explains the workflow. While it doesn't explicitly list when not to use, the positive guidance is clear and actionable.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds significant behavioral details: authentication requirement, persistence limits, delivery channel behaviors (feed always on, email/SMS/webhook constraints including webhook auto-disable and HMAC signing). No contradictions with annotations.

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

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

The description is well-structured with information front-loaded (purpose and return value) followed by details. It is slightly lengthy but every sentence adds value, covering types, parameters, and delivery options.

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 types, delivery channels, restrictions, no output schema), the description covers prerequisites, type-specific parameters, delivery options, and behavioral constraints. It lacks detailed description of the return value composition but specifies it returns the subscription ID.

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

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

Schema coverage is 100%, so baseline 3. The description adds value beyond schema by providing concrete examples (e.g., sec_8k items codes) and elaborating on delivery channel details (verification, caps, webhook signing).

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It enumerates supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies requirements (Pipeworx OAuth account), supported types with examples, and delivery channel restrictions (SMS verification, daily cap, webhook auto-disable). However, it does not explicitly state when NOT to use this tool compared to alternatives like recent_alerts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the return format (category buckets, tool+argument shape) which is valuable 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?

Front-loaded with common queries, but the description is somewhat lengthy. All sentences are useful, but could be slightly more concise without losing information.

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

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

The description covers purpose, usage, output format, and parameter details. For an onboarding tool with no output schema, it provides sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100%. The description explains the optional topic parameter with examples and valid values, adding context beyond the schema 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 category-bucketed example questions with exact tool calls. It distinguishes itself from siblings as the onboarding entry point for new agents.

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

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

Explicitly says to use this FIRST when you don't know what Pipeworx can do, and provides guidance on when to pass a topic vs. omit. Lists specific example queries that trigger this tool.

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

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

Annotations give idempotentHint=true and destructiveHint=false; description adds that row is deactivated not deleted, preserving history. No contradictions, detailed side effect disclosure.

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

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

Two sentences covering purpose, constraint, and side effect with no extraneous 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?

Complete for a simple one-param tool with no output schema. Covers purpose, ownership, and behavioral impact (deactivation).

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

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

Schema describes 'id' as subscription uuid from subscribe; description reinforces its source and requirement. Since schema coverage is 100%, description adds useful 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 'Cancel a subscription by id' with specific verb and resource. Differentiates from siblings like 'subscribe' and 'list_subscriptions' by implying mutation.

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 ownership constraint ('you can only cancel your own subscriptions'), guiding when the tool is applicable. Does not explicitly mention alternatives or when not to use, but constraint is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by explaining that 'could_not_verify' means the check did not happen and carries a verification_error, and must not be treated as evidence. It also discloses the composite nature ('Replaces 4–6 sequential calls') and the routing to different sources, 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 fairly long but well-structured and front-loaded with trigger phrases. It flows logically: purpose, pipeline routing, return value semantics, and caller warnings. Every sentence earns its place—there is no fluff or repetition. The complexity of the tool justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return values. It enumerates the verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify) and explains the difference between could_not_verify and unsupported. Combined with annotations and parameter schema, the description is complete for an 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% for both parameters, so the baseline is 3. However, the description adds significant meaning beyond the schema for tolerance_pct: it states it overrides the tolerance implied by claim wording, recommends 1–2 for hallucination detection, and gives the default behavior (capped at 5). This is genuinely helpful guidance not present 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 opens with natural-language trigger phrases and states 'natural-language claim verification against authoritative sources.' It uses clear verbs like 'verify' and 'fact check' and distinguishes itself by focusing on claim verification, with explicit mention of two pipeline paths (SEC EDGAR fast path and grounded pipeline). This makes its purpose unmistakable and differentiates it 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition. It also gives detailed routing guidance for company-financial vs. other claims and explains when to set tolerance_pct to 1–2 for hallucination detection. This is explicit and actionable, though it doesn't name alternative tools.

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