Google_drive

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive actions. The description adds valuable behavioral details: it executes across models, returns per-model scores with confidence and raw responses, defaults to a free model, and passes `_apiKey` directly to Anthropic without processing. No contradictions with annotations.

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

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

Description is a single paragraph but well-structured: it opens with the core action and return value, then covers model options and use cases. Every sentence adds necessary information without redundancy. Front-loaded with the primary function.

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 specifies the return shape (per-model score, confidence, signals, raw_response + combined view). It covers all parameters and use cases. However, it could mention potential timeout issues or API key validation, which would improve completeness. Still, very good for a tool with simple inputs and no output schema.

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

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

Schema has 100% description coverage for all 4 parameters. The description enhances understanding by providing examples for `entity` (e.g., 'Pipeworx'), clarifying default behavior for `models`, explaining the payment implication for `_apiKey`, and specifying that `context` disambiguates common names. This adds value beyond the schema.

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

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

Description clearly states the tool's purpose: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility (0-100). It distinguishes from sibling tools by focusing on visibility score rather than question answering or research. The verb 'probe' and resource 'LLMs' make the action 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?

Description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use the optional `_apiKey` parameter. While it doesn't explicitly contrast with sibling tools like `compare_entities` or `scan_competitor_ai_presence`, the stated use cases provide clear guidance on when this tool is appropriate.

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, so the safety profile is covered. The description adds valuable behavioral context: it returns structured answers with stable citation URIs, works on every tier, and makes one fast call. It does not elaborate on internal routing or pagination, but these are minor given 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 longer than average but every sentence earns its place: it covers when to use, examples, alternative tools, and caveats. It is front-loaded with the critical preference instruction. Slight redundancy (e.g., 'START HERE' restates the preference) prevents a 5.

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, general-purpose routing tool with no output schema, the description fully explains what the agent can expect (structured answer with pipeworx:// citation URIs), when it should be used, and when to choose alternatives. It addresses both coverage and limitation aspects thoroughly.

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

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

Schema description coverage is 100%, with the 'question' property adequately described as accepting natural language and aliases. The description adds example questions and emphasizes natural-language input, but this does not go materially beyond the schema's own description, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('routes', 'fills', 'returns') and identifies the resource ('questions to the right one of 5,529 tools across 1455 verified sources'), clearly distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs to prefer over web search, provides trigger phrases ('what is', 'look up', 'find'), concrete examples, and names alternatives with precise conditions for stepping up (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions). Also states it is the default entry point.

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 meaningful context beyond these: the experimental nature, current inactive candidate status, comparison against the stable router, and the fact that it is a fully working router with 'no fallback'.

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

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

The description is four sentences long and well-structured, starting with the core identity and then adding context. Some details, like the retirement date parenthetical, are slightly verbose but still relevant, so no sentence is purely 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?

For a beta router with no output schema, the description gives sufficient context: it explains the tool's function, current behavior relative to the stable version, and the response shape. It does not detail the response contents, but referencing ask_pipeworx's response shape is an acceptable shorthand.

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

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

The input schema covers 100% of parameters with clear descriptions for question and all aliases. The description only generically mentions 'same arguments' and does not add parameter-specific semantics, so the 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 clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx by highlighting 'candidate routing improvements' and its experimental status.

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

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

The description explicitly states when to use the tool ('when you want the newest routing') and names ask_pipeworx as the stable alternative. However, it does not provide an explicit 'when not to use' exclusion, so it stops short of a 5.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial behavioral context: success output shape (answer, evidence, confidence, source, fetched_at), refusal reasons (not_in_source, no_tool_match, etc.), and the guarantee that it extracts only from tool results. It also discloses the cost overhead. This goes far beyond annotations without contradicting them.

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

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

The description is dense but every sentence carries unique, needed information: purpose, routing mechanism, return format, refusal reasons, usage guidance, and cost trade-off. No filler or redundancy; well-structured for parsing.

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?

Without an output schema, the description fully documents both success and refusal return shapes. It also covers when to use the tool, how it routes, what it returns, and how it differs from siblings. This makes it complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% and the schema already documents the question parameter and its aliases clearly. The description does not add significant new parameter semantics beyond referencing 'fills arguments' as part of routing, but that's not about the parameter itself. 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 uses a specific verb ('extracts the answer') and resource ('Pipeworx grounded'), and clearly distinguishes itself from sibling ask_pipeworx by emphasizing hallucination-resistance and evidence-based answers. It describes the exact mechanism of routing through other tools and extracting only from tool results, making the purpose unmistakable.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). It also mentions the extra LLM call cost, providing a clear trade-off against the sibling tool.

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

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

The description discloses extensive behavioral details beyond what annotations provide: resolver contract (match confidence, alternatives, suggestions), parent event extractor, news fallback fields, safety for low-confidence matches, closed market handling, wide spread indication, and resolution-rule risk parsing. Annotations already indicate readOnly, idempotent, non-destructive, and the description aligns with these while adding critical operational details.

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

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

The description is very long (multiple paragraphs) and includes extensive details, examples, and edge cases. While well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), the length exceeds what is strictly necessary for an AI agent to understand the tool. Some information could be condensed without losing clarity.

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

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

Given no output schema, the description fully compensates by detailing response shapes (market fields, analysis fields, evidence keyed by source), resolver contract, parent event extractor, news fields, safety behaviors, and edge cases. It covers all relevant aspects an agent needs to correctly interpret and use the tool's output.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). The description adds value by clarifying the 'market' parameter can be a slug, URL, or question text, providing examples, and explaining the 'depth' and 'include_raw' parameters with concrete behavior (e.g., response size implications). This adds meaning beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-model comparison). Although it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, the use cases ('should I bet on X', 'what does the data say about Y') imply its research-oriented role, distinguishing it from edge/arbitrage tools.

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

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

The description includes explicit use cases ('Use for should I bet on X...') and provides detailed classifiers, fan-out examples, and behavior for various scenarios (closed markets, low-confidence matches, wide spreads). It does not explicitly state when not to use or mention alternatives, but the provided context is sufficient for an agent to determine appropriate usage.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds: pulls latest 10-K from SEC EDGAR/XBRL with off-calendar FY handling for companies; FAERS adverse events, FDA approvals, trials for drugs. Results sorted by primary metric, returns URIs.

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

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

Description is dense but efficient. Front-loads key trigger phrases and purpose. 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?

With only 2 params, no output schema, and strong annotations, the description fully covers behavioral details, data sources, and output format (sorted, URIs). Adequate for correct invocation.

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

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

Schema coverage 100% handles both params. Description adds beyond schema: explains what `type='company'` vs `type='drug'` yields, and gives examples for `values` (tickers/CIKs vs drug names).

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

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

Description clearly states tool does side-by-side comparison of 2-5 companies or drugs. Uses verbs like 'compare', 'rank', 'head to head'. Distinguishes from sibling tool `entity_profile` which is single entity.

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.' Provides typical user phrases and states it replaces 8-15 sequential lookups.

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

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

Even though annotations already indicate readOnlyIdempotent behavior, the description goes far beyond by disclosing account prerequisites, parallel tool routing, gaps[] that are never invented, contradiction reporting, semantic excerpting, latency expectations, and the stable pipeworx:// citation format. This adds substantial context not available in annotations.

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

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

The description is long but every sentence serves a purpose, covering account/access, primary use case, alternatives, depth semantics, output features, citation guarantees, and performance. It is logically organized, front-loaded with the most important constraint (account required), and contains 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?

Given the tool's complexity and absence of an output schema, the description fully compensates: it explains output structure (findings packet, gaps, contradictions, hop field), specific error-prone scenarios (current-news returns empty gaps), and operational details (timeouts, paid tier). This is a model of complete contextual documentation.

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

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

Schema coverage is 100%, but the description enriches both parameters: 'depth' is tied to hop behavior, gap recovery, contradictions scan, and paid tier; 'question' is clarified to accept broad/multi-part queries since decomposition is the point. This adds meaning beyond the schema enums and prompts.

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

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

The description clearly states the tool performs grounded multi-source research over 1455 structured data sources in one call, explicitly calling out that it is NOT open-web search. It distinguishes itself from siblings by specifying that for a single lookup or breaking current-news, ask_pipeworx is preferred.

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: best for broad/multi-part questions over structured data, while explicitly directing single lookups and breaking current-news topics to ask_pipeworx. Also notes account requirements and a fallback (ask_pipeworx) when not signed in.

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

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

Annotations provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral detail beyond annotations: it returns top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) and states that each result is ready to call directly with no second schema lookup. 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 concise yet comprehensive, around 5-6 sentences. It is front-loaded with purpose and followed by usage context, output format, and usage timing. Every sentence adds value with no redundancy or fluff.

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

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

Given the tool's simplicity (one required parameter, no nested objects, no output schema), the description covers all necessary aspects: what it does, when to use it, what the output contains (top-N tools with schemas), and parameter details. No gaps identified.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal value beyond schema: it reiterates that query accepts natural language and aliases, and provides examples. The limit parameter details are already in schema. No additional semantic enrichment needed.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It includes specific examples of use cases (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling tools by explaining it returns top-N relevant tools with full schemas, ready to call. It explicitly says to call this first to see the option set.

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

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

The description provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lists example queries and domains, indicating when to use. It lacks explicit 'when not to use' statements, but the context is clear enough.

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

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

Annotations already indicate non-destructive, mutable, idempotent behavior. Description adds return value info but does not disclose file overwrite behavior or permissions needs, adding minimal new context.

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

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

Two concise sentences: one for action, one for output. No redundant information.

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

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

Adequately describes creation and return of file ID. Could mention default root folder behavior or file size limits, but output schema likely covers return structure.

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 detailed descriptions for each parameter. The description provides examples but no additional semantic meaning beyond the schema.

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

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

Description clearly states 'Create a new file in Drive' with specific parameters (name, content, type), distinguishing from sibling tools that list, get, or search files.

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 like drive_get_file or drive_list_files. No mention of prerequisites or context-dependent usage.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context about export capabilities and raw content retrieval, which is consistent. However, it does not disclose potential limits (e.g., file size, rate limits) or behavior for unsupported MIME types. With annotations covering safety, this is adequate but not exceptional.

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

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

Two sentences, no redundant words. The first sentence captures the primary action; the second clarifies the two modes (export vs raw). Information density is high without being verbose.

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

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

Given the presence of an output schema and 100% schema coverage, the description adequately covers the core functionality. It explains the two use cases (export and raw retrieval) and mentions common export targets. It could mention error handling or prerequisites (e.g., proper permissions), but the annotation hints and schema reduce that need. Overall, sufficient for an informed 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 descriptions for both parameters. The description adds value by explaining export_mime_type's role in converting Google Workspace files and listing common formats (PDF, Word, Excel). This goes beyond the schema's generic MIME type description, helping the agent understand when and how to use export_mime_type.

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 downloads file content from Drive, distinguishes between exporting Google Workspace files (to PDF, Word, Excel, etc.) and retrieving raw content from other files. The verb 'Download' and resource 'Drive' are specific, and the distinction from sibling tools like drive_get_file (which likely returns metadata) is implicit.

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 does not explicitly state when to use this tool versus alternatives. It mentions export for Google Docs/Sheets/Slides but provides no guidance on when not to use it (e.g., for metadata-only needs, use drive_get_file). No direct comparison to sibling tools like drive_get_file or drive_list_files.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds no additional behavioral context beyond confirming it is a read operation. The description is consistent with annotations and does not contradict 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?

A single sentence that is front-loaded with the main purpose ('Get metadata for a specific Drive file by ID') and then lists the returned fields. No unnecessary words, highly efficient.

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

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

For a simple metadata retrieval tool with an output schema (indicated in context), the description is complete. It lists the key fields returned and does not need to explain return values beyond what the output schema provides.

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% (both file_id and fields have clear descriptions). The description adds no extra meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

Description explicitly states 'Get metadata for a specific Drive file by ID' with a specific verb and resource, and lists the returned fields (name, type, size, etc.). This clearly distinguishes it from sibling tools like drive_create_file, drive_get_content, drive_list_files, and drive_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 clear usage context: use this tool when you need metadata for a specific file by ID. While it does not explicitly mention when not to use it or mention alternatives, the purpose is straightforward and unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds detail about return fields but doesn't disclose pagination or rate limits beyond schema.

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

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

Two sentences, front-loaded with purpose, no redundancy. Every word earns its place.

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

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

Given output schema exists, description adequately covers listing with filters and return fields. Lacks mention of pagination (page_token) but schema handles it.

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

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

Schema covers all parameters (100% coverage). Description adds value with a concrete example query ('name contains "report"'), aiding interpretation.

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 'List files in your Google Drive', a specific verb+resource. Differentiates from siblings like drive_search by mentioning optional filters and returning metadata.

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?

Gives context on optional filters (name, type, owner, modified date) with an example, but does not explicitly contrast with siblings like drive_search or drive_get_file.

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, covering safety and behavior. The description adds that it returns matching files and IDs but does not elaborate on pagination, result size limits (only mentioned in page_size), or response format beyond IDs. With rich annotations, the description adds modest value.

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

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

Two sentences, every word earns its place. The tool's purpose and return value are front-loaded, making it easy for an agent to parse quickly. No unnecessary text.

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

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

Given the tool's complexity (search with query operators), the description, schema, and annotations together provide comprehensive guidance. The output format (matching files and IDs) is mentioned. The agent has enough information 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 descriptions for both parameters. The description goes beyond the schema by providing concrete query operator examples (e.g., 'name contains', 'mimeType =') and mentioning full text search, which adds meaning for the agent. Examples in the schema also help.

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 'Search' and the resource 'Drive files', listing specific search criteria (name, type, owner, modified date, full text) and mentioning query operators. This distinguishes it from siblings like drive_list_files (which likely lists all files without query operators) and drive_get_file (single file).

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

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

The description implies usage for query-based searching but does not explicitly state when to use this tool versus alternatives like deep_research or search_within. No exclusions or comparisons are provided, leaving the agent to infer 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 indicate idempotency, read-only, and non-destructive nature. Description adds valuable behavioral details: fans out across multiple sources, patents soft-fail due to API sunset, news fallback. No contradictions.

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

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

Front-loaded with example queries. Detailed but every sentence adds value. Slightly lengthy but well-structured.

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

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

Despite no output schema, description thoroughly explains return fields and their sources, including caveats about patents. Sufficient for an agent to understand 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 covers both parameters completely (100% coverage). Description enhances semantics by specifying input formats (ticker or zero-padded CIK) and noting names are unsupported. Provides actionable guidance 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 provides a full cross-source profile of a US public company, listing specific data points (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from siblings like compare_entities and resolve_entity.

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

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

Explicitly says to prefer this over chaining single-pack lookups for holistic views, and advises using resolve_entity first if only a name is available. Clear 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 indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not disclose additional behavioral traits beyond what annotations provide.

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

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

Two sentences with no redundancy. The description is front-loaded with purpose and efficiently covers usage and complementary tools.

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 single-parameter tool with good annotation coverage, the description is complete: it explains what it does, when to use it, and how it relates to siblings.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter. The description adds no extra meaning beyond 'by key', so it does not compensate beyond the baseline.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key'. It distinguishes from siblings by mentioning 'remember' and 'recall', which are complementary tools.

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

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

The description explicitly lists three use cases: stale context, task done, or clearing sensitive data. It also recommends 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, read-only, idempotent behavior. The description adds the exact process: fetching the page, extracting title/description/key links, and emitting standard markdown format. No contradictions.

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

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

The description is a single, well-structured paragraph with the main action upfront, followed by process and use cases. Every sentence adds value, 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?

Given the tool's simplicity (2 params, 100% schema coverage, no output schema needed), the description fully explains what the tool does, how it works, and the output format, making it self-contained and easy to understand.

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, baseline at 3. Description adds value by connecting parameters to behavior (e.g., 'max_links' is mentioned as 'maximum number of link entries'), and explains the output format, which is not in schema.

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

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

The description clearly states the verb 'generate' and the resource 'llms.txt file', specifying the action and output. It distinguishes from sibling tools by focusing on a specific, unique task.

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

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

Explicitly lists three practical use cases (indexing client sites, drafting own projects, auditing competitors), providing clear context for when to use the tool. Could benefit from stating when not to use it, but the guidance is strong.

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. Description adds useful behavioral details like the default filtering to active subscriptions and the effect of the include_inactive parameter, plus the exact returned fields. 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?

Two concise sentences: first states purpose and output, second provides usage context. No redundant words, well-front-loaded, earns its place.

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

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

Given the simple schema (one optional boolean, no required params), strong annotations covering safety, and no output schema needed, the description provides complete context for an AI agent to correctly invoke the tool and interpret results.

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

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

Schema covers 100% of parameters with a clear description for include_inactive. The description does not add further semantic value beyond restating the parameter's effect indirectly ('List the caller's active subscriptions' implies default behavior). Baseline for high coverage is appropriate here.

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 clearly that the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes itself from sibling tools like subscribe and unsubscribe by explicitly noting use cases for reviewing or finding subscription ids.

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 using this tool 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use it. It could mention alternatives (e.g., subscribe/unsubscribe) but the guidance is sufficient for 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 are all false, so the description carries the burden and it delivers: it discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota behavior, and the claim_token follow-up mechanism. It stops short of describing error/failure modes or the exact shape of the response, but the key behavioral traits are covered.

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 typical but every section earns its place: purpose, use cases, exclusion, claim_token mechanics, and rate limit. It is front-loaded with the verb and resource, so the essential info appears immediately; the length is justified by the nuanced routing rules.

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

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

Given there is no output schema, the description adequately covers the return behavior via claim_token and describes the practical constraints (rate limiting, daily digests). It does not specify failure response formats, but for a feedback submission tool the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds useful semantics by telling agents to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and by demonstrating claim_token usage with `pipeworx_feedback({claim_token:"pwfb_…"})`. This is meaningful guidance on top of 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?

Opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist', giving a specific verb, resource, and scope. This clearly differentiates it from sibling tools like ask_pipeworx and discover_tools, which are about querying rather than reporting issues.

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

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

Explicitly states when to use: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap)...'. It also gives a firm exclusion: 'if the tool came from a different MCP server in your client... file it with that server instead', so the agent knows not to misroute.

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

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

Annotations already mark it as read-only and idempotent. The description adds valuable context: data source ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('cached 5min-1h depending on window'). No contradictions.

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

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

The description is concise (~100 words) with a clear, front-loaded statement of purpose. It uses bullet points for use cases and ends with important behavioral notes. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, use cases, data origin, privacy, caching, and output structure (top tools, top packs, total call volume). 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% for the single parameter. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which enhances understanding beyond the raw 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 explicitly states it returns 'top tools, top packs, and total call volume' over a window. It clearly distinguishes itself from siblings by focusing on what other agents are calling, with specific use cases that differentiate it from general research tools.

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

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

Three concrete use cases are listed (discovering hot sources, confirming canonical choice, seeing alignment) that provide clear context for when to use this tool. It does not explicitly mention when not to use or name alternatives, but the context is sufficient.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds context: internal algorithms (monotonicity, partition-sum), similarity threshold, placeholder filter, and the need for fill check to avoid trading theoretical edges not present in the book. No contradiction.

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

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

Description is somewhat long but well-structured with clear sections and front-loaded purpose. Every sentence adds value; could be slightly trimmed but not excessive.

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, so description fully explains return values: opportunities array with fields, partition_check object, and fill check details. Covers all three modes and edge cases like low similarity and placeholder filtering.

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 significant value: explains 'event' and 'topic' in detail with examples, and describes the no-arg mode implicitly. Goes beyond schema by explaining when to use each parameter.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes: trending scan (no args), event mode, and topic mode. This differentiates it from siblings like polymarket_edges and 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?

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Also explains when to avoid (e.g., fill check required before trading) and mentions alternatives like polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, but the description enriches transparency by detailing the three model families, caching behavior (1h KV-level), edge components (edge_pp_net, kelly_fraction), tradeable-edge knobs, and exclusions like Fed bets. 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 lengthy but well-structured: purpose, model families, response structure, knobs, and caching. It is front-loaded with the core verb and resource, and each section is clearly delineated, though slightly verbose for some details.

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

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

Given the complexity (multiple segments, no output schema), the description thoroughly explains the response structure (by_segment, diagnostics) and return fields (edge_pp_net, kelly_fraction, etc.). It covers filtering knobs and edge cases, making it complete for an agent to understand 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?

All 9 parameters are described in the schema (100% coverage), so baseline is 3. The description adds value by explaining nuanced behavior (e.g., min_kelly applies to single-leg only, min_partition_leg_kelly for partitions) and providing usage tips, justifying a slightly higher score.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data differs from market price, fulfilling a specific need ('what should I bet on today'). However, it does not explicitly distinguish itself from sibling tools like polymarket_edge_tracker or polymarket_arbitrage, which could have overlapping functions.

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

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

The description implies usage for discovering daily betting opportunities without paging, but it lacks explicit guidance on when to use this tool versus alternatives. No 'when not to use' or comparisons to siblings are provided, leaving the agent to infer 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?

The description provides extensive behavioral details beyond annotations: the structure of the response (tracked, expired, snapshot_dates), computation of trend and decay, lifespan tracking, and limitations like the 60-day TTL. No contradiction with annotations (read-only, idempotent, etc.).

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 packed with useful information but is somewhat lengthy. It front-loads the core purpose and uses a clear structure with sections (RESPONSE, LIMITS). Every sentence adds value, but it could be slightly more concise.

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

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

Despite lacking an output schema, the description fully compensates by detailing the response structure and key fields. It covers limitations and edge cases. For the tool's complexity (time-series analysis), the description is complete.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning to parameters: days as 'lookback' with defaults and clamp, window as 'snapshot family' with examples. This helps the agent understand parameter semantics 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: analyzing edge persistence and decay from daily snapshots. It uses specific verbs ('answers', 'provides') and distinguishes itself from the sibling tool 'polymarket_edges' by focusing on time-series and trend analysis.

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

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

The description explains when to use the tool: to understand if an edge is shrinking and how long it existed. It contrasts fresh vs old edges, implying when to trust the width. However, it does not explicitly list alternatives or when not to use it, but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context: it details the 'walk the ladder' process, explains return fields (vwap_fill_price, slippage_pp, etc.), highlights risks (thin legs, forced directional risk), and confirms it does not execute trades. 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 long but well-structured with clear sections (SINGLE-MARKET, BASKET) and front-loaded 'REQUIRES' and 'USE THIS' directives. Every sentence adds necessary context, though some brevity could be achieved without losing clarity. It is appropriately concise for a complex tool.

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

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

The tool has no output schema, so the description must cover return values, which it does thoroughly (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 baskets). It also covers edge cases and risks, making it complete for an AI agent to decide usage.

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

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

Schema description coverage is 100%, but the description adds significant value by explaining parameter semantics in context: size_usd is 'settlement notional S' for baskets, side defaults to 'auto' based on partition sum, and the market/event distinction is reinforced with mode-specific behavior. This goes far beyond the schema descriptions.

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

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

The description explicitly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It clearly distinguishes single-market and basket modes, specifies the outputs (top_of_book, vwap_fill_price, etc.), and ties usage to specific sibling tools (polymarket_arbitrage, polymarket_edges). The verb 'check' and resource 'order-book depth' are precise and actionable.

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

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

The description provides explicit conditions: 'REQUIRES one of market or event', explains when to use (before arbitrage signals or trades above $500), and warns against misuse ('partial basket fills convert an arb into an unhedged directional position'). It also clarifies default behavior for basket mode when side is omitted. This is comprehensive 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 mark readOnlyHint; description adds extensive behavioral context: response structure, safety fields (compatibility_warning, temporal_alignment), and limitations (real spreads are rarer than shortcuts suggest). 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 front-loaded with core purpose and modes, then details response and safety fields. Some redundancy in safety field explanations, but overall well-organized and each 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 no output schema, the description fully explains response: venue prices, spread array, and safety fields including compatibility_warning scenarios and temporal_alignment. Covers usage limitations thoroughly.

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

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

Schema covers all 3 parameters (100%). Description adds meaning by listing valid topic values, explaining override behavior when explicit tickers are provided, and clarifying that no parameters are required.

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 two modes (topic shortcuts and explicit tickers) and highlights the uniqueness among sibling tools like polymarket_arbitrage.

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

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

Explicitly guides when to use topic mode vs explicit mode, and warns that pre-mapped topics often return compatibility warnings. Also explains conditions under which spreads are meaningful via compatibility_warning and temporal_alignment fields.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail (per identifier like IP or account ID), which is useful beyond annotations.

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

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

Three concise sentences, front-loaded with main purpose, then usage, then scoping. No superfluous words.

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

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

Given the tool's simplicity (1 optional param, clear semantics, strong annotations), the description fully covers purpose, usage, behavior, and parameter nuance.

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 of 'key' parameter. Description adds crucial clarification that omitting key lists all keys, enhancing understanding.

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

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

Description clearly states the tool retrieves a value saved via remember, or lists all keys if no key argument. It distinguishes from sibling tools remember and forget by naming them directly.

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

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

Explicitly says when to use (look up previously stored context) and mentions alternatives: pair with remember to save, forget to delete. Clear guidance for the 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 (readOnlyHint, idempotentHint, destructiveHint) indicate safe, non-destructive behavior. The description adds that mark_read:true updates read state, clarifying a mild mutation is possible. No contradiction with annotations; the description enriches 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 very concise: three sentences that front-load the purpose, then add key details and alternative access. Every sentence earns its place 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 no output schema, the description sufficiently explains the return format (source, citation_uri, raw event payload). It covers filtering, polling, and alternative access. The tool's complexity is low, and the description is complete for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining mark_read functionality and the format for 'since' (ISO timestamp). However, it does not cover 'limit' or 'unread_only' beyond the schema, but that is acceptable since schema already describes them.

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 action: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), the verb (Pull), and details about the return data (source, citation_uri, raw payload). It distinguishes from siblings by mentioning the alternative endpoint for scripts/dashboards.

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 usage context: 'Polls work fine' and an alternative access method (GET endpoint). It also explains the 'mark_read' parameter for flagging events read. However, it does not explicitly state when not to use this tool versus alternatives like 'list_subscriptions'.

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. The description adds details about fan-out to multiple sources, fallback logic, and soft-fail for USPTO. 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 front-loaded with examples and purpose. It is informative but somewhat dense; a bulleted list could improve readability, but it remains efficient without unnecessary words.

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

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

The description covers core functionality, sources, input format, and output structure. It could mention potential limitations like pagination or rate limits, but annotations suffice for safety. Overall adequate.

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

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

Schema coverage is 100%. The description adds meaning by explaining 'since' accepts ISO dates or relative shorthand, and 'value' can be ticker or CIK. This aids correct parameter use.

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

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

The description clearly states the tool's purpose as a change feed for a company, with concrete examples of queries it answers. It distinguishes from the sibling tool entity_profile by specifying when to use each.

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 provides use cases and contrasts with entity_profile for static profiles. It also gives guidance on the 'since' parameter format and typical values like '30d'.

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

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

Discloses key-value storage, scope by identifier, and persistence details (persistent for authenticated users, 24-hour for anonymous). The idempotentHint annotation is accurate for overwriting. 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?

Three concise sentences, each adding distinct value: purpose, usage guidance, and behavioral notes. 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?

Complete for a simple tool: covers purpose, when to use, storage behavior, authentication differences, and pairing with siblings. No output schema, but return value is implicit (success/failure via tool execution).

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 descriptions cover both parameters fully. Description provides examples (e.g., 'subject_property') but adds no syntax or behavior beyond schema. Baseline score of 3 is appropriate given 100% coverage.

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

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

Clear verb ('save data') and resource ('for reuse across sessions'). Distinguishes from siblings recall and forget, and provides concrete examples of what to store.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and mentions related tools (recall, forget) for retrieval and deletion. Lacks explicit when-not-to-use guidance.

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

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

The description goes well beyond the annotations by disclosing internal cascading lookups, source labeling for each identifier, explicit `unresolved` handling, graceful degradation when GLEIF or OpenFIGI is unavailable, and the fact that EDGAR identifiers still return on partial failure. This rich behavioral context helps the agent predict edge cases and partial results.

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: it opens with user query examples, then defines supported types with colon-separated details, and concludes with degradation behavior. Each sentence carries relevant information for an LLM to select and invoke the tool, though it could be slightly tighter by trimming redundant phrasing (e.g., 'accepts ticker, CIK, or company name' duplicates the schema).

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

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

With no output schema, the description compensates by explaining return values per type, including identifier sources, the `unresolved` field behavior, and fallback guarantees. It does not provide an example response shape or exact structure, but given the tool's complexity, the description covers the key contextual needs 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% and the schema already provides detailed parameter descriptions (e.g., ticker, CIK, name for company; brand or generic for drug). The description mostly repeats these examples (AAPL, 0000320193, ozempic) without adding new syntactic or semantic nuance beyond what the schema already states. It adds output context, but that does not elevate parameter semantics.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples of query phrasings and supported entity types (company, drug). It explicitly lists what identifiers are returned for each type (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug), distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

The description gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also explains that other tools require these identifiers as input, positioning this as the prerequisite lookup. However, it does not explicitly name alternatives or provide when-not-to-use conditions, missing the full 5-level guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral details: probing each entity with ai_visibility_check, ranking by score, surfacing most/least recognized, and returning a ranked list with score, confidence, signal density. No contradictions.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds necessary 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 no output schema, the description explains the return format (ranked list with score, confidence, signal density). Parameter descriptions in schema cover all details. The description is complete for a tool with moderate complexity and good annotations.

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% (all 4 parameters described). The description adds value beyond schema by clarifying that the first entity is treated as the 'subject' for narrative and explaining the conditional need for _apiKey. Baseline 3 with good schema coverage; +1 for extra context.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side. It uses a specific verb ('compare') and resource ('AI visibility'), distinguishing it from siblings like ai_visibility_check (single probe) and compare_entities (general comparison).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question, implying when to use. However, it does not explicitly state when not to use or suggest alternative tools, leaving some ambiguity.

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 it as read-only, idempotent, and non-destructive. The description adds significant behavioral context: graceful degradation, potential 5-30s latency on bundlephobia first measurement, and the 'sources_failed' field. This goes beyond annotations and discloses important runtime characteristics.

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

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

The description is a single dense paragraph that leads with the core purpose, then usage, then return structure, then limitations. Every sentence adds value, though it could be trimmed slightly. It is well-structured and front-loaded.

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

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

Given the complexity of the tool (composite call, multiple sources, potential partial failures), the description covers the return block fields, behavior on partial failures, ecosystem scope, and latency. No output schema exists, so the description adequately fills the gap for an agent to understand 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%, so baseline is 3. The description slightly reinforces the default behavior for 'version' but does not add new semantic meaning beyond what the schema already provides. No additional parameter nuances are explained.

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 composite nature, specific resources (npm package, deps.dev, bundlephobia), and the verb 'scan' combined with the 'should I add' check. It distinguishes from sibling tools by explicitly noting it's a one-call composite and mentions the fallback for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks ...' giving clear context. Also specifies that PyPI/Maven/Cargo/Go fall under a different tool (deps.dev:version directly), providing a clear alternative. This guides appropriate usage and exclusion.

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

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

Beyond annotations (which are already safe/read-only), the description reveals: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and every passage includes character offsets for verification. This is 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?

Four sentences with no wasted words. Front-loaded with purpose, then explains usage, pairing, and technical details. 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?

Covers all essential aspects: what it does, when to use, how it works (model, windowing, cap), and what it returns (passages, offsets, scores). Even without an output schema, the description gives enough detail for the agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context like 'use when the record is too big' and 'pass the text you already pulled', but these are usage guidelines rather than parameter semantics. No new parameter-specific meaning beyond what's 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?

Clearly states the tool performs semantic search inside a fetched record, specifying the action (search), resource (inside a fetched record), and output (passages with offsets and scores). Distinguishes from siblings by emphasizing it works on already-fetched text and saves context.

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 when the record is too big for the prompt and pairs with ask_pipeworx_grounded, providing a clear alternative workflow. This gives the agent concrete when-to-use and when-not-to-use guidance.

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

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

Adds significant behavioral context beyond annotations: requires specific auth type, webhook auto-disable after failures, SMS verification requirement, and details on delivery channel behavior. Annotations (readOnlyHint=false, idempotentHint=true, etc.) are consistent.

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

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

Well-structured with clear sections for types and delivery channels. Front-loaded with purpose. Slightly long but every sentence adds value; 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?

Covers all input parameters comprehensively given 100% schema coverage. Mentions return value ('new subscription id'), but lacks explicit response format details; webhook secret return is noted. Adequate for a creation tool.

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

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

Schema coverage is 100%, but description adds substantial meaning: type-specific param examples, webhook signing secret details, and delivery channel constraints that go 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies return of subscription id. Distinguishes from sibling tools like list_subscriptions (listing) and unsubscribe (removal).

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 requires Pipeworx OAuth account, provides examples for each subscription type (sec_8k, polymarket_edge, etc.), and mentions delivery channel options and limitations (SMS cap, webhook auto-disable). Does not explicitly state 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?

Annotations already indicate readOnly, idempotent, and non-destructive, so the description only needs to add behavioral context. It describes what the tool returns (category-bucketed example questions with tool shapes), which is sufficient. 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 relatively long but every sentence adds value. It is front-loaded with common user questions and structured with examples, making it informative without being verbose.

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

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

For a simple tool with one optional parameter and no output schema, the description completely explains the input, output, and use case. It covers what the tool does, when to use it, and what results 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 covers 100% of parameters, but the description adds valuable context: the list of possible topic values and the effect of omitting the parameter (cross-category spread). This goes beyond the schema's description.

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

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

The description clearly states the tool's purpose: to suggest example questions for Pipeworx, acting as an onboarding entry point. It uses specific verbs ('suggest', 'show') and distinguishes itself from siblings like ask_pipeworx by focusing on exploration rather than answering.

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 it (first when unsure what Pipeworx can do) and how to use it (no arguments for full spread, or pass 'topic' to focus). It also mentions learning about meta-tools, providing clear 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?

The description adds crucial behavioral details beyond annotations: the row is deactivated (not deleted) and historical events remain available via recent_alerts. This complements the idempotentHint and destructiveHint annotations without contradiction.

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

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

Two sentences, each providing essential information: the action (cancel), constraint (ownership), and side effect (deactivation vs deletion). No redundancy or unnecessary words.

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

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

The description covers the core function, constraints, and behavioral nuance. However, it does not mention the return value or confirmation, which could be helpful for a mutation tool. Given the presence of sibling tools and annotations, it is nearly complete.

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

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

The input schema already fully describes the single parameter 'id' with its type and origin ('Subscription id (uuid) returned by subscribe'). The description does not add new meaning, so baseline 3 applies (schema coverage 100%).

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

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

The description clearly states the tool cancels a subscription by ID, and distinguishes it from siblings like subscribe (creation) and list_subscriptions (listing). The verb 'Cancel' and resource 'subscription' are 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 specifies ownership enforcement ('you can only cancel your own subscriptions'), which guides appropriate usage. It does not explicitly list when not to use or mention alternatives, but the context is clear for a straightforward cancellation.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important runtime behavior: it routes claims differently based on domain, returns a structured verdict set, and attaches pipeworx:// citations. It also defines tricky result states—could_not_verify means the check didn't happen and must not be treated as evidence, while unsupported means no source exists. This is rich behavioral context that annotations alone don't provide.

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

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

Although longer than a simple two-sentence description, every sentence earns its place: it opens with query examples, states the use case, describes routing, defines the return payload, explains critical caller caveats, and even notes the tool replaces 4–6 sequential calls. It is front-loaded and information-dense 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 (two routing paths, multiple verdicts, error states) and the lack of an output schema, the description covers all necessary context: what it returns (verdict, actual value, citation, reasoning), how to interpret edge cases (could_not_verify vs unsupported), and the composite nature (replaces multiple calls). The agent has enough information to invoke and interpret results correctly.

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

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

The schema already provides 100% coverage for both parameters, and the description adds extra meaning: claim is shown with real-world examples, and tolerance_pct is explained as overriding the claim's implied tolerance with a suggestion to use 1–2 for hallucination detection. This enriches the schema's minimal definitions.

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

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

The description opens with concrete natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…') and clearly states the tool validates claims against authoritative sources. It specifies the two routing paths (SEC EDGAR for company financials, grounded pipeline for everything else), which distinguishes it from sibling ask_pipeworx tools by focusing on fact-checking rather than general Q&A.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear invocation condition. It also explains when the SEC EDGAR fast path applies versus the grounded pipeline. However, it doesn't name specific alternative tools or state explicit 'when not to use' scenarios, so it doesn't fully earn a 5.

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