Google_docs

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds beyond that by noting that the default model is free and that Anthropic probing requires the user to bring their own API key, disclosing the cost implication.

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

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

The description is well-structured with the main action front-loaded. It is concise at 3-4 sentences, but could slightly tighten language without losing clarity. Still, it efficiently conveys essential information.

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

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

Given the tool's complexity (4 parameters, no output schema, rich annotations), the description covers purpose, parameters, usage scenarios, and behavioral notes adequately. It provides enough context 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% with descriptions for all parameters. The description adds value by explaining the default model, cost implications of _apiKey, and the purpose of the context parameter for disambiguation, going beyond the schema details.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility numerically. It specifies the default model and provides concrete examples, making its function distinct from sibling tools like ask_pipeworx or 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?

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when the optional _apiKey is needed. While it doesn't explicitly state when not to use or compare to alternatives, the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive; description adds meaningful behavioral context: it routes questions, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. 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?

Though long, the description is front-loaded with the most important instruction (prefer over web search) and each subsequent sentence adds distinct value: scope, examples, alternatives, and caveats. The structure with examples and step-up guidance makes it easy to scan.

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

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

Given no output schema, the description explains the return format (structured answer with citation URIs) and covers tool scope, usage triggers, examples, and alternatives. It is complete for a meta-router tool of this complexity.

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

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

Schema covers 100% of parameters (all aliases for question), so baseline is 3; description adds value by specifying the natural-language question format, giving concrete examples, and clarifying that aliases are accepted. It doesn't deeply elaborate parameter syntax, but that's unnecessary given 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 identifies ask_pipeworx as a routing/aggregation tool for factual questions across 5,566 tools and 1,462 sources, returning structured answers with citation URIs. It explicitly distinguishes itself from siblings by positioning as the default entry point and naming alternatives (ask_pipeworx_grounded, deep_research).

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

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

Provides explicit when-to-use guidance: prefer over web search for factual/current/historical data, use for 'what is', 'look up', 'find', etc. It also gives step-up conditions for grounded answers and deep_research, plus a breaking-news note.

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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond those annotations: it is beta, may contain experimental routing changes, falls back to nothing, and is a fully working router rather than a stub. It does not contradict annotations.

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

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

The description is front-loaded, informative, and every sentence contributes: the beta identity, identical surface, current status, usage recommendation, and fallback behavior. It is moderately detailed but all content 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?

For a tool with only one meaningful input and no output schema, the description gives enough context: it names the stable reference tool, confirms current behavior, and clarifies its experimental function. It could describe the actual response shape more independently, but the pointer to ask_pipeworx's response shape is adequate given the sibling context.

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

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

Schema coverage is 100% and all six parameters are clearly documented as aliases for the question. The description adds no real parameter-level semantics beyond saying it uses the same arguments as ask_pipeworx, which is not necessary because the schema already fully explains the input surface.

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

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

The description states this is the beta version of ask_pipeworx, an identical universal router with the same 5,566 tools, arguments, and response shape. It clearly distinguishes itself from the stable sibling by explaining it carries experimental routing improvements; it is specific about what changes and what stays the same.

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

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

It provides explicit guidance: use it exactly like ask_pipeworx when the newest routing behavior is desired, and notes results are compared against the stable router. It also explains that currently no candidate is active, so behavior currently matches ask_pipeworx exactly. This is strong when-vs-alternative 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?

Beyond the annotations (readOnlyHint, etc.), the description discloses behavioral details such as extracting answers only from tool results, returning evidence and confidence, providing refusal reasons, and costing an extra LLM call—none of which are covered by 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 detailed but well-structured, starting with a clear summary and then covering mechanism, return format, usage, and cost. It is appropriately sized for the complexity, though slightly verbose in places.

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, the description is complete: it explains the return format, refusal scenarios, usage context, and cost implications. No critical information is missing for an agent to decide when and how to invoke it.

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

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

The input schema already provides a comprehensive description of the 'question' parameter with all aliases, achieving 100% coverage. The tool description does not add further parameter-specific semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, and distinguishes it from the sibling tool ask_pipeworx by highlighting its rigorous evidence-based approach and additional LLM call cost.

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

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

It explicitly specifies when to use this tool (when answers will be quoted, cited, or acted on, and facts must not be invented) and when to prefer the alternative (casual lookups), providing clear usage boundaries.

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

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

The description extensively details behavioral traits beyond annotations: fan-out logic, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, closed market handling, wide spread warnings, and cancellation rules. 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 comprehensive but verbose, at several paragraphs. It is structured with capitalized section headers for readability, but contains redundant explanations (e.g., repeated resolution paths). Could be more concise while retaining key information.

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

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

Given the tool's complexity (multiple data sources, classification, fan-out, response shapes, edge cases), the description covers all necessary aspects. It explains resolver behavior, parent events, fallback mechanisms, safety guards, and cancellation rules. No output schema exists, so the detailed response shape description is essential and well-provided.

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

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

With 100% schema description coverage, baseline is 3. The description adds context: it explains the effect of 'depth' (quick vs thorough fan-out) and 'include_raw' (response size trade-offs). This enhances the agent's understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and the process (resolve, classify, fan out, return evidence). Usage scenarios are given ('should I bet on X', etc.), 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?

The description provides explicit usage guidance ('Use for...'), but does not specify when not to use the tool or contrast it with sibling tools like polymarket_edges or polymarket_arbitrage. The guidance is clear for intended use but lacks exclusion criteria, leaving some ambiguity for the 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?

Adds details beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of special fiscal years, sorting by primary metric, and citation URIs. 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?

Description is moderately long but every sentence adds value. Starts with example queries, then usage preference, then data details. Could be more concise but justified by richness of information.

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

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

Given the tool has two parameters, no output schema, and annotations, the description covers purpose, usage, parameter details, behavior, and results. Adequate for the complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context: explains what 'company' and 'drug' types pull (e.g., revenue, adverse events), provides examples for values (tickers vs names), and mentions constraints (2-5 items).

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 purpose: side-by-side comparison of 2-5 companies or drugs. Provides example queries (e.g., 'X vs Y', 'head to head') and distinguishes from sequential lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups' and explains the query patterns that trigger this tool. Also mentions replacing 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 with readOnly/openWorld/idempotent annotations, the description adds substantial behavioral context: account/paid-plan requirements, parallel facet decomposition, gaps[] behavior, never invented, contradictions[] for standard/thorough, hop fields, always-fetchable citations, excerpting semantics, and expected latency ranges. This far exceeds the annotation burden without contradicting it.

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 each sentence adds distinct, valuable information: auth, fallback, scope, output shape, retrieval behavior, exclusions, depth behavior, citation guarantees, contradiction handling, excerpting, and latency. It is front-loaded with the most selection-critical account/warning note. Slightly dense but not verbose or tautological.

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

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

There is no output schema, so the description carries the full burden explaining what the agent will receive and experience: findings packets, verbatim evidence, sources, citations, gaps[], hop, contradictions[], and performance behaviors. It also covers auth and parameter effects, making the selection and invocation decision interpretable without external info.

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

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

Schema coverage is 100%, so description need not restate both parameters. It still improves on the schema by explaining depth strategy in prose: quick implies one hop, standard adds gap recovery and contradictions, thorough also chases leads. The question parameter is also enriched with example usage. Not 5 because the schema already carries strong 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?

States a specific action and resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call. It also explicitly distinguishes the tool from open-web search and from ask_pipeworx by scope: broad/multi-part structured-data questions versus single lookups and breaking news.

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

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

Description gives explicit when-and-when-not guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also names the ideal usage scenario: broad/multi-part questions over structured data.

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 safe read-only behavior (readOnlyHint, idempotentHint). The description adds that it returns top-N tools with full schemas and curated examples, ready to call directly, which is valuable behavioral context beyond annotations.

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

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

Description is concise (4 sentences) and well-structured: purpose first, then use cases, then return value. No unnecessary words.

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

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

Complete for a discovery tool: explains what it does, when to use, what it returns. No gaps despite lacking output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing example queries and clarifying that query accepts natural language, but parameter details are already in the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous example use cases (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a discovery tool, not a specific data source tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' and 'Use when you need to browse, search, look up, or discover what tools exist for...' This provides clear when-to-use guidance.

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

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

Annotations already declare write operation and idempotency. Description adds that text goes to the end, but does not disclose auth needs or output format.

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

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

Single sentence, no wasted words, purpose 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?

For a simple append tool with full schema and output schema, description is sufficient. Provides usage guidance.

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

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

Schema covers 100% of parameters with descriptions. Description adds no extra parameter details beyond schema.

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

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

Description clearly states verb 'Add', resource 'Google Doc', and scope 'to the end'. Distinguishes from siblings like docs_insert_text.

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 when insertion position doesn't matter', implying context. But does not name sibling tools or state when not to use.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the return value context (document ID), which is useful. However, it does not explain behavioral implications like whether creating a doc with an existing title succeeds or any side effects beyond creation.

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 consists of two short, front-loaded sentences that efficiently convey purpose and key output. Every word adds value, and there is no redundancy or unnecessary 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?

Despite having only one parameter, the description completely covers what the tool does and what it returns. The output schema existence is signaled, and the return value (document ID) is mentioned, which is sufficient for a simple creation tool given the 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%, and the input schema already describes 'title' as 'Title for the new document'. The description only mentions 'with a title', adding no new meaning beyond the schema. The examples in the schema provide context, so the description is sufficient but not compensatory.

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 'Create', resource 'a Google Doc', and the key result 'returns the document ID needed for editing operations'. This effectively distinguishes it from sibling tools like docs_append_text, docs_get, etc., which focus on editing or reading existing documents.

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 purpose but offers no explicit guidance on when to use this tool versus alternatives (e.g., when to create a new doc vs. edit an existing one using sibling tools). Usage is implied by the action, but no exclusions or context are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explicitly stating the return fields (title, formatted body content, document structure), giving the agent a clear picture of the behavioral outcome.

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 sentence with no redundant words. It conveys purpose and output efficiently.

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 required parameter and an existing output schema, the description is complete: it states the action, the input identifier, and the output content. No major gaps are present.

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

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

The input schema already describes the document_id parameter well ('Document ID (from the URL)') with 100% coverage. The description adds no further parameter details beyond 'by ID', so it meets the baseline but does not enhance.

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

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

The description clearly states the verb 'Retrieve' and the resource 'Google Doc by ID', and specifies the return values (title, formatted body content, document structure). This distinguishes it from sibling tools like docs_get_text (text only) and docs_append_text (write operation).

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 retrieving full doc content but does not provide explicit guidance on when to use this tool versus alternatives like docs_get_text, nor does it mention when not to use it. Siblings exist but no comparison is made.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that extracting plain text results in no formatting or structure, which is a behavioral trait beyond annotations.

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

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

Two sentences front-loaded with action and purpose. Every word earns its place; no unnecessary detail.

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

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

With one parameter, annotations covering safety, and an output schema, the description is complete for this simple tool. It clearly defines the tool's purpose and 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 coverage is 100%, so the schema already documents the parameter. The description does not add additional meaning beyond what the schema provides, such as where to find the document ID.

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 extracts plain text from a Google Doc without formatting or structure, distinguishing it from siblings like docs_get which likely return structured content.

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 mentions 'Use when you need raw text content only,' providing a clear use case. It implies not to use when formatting or structure is needed, though it could explicitly mention alternatives.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the description adds minimal behavioral context beyond specifying the insertion position. It does not discuss side effects like shifting existing text or handling out-of-range indices. No contradiction with annotations.

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

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

The description is a single sentence with an example in parentheses, extremely concise with no unnecessary words. Every part earns its place.

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

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

Given the tool has an output schema and the annotations cover safety aspects, the description is minimally complete for a simple insertion. However, it lacks details on edge cases (e.g., index out of bounds) and does not explicitly distinguish from sibling tools, which would enhance completeness.

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

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

Schema coverage is 100%, so the baseline is 3, but the description's example suggests index 0 for start while the schema states 1 = start, which is misleading. This reduces the value added 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 inserts text at a specific position in a Google Doc, with examples indicating start and middle. However, there is an inconsistency between the description (position 0 for start) and the input schema (index 1 = start of body), which could cause confusion.

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

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

The description provides examples of when to use (insert at start or middle), but does not explicitly differentiate from sibling tools like docs_append_text or docs_replace_text. Guidance is implied but not explicit, leaving the agent to infer alternatives.

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

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

The description asserts a mutation operation ('Find and replace...'), but annotations declare readOnlyHint=true and destructiveHint=false, which is a direct contradiction. The description does not reconcile this, leaving the agent with inconsistent signals about the tool's behavior.

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

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

The single-sentence description is concise and front-loaded with the action. However, it lacks any structured breakdown or additional context that might help. It earns its place but could be more informative.

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

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

Given the tool's mutation nature and the contradiction with annotations, the description fails to provide complete context. It does not mention that all occurrences are replaced, nor does it address idempotency or start/end positions. The output schema exists but is not described, and the description does not compensate for the misleading 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 coverage is 100% (all 4 parameters described). The description adds no additional meaning beyond the schema; it merely restates the function. Baseline 3 is appropriate.

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

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

The description clearly specifies the action ('find and replace'), the resource ('text in a Google Doc'), and the scope ('all occurrences'). It effectively distinguishes this tool from sibling tools like docs_append_text or docs_insert_text.

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 is provided on when to use this tool versus alternatives. For example, it does not contrast with docs_insert_text or docs_append_text, nor does it mention prerequisites like document ownership.

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 readOnlyHint and idempotentHint annotations, the description details the tool's behavior: it fans out across multiple sources, returns specific fields (e.g., up to 5 filings, sorted fundamentals), notes the USPTO soft-failure, and explains the input format requirements. This is comprehensive and adds significant value.

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

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

The description is somewhat lengthy but efficiently uses every sentence to convey crucial information. It is front-loaded with examples and a clear statement of purpose, and the subsequent details are well-organized. It could be slightly trimmed, but overall it earns its length.

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

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

Given the complexity of this tool and the lack of an output schema, the description thoroughly explains what the tool returns (e.g., cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers limitations and dependencies, making it fully informative 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?

The input schema already has 100% coverage for the two parameters. The description adds context by noting that names are not supported and that 'resolve_entity' should be used first if only a name is available, which enhances understanding beyond the schema.

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

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

The description clearly states that the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It includes specific examples like 'Tell me about X' and explicitly distinguishes it from chaining individual lookups, making the purpose unambiguous.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises to use 'resolve_entity' if only a name is available, covering when to use and when not to use this tool.

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

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

Annotations set destructiveHint=true, description confirms destructive behavior and adds context about clearing sensitive data. No contradictions.

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

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

Three concise sentences covering purpose, usage, and relationships. No redundancy or unnecessary detail.

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

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

Simple tool with single parameter; description fully covers intent, usage context, and relationships with siblings. No output schema needed.

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

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

Schema coverage is 100% and parameter 'key' is well-described in schema. Description adds no additional semantics beyond 'by key', earning baseline 3.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying verb and resource. Differentiates from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests 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 readOnlyHint, idempotentHint, destructiveHint=false. Description adds process details: fetches page, extracts title/description/key links, emits standard markdown. No contradictions; fully transparent about read-only, non-destructive behavior.

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

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

Front-loaded with main action and purpose in first sentence. Process in second, output format in third, use cases in bullet list. No redundant words; 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?

Given tool simplicity and rich annotations/schema, description covers all essential aspects: action, input, process, output (single text blob), and use cases. No output schema needed; context 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%, so baseline 3. Description does not explicitly detail parameters but implies max_links controls link count. Schema descriptions are clear, so description adds no significant extra meaning.

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

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

Clearly states verb+resource: 'Generate a production-ready llms.txt file for any URL'. Specifies output format and purpose (AI crawlers). Distinguishes from siblings like ai_visibility_check by focusing on file generation.

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

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

Provides concrete use cases in a bullet list (client indexing, own project, competitor auditing). Lacks explicit when-not-to-use or comparison with alternatives, but the scenarios are 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 signal readOnly and idempotent. The description adds value by specifying the returned fields and the optional include_inactive parameter behavior.

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

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

Two concise sentences: first states purpose and output, second provides usage context. No wasted words.

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

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

Despite no output schema, the description fully describes the return format and usage context. The single optional parameter is explained in the schema.

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

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

Schema coverage is 100% (baseline 3). The description adds value by listing the returned fields, which are not in the schema, helping the agent understand what to expect.

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

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

The description clearly states it 'list the caller's active subscriptions' and enumerates returned fields (id, type, params, etc.), distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't state when not to use it, this is sufficient for a listing 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 annotations only provide false hints, so the description carries the burden and does so excellently. It discloses rate limits ('Rate-limited to 5 per identifier per day'), no cost ('Free; doesn't count against your tool-call quota'), triage flow ('The team reads digests daily'), and the claim_token round-trip behavior. No contradiction with annotations.

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

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

The description is dense but front-loaded with its purpose and contains no filler. However, it is a single long paragraph; while every sentence earns its place, it could be slightly more scannable with visual structure. Still, it remains appropriately sized for the amount of critical guidance it conveys.

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 moderate complexity (4 optional params, nested context object, claim-token flow) and no output schema, the description is complete. It covers expected use cases, exclusions, account-optional behavior, rate limits, cost, and the post-filing follow-up flow. The agent has enough information to decide when and how to invoke correctly.

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

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

Even though schema coverage is 100%, the description adds meaningful parameter-level context beyond the schema. It gives an explicit invocation example for claim_token (`pipeworx_feedback({claim_token:"pwfb_…"})`), explains when to use each argument, and instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting the end-user's prompt.

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 ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly identifies the resource (Pipeworx team/tools). It also distinguishes itself from siblings by explicitly limiting use to tools served by this Pipeworx connection and contrasting with other MCP servers.

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

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

The description provides explicit when-to-use guidance for each feedback type ('Use when a tool returns wrong/stale data (bug)...') and equally explicit when-not-to-use guidance ('ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead'). It also gives an alternative path for uncertain cases, making the decision boundary very clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: self-aggregating from CF analytics engine, no PII, caching 5min-1h. 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?

Three sentences plus bullet use cases. Front-loaded with main output, then usage, then technical details. Every sentence adds value, no waste.

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

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

No output schema, but description explains return structure (top tools, packs, volume) and covers caching, data source, privacy. Complete for a simple tool with one optional param.

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% with enum. Description adds meaning: shorter windows for what's hot, longer for steady-state demand. Provides 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?

Clearly states it returns top tools, top packs, and total call volume over a window. Uses specific verb 'returns' and describes resource. Three use cases further clarify purpose and differentiate from sibling tools.

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

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

Explicitly lists three scenarios for use (discovering hot data, confirming canonical choice, aligning use case). Provides clear context but does not mention when not to use or alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. The description adds significant behavioral details: fill check warning ('do not trade it'), partition filter logic, semantic anchor (Jaccard similarity), and placeholders filter. 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 thorough but verbose, spanning multiple paragraphs. It is well-structured with clear sections but could be more concise. Some sentences could be trimmed without losing meaning.

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

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

Given the complexity (two modes, multiple checks, response format), the description covers all necessary aspects: input modes, logic, response fields (opportunities[], partition_check, fill check), and edge cases (placeholder filter). No output schema exists, but description compensates by listing response fields.

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

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

Schema coverage is 100% with descriptions for both event and topic. The description goes beyond schema by explaining default behavior (no args), providing examples of slugs and seed questions, and detailing when to use each parameter. Adds substantial meaning.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no-args, event, topic) with specific verbs and resources. No tautology or ambiguity.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market): pass a Polymarket event slug...', 'topic (for cross-event scanning): pass a seed question...'. It also warns when not to trade (fill check). However, it does not explicitly contrast with sibling tools like polymarket_edges.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: three segment logic, cache behavior (1h KV keyed on knobs), diagnostics for empty segments, Fed bet exclusion with reason, and a 24h-move warning. This far exceeds annotation coverage.

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

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

The description is long and detailed, which is valuable, but it is not concise. It front-loads the purpose and then dives into technical explanations of segments. While well-structured, it could be shortened without losing meaning.

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

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

Given the tool's complexity (9 parameters, no output schema, three segments), the description is exceptionally complete. It covers output structure, segment logic, edge cases (empty segments, Fed bets), caching, and parameter interactions. No gaps identified for informed 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 description coverage is 100%, so baseline is 3. The description repeats some parameter info (e.g., slippage_pp, min_liquidity) but does not add significant new meaning beyond the schema. The explanation of min_partition_leg_kelly adds marginal value but not enough to raise the score.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and differentiates from sibling tools by focusing on data-disagreement edges. The verb 'scan' and resource 'opportunities' are specific and unambiguous.

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

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

The description provides clear usage context: 'agents discover opportunities without paging hundreds of markets.' It explains tradeable-edge knobs and diagnostics for empty segments. However, it does not explicitly contrast with siblings like polymarket_arbitrage or polymarket_edge_tracker, missing an opportunity to guide when NOT to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant context: return structure (tracked, expired, snapshot_dates), edge_pp_net sign meaning (negative = SELL YES), decay computation from daily closes, and constraints (60-day TTL, snapshot start, no intraday data).

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 long paragraph covering purpose, response fields, and limitations. While comprehensive, it is somewhat verbose and could be broken into sections for readability.

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

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

No output schema exists, so the description fully explains return fields (tracked, expired, snapshot_dates), their substructures (edge_pp_net time-series, first_seen, trend, decay_pp_per_day, lifespan_days), and critical limitations (60-day TTL, gap handling, decay definition).

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 repeats defaults and clamps for 'days' (default 14, max 30) and 'window' (default '1wk'), adding marginal value beyond schema descriptions.

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

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

The description states it provides edge persistence telemetry answering 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old edges, clearly distinguishing from sibling tools like polymarket_edges (raw edges) and 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?

The description implies use when edge decay/persistence analysis is needed, and contrasts with fresh vs old edges, but does not explicitly list when not to use or name sibling alternatives like polymarket_edges for raw edge snapshots.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: it lists return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains basket-mode risks (forced_directional_risk, thin_legs), and clarifies that partial fills convert arbitrage into directional positions. 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 dense with technical detail and covers two modes thoroughly. It is front-loaded with purpose and mode requirements, then uses a bullet-like structure for modes. While every sentence adds value, it could be more concise; a slight reduction in verbosity would improve readability.

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

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

Given the tool's complexity (two modes, many return fields, no output schema), the description is highly complete. It explains both modes, default behaviors, all return fields, and critical risks (e.g., 'partial basket fills convert an arb into an unhedged directional position'). No gaps remain for an agent to use the tool correctly.

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

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

Schema description coverage is 100% (all 4 parameters described in schema). The description adds meaning beyond the schema: how `side` default works in basket mode ('auto from partition sum'), interpretation of `size_usd` in basket mode ('settlement notional S (shares per leg; each share pays $1)'), and clamping range (10–1,000,000). This significantly aids correct invocation.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It also explicitly connects to sibling tools, saying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', which differentiates it effectively.

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: use this tool before acting on arb signals or above $500. It explains why skipping it risks unhedged directional positions and notes the dominant loss mode. This is comprehensive and actionable.

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

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

While annotations already indicate readOnly and idempotent, the description adds extensive behavioral details: two modes, response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment), and skipped counters. It also discloses limitations (pre-mapped ≠ tradeable) and conditions for no arbitrage.

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

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

The description is lengthy but well-structured with an opening summary, mode explanations, and detailed response field descriptions. Every sentence adds value, and the complexity justifies the length. However, 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?

Given no output schema, the description fully covers output fields (leg-by-leg prices, spreads, compatibility_warning, temporal_alignment) and edge cases (matched_pairs=0 scenarios). It addresses the tool's flexibility with optional parameters and explains both modes comprehensively.

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

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

Schema describes all parameters with 100% coverage. The description adds context: topic shortcuts list, explicit parameters override topic-mapped sides, and examples. This adds meaning beyond schema definitions, though baseline is high due to coverage.

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

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

The description clearly states the tool calculates cross-venue spread between Kalshi and Polymarket, distinguishing it from sibling Polymarket-specific tools. The verb 'spread' and resource 'cross-venue' are specific, and the tool's unique value is well-defined.

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

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

The description explains two usage modes (topic shortcuts and explicit tickers) and provides explicit guidance on when spreads are meaningful via compatibility_warning, temporal_alignment, and skipped counters. It warns that most pre-mapped topics are not tradeable, setting clear expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping (by identifier) and the dual behavior when omitting the key. No contradictions.

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

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

Two well-structured sentences that front-load the main action and then provide context and pairing instructions. No wasted words.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers all essential behavioral aspects: retrieval vs. listing, scoping, and pairing with siblings. Nothing is missing.

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

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

Schema has 100% coverage with a description for the key parameter. The description adds context about listing all keys when omitted, which is not in the schema. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: retrieving a value by key or listing keys. It specifies the relationship with 'remember' and distinguishes itself from siblings by naming 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?

Explicit guidance on when to use ('look up context the agent stored earlier') and pairing with 'remember' and 'forget'. It also clarifies scoping by identifier.

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

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

Description states that setting mark_read:true flags events as read, which implies a state mutation, contradicting the readOnlyHint:true annotation. This is a serious inconsistency that undermines trust in the tool's behavior.

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

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

The description is concise and front-loaded, starting with the core action. It efficiently covers key fields, filters, and the mark_read behavior, with no unnecessary sentences. Slight room for improvement by grouping related info more tightly.

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?

Has no output schema but describes return fields adequately. Mentions polling and alternate endpoint, but lacks explanation for unread_only and limit parameters, and does not address authentication or rate limits. The contradiction reduces completeness.

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 5 parameters are documented in the schema (100% coverage). The description adds value by explaining mark_read's effect (only newer events on next call), giving an example for type ('sec_8k'), and clarifying since usage, but omits details on limit and unread_only.

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

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

Clearly states it pulls fired events from the subscription feed, specifying verb ('pull') and resource ('recent alerts'). The description distinguishes it from sibling tools by focusing on the persisted feed and mentioning an alternative REST endpoint.

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 clear usage context: returns recent alerts, filterable by type and since, with mark_read feature to manage read state. Mentions polling is acceptable and notes an alternative HTTP endpoint, but does not explicitly compare with sibling tools or state when not to use.

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

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

Annotations already provide safety traits (readOnlyHint, idempotentHint, etc.). Description adds operational context: makes one parallel call, fan-out behavior, source fallback, and soft-fail note. Could be 5 but does not explicitly confirm no side effects beyond annotations.

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

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

Single paragraph front-loaded with usage examples, then behavior, then parameters, then alternative. 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?

Fully explains tool behavior, parameter semantics, output shape (changes grouped by source), and alternative tool. No output schema but description covers return structure adequately.

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%. Description adds valuable extra guidance: relative date shorthand examples, recommended typical values, and that value accepts ticker or CIK. This exceeds schema documentation.

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 provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). Distinguishes from sibling entity_profile by contrasting dynamic vs static profile.

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

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

Provides explicit query examples ('What's new with X', 'latest on Y') and explicit when-to-use vs entity_profile. Also explains fallback behavior (GDELT→GNews) and soft-fail for USPTO.

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

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

Description adds details beyond annotations: scope by identifier, persistence for authenticated vs anonymous sessions (24 hours), and cross-session reuse. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Three sentences with useful info; could be slightly tightened but each sentence earns its place. No wasted words.

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

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

For a simple key-value store with no output schema, the description covers purpose, usage triggers, behavior details, and companion tools. Fully adequate.

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

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

Schema coverage is 100% with clear descriptions. Description adds no new parameter information beyond what schema 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 clearly states verb 'save data' and resource 'key-value pair', and distinguishes from siblings recall and forget by naming them explicitly.

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

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

Explicitly says 'Use when you discover something worth carrying forward' with concrete examples, and instructs to pair with recall and forget.

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. The description adds substantial behavioral context: lists specific identifiers returned (CIK, ticker, LEI, FIGI, RxCUI), explains labeling by source, explicit unresolved identifiers, graceful degradation when GLEIF/OpenFIGI unavailable, and cascading internal lookups. No contradiction with annotations.

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

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

The description is longer than average but front-loaded with examples and explicit usage guidance. Every sentence adds value, but some details (e.g., graceful degradation explanation) could be slightly condensed without losing clarity. Well-structured for the complexity.

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

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

Given the tool's complexity (two entity types, multiple identifiers, data sources, degradation), the description covers return values (unresolved listed, labels with source), usage constraints, and internal behavior. No output schema exists, so the description adequately explains what to expect from the result.

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 significant meaning beyond the schema: elaborates on company type (accepts ticker, CIK, ISIN, or name; ISIN resolves via LEI mapping), drug type (RxCUI + ingredient + brand), and provides examples and caveats (e.g., graceful degradation).

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 a user-spoken name to canonical/official identifiers, with examples like ticker, CIK, LEI, RxCUI. It explicitly distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID' and listing supported types (company, drug) with specific use cases.

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

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

The description provides clear context on when to use (examples like 'look up the ticker for...') and states 'Use FIRST whenever you have a name but need an ID.' It does not explicitly exclude alternatives or mention sibling tools like compare_entities, but it implies usage for name-to-ID resolution.

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

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

The description adds behavioral context beyond annotations: it probes each entity with 'ai_visibility_check', ranks results, and returns scores, confidence, and signal density. Annotations already declare readOnlyHint and idempotentHint, so the description complements rather than repeats.

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 focused sentences with no wasted words. It front-loads the core action and immediately follows with use case and output details. Excellent conciseness.

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

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

For a tool with good annotations and full schema coverage, the description adequately covers process and output fields. Missing elements like exact error handling or entity count constraints are covered by the schema. The description is complete enough for effective tool selection and 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 is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' and that the context parameter disambiguates common names. This provides semantic guidance beyond the schema.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It uses specific verbs ('Compare', 'Probes', 'ranks') and identifies the resource ('AI visibility'). It distinguishes itself from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (broader) by focusing on AI recognition scores.

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 context for use: competitive AI-marketing audits, with an example question. It implicitly differentiates from the single-entity 'ai_visibility_check' sibling. Although it lacks explicit when-not-to-use guidance, the context is sufficient for an AI agent to decide.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds critical runtime details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. This goes well beyond what annotations provide.

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

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

The description is information-dense and front-loaded with the core purpose. While slightly verbose, every sentence adds value and is justified given the complexity of the tool. No extraneous content.

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

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

Without an output schema, the description fully details the return structure: summary block fields, advisory details, links, and alternative versions. It also explains partial failure behavior and response shape, leaving no gaps for an agent to guess.

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

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

Schema coverage is 100% with both parameters documented. The description minimally adds that scoped packages are accepted for 'package' and defaults for 'version', but the schema already conveys these. Baseline of 3 is appropriate as the description does not significantly enhance parameter 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?

The description clearly states the tool performs a composite check for adding an npm package, fanning out across deps.dev and bundlephobia. It specifies the resources (license, advisories, bundle size) and distinguishes from siblings by noting it's NPM-only in v1.

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

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

Explicitly says 'Use whenever an agent asks is X safe / popular / small' and gives an example ('what does adding lodash cost me'). It also clarifies NPM-only and directs other ecosystems to deps.dev directly, providing clear when-to and when-not-to 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 this as read-only, open-world, idempotent, and non-destructive. The description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char limit with truncation flagging. 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 efficient: the first sentence captures the core purpose, and each subsequent sentence adds essential context, use cases, technical details, and limitations without repetition 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 moderate complexity, the description covers purpose, inputs, outputs, technical behavior, limitations, and complementary tools. Even without an output schema, the description explains what the agent can expect (passages, offsets, similarity scores).

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

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

The input schema has 100% coverage with clear descriptions. The description adds value by reinforcing the max char limit and providing example queries for context. However, it doesn't add significantly beyond what the schema already conveys, earning a 4 instead of 5.

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: 'Semantic search INSIDE a fetched record.' It specifies the inputs (text and query) and outputs (passages with offsets and scores). It distinguishes from potential siblings by emphasizing internal search versus external, and explicitly pairs with ask_pipeworx_grounded for grounding.

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: 'Use when the record is too big to cram into the prompt.' It explains the benefit (saves context, returns relevant passages with offsets) and suggests a complementary workflow (pair with ask_pipeworx_grounded). This tells the agent when to use and how to combine with other tools.

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

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

The description adds significant behavioral context beyond annotations, such as requirements for an OAuth account, delivery channel details (email, SMS with rate limits, webhook with signing and auto-disable), and type-specific parameter examples. However, the idempotentHint annotation (true) is not addressed, and the description's 'Returns the new subscription id' suggests non-idempotent behavior, though not explicitly contradictory.

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

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

The description is fairly long but well-structured and front-loaded with the main purpose. Every sentence adds useful information, avoiding redundancy. Minor improvements could be made by tightening some examples, but overall it is concise for the complexity.

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

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

Given 3 parameters, no output schema, and the complexity of subscription types and delivery channels, the description covers all essential aspects: purpose, prerequisites, type-specific parameters, delivery options, and limitations. It does not detail the return format beyond stating the subscription id, but this is sufficient for the tool's operation.

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 parameter descriptions, but the tool description adds substantial value by providing type-specific examples (e.g., sec_8k items, polymarket_edge topic) and detailed delivery channel behavior (SMS verification, webhook signing, auto-disable). This greatly aids the agent in constructing correct invocations.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This directly identifies the verb (create) and resource (subscription/alerts), and distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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 context on when to use the tool (proactive monitoring) and lists supported types with examples. It mentions prerequisites (Pipeworx OAuth account) and limitations (anonymous/BYO cannot persist). While it does not explicitly contrast with sibling tools, the inclusion of delivery channels and type-specific details aids in proper selection.

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

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

Annotations already indicate it is read-only, idempotent, and non-destructive. The description adds that it returns category-bucketed example questions with exact tool+argument shapes, which is useful context beyond the annotations.

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

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

The description is front-loaded with purpose and synonyms, then concisely covers parameters, output, and usage. Every sentence adds value without redundancy.

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

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

With no output schema, the description thoroughly explains the return value structure. The single optional parameter is well described. Annotations cover safety. The tool is simple and the description is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by listing example topic values (finance, pharma, etc.) and clarifying omission returns a full spread, providing practical guidance beyond the schema.

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

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

The description clearly identifies the tool as the onboarding entry point that suggests example questions, distinguishing it from answer-oriented siblings like ask_pipeworx. The verb 'suggest' and resource 'questions' 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?

Explicitly recommends using this tool first when unsure of capabilities, provides how to use the optional topic parameter, and references alternative sibling tools such as ask_pipeworx, entity_profile, and compare_entities.

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 a non-destructive, idempotent write. The description adds key behavioral details: ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. This surpasses what annotations convey.

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

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

Two sentences with no unnecessary words. Every sentence adds value: action, ownership, and behavioral consequence. Front-loaded with the core purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers all necessary aspects: what it does, who can use it, what happens to the data, and how it relates to other tools (recent_alerts). No gaps.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The description does not add further meaning to the parameter beyond noting it comes from 'subscribe,' which is helpful but not essential. Baseline score applies.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the action and resource. It implicitly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by naming the opposite operation.

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 guidance on when to use: you can only cancel your own subscriptions (ownership enforcement). It also explains the effect (deactivation, not deletion). No explicit exclusions or alternatives, 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?

Even though annotations already declare readOnlyHint and idempotentHint, the description adds crucial behavioral details: the nuanced meaning of 'could_not_verify' (including verification_error) and 'unsupported', the fact that answers include pipeworx:// citations, and the fallback routing logic. This goes well beyond the annotations and clarifies how the tool behaves in failure and edge cases.

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

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

The description is fairly long but every sentence carries essential information, including examples, path routing, verdict definitions, and error semantics. It is well-structured (definitions, path descriptions, return value summary) and front-loaded with usage signals, though it could be slightly tightened without losing value.

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

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

Despite the lack of an output schema, the description fully explains the return value (verdict types, actual value with citation, reasoning) and the two special verdicts ('could_not_verify' and 'unsupported') with their distinct meanings. For a tool of this complexity, this is a comprehensively self-contained description that leaves little ambiguity 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?

While the schema covers both parameters descriptively, the tool description adds practical semantics: example claims for the 'claim' parameter, and detailed guidance for 'tolerance_pct' including how to set it for hallucination detection (1–2) and the default behavior (implied by wording, capped at 5). This enriches the schema meaning significantly.

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 a specific verb (verify/validate) and resource (natural-language factual claims), and distinguishes this tool from siblings by highlighting its specialized claim-verification role. It even describes two distinct processing paths (structured SEC EDGAR vs. grounded pipeline), making the tool's purpose unambiguous.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides guidance for when to expect the structured path vs. the fallback grounded path. It also notes that it replaces 4–6 sequential calls, signaling efficiency and preference over composing multiple tools.

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