Google_docs

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

The description adds value beyond annotations by disclosing that the tool makes external API calls (to Workers AI and optionally Anthropic) and that the Anthropic calls require a BYO key with direct payment. This supplements the readOnlyHint and idempotentHint annotations.

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

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

The description is concise (four sentences) and well-structured: first sentence states core function, second adds model details, third mentions return format, fourth lists use cases. Every sentence adds value.

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

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

The description covers the tool's input (entity and optional parameters), behavior (probing models, scoring), and output (per-model and combined view). Although there is no output schema, the description adequately describes return fields.

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

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

With 100% schema coverage, the description still adds context: it explains the default model, the role of _apiKey, and the purpose of context for disambiguation. This enriches the schema descriptions without redundancy.

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 probes LLMs for entity visibility and scores it. It uses specific verbs ('Probe', 'score') and distinguishes itself from siblings by focusing on AI visibility scoring for businesses/brands/topics, which is unique among the sibling list.

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

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

The description lists explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). It does not explicitly state when not to use it or mention alternatives, but the context is clear enough 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 indicate read-only, idempotent, and open-world behavior. The description adds value by explaining the internal routing mechanism and the output format (structured answer with stable citation URIs), providing 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 the key preference statement and organized into clear sections (when to use, examples). It is somewhat lengthy due to detailed examples but remains well-structured and informative for an AI agent.

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

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

Given the tool's complexity (routing, many domains) and lack of output schema, the description adequately covers purpose, usage, and output format (structured answer with citations). However, it does not detail the exact structure of the returned data, which slightly 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?

Schema coverage is 100% with clear descriptions for all parameters (all aliases for 'question'). The description reinforces the parameter meaning through examples but does not add significant new semantic information beyond what the schema already provides, meeting the baseline expectation.

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

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

The description clearly states the tool routes questions to thousands of verified sources and returns structured answers with citations. It explicitly distinguishes from web search, making the purpose highly specific and distinct from common alternatives.

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 to prefer this tool over web search for factual queries, lists many supported domains, and gives concrete examples. It covers when to use (e.g., 'what is', 'look up', 'current') and implies when not (non-factual questions), though it lacks direct comparison with sibling tools like ask_pipeworx_grounded.

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?

No contradiction with annotations. Description adds key behavioral details: hallucination-resistance, explicit refusal reasons (not_in_source, no_tool_match, etc.), and extra LLM call cost, which supplements readOnlyHint and idempotentHint.

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?

Structured with purpose, usage, return format, and refusal reasons. Front-loaded, but slightly verbose in listing refusal reasons inline.

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, description fully explains return structure including answer, evidence, confidence, source, fetched_at, and refusal reasons. Covers failure modes 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 coverage 100%, baseline 3. Description mentions alias handling but does not add significant per-parameter meaning beyond schema.

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

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

Description clearly states it's a 'Hallucination-resistant answer mode for high-stakes reads' and extracts answer using only tool result. Distinguishes from sibling ask_pipeworx by noting extra cost and appropriate 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when to prefer sibling: 'prefer ask_pipeworx for casual lookups'.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description goes far beyond by detailing fan-out logic, resolver contract, parent event extraction, news fallbacks, safety short-circuits, wide-spread detection, and resolution-rule risk. 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 quite long but structured with section headings (e.g., RESPONSE SHAPES, RESOLVER CONTRACT). Front-loaded with core purpose and usage. However, the extensive detail may be verbose for quick parsing; could be tightened while retaining completeness.

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 comprehensively covers return shapes (result.market, result.analysis, result.evidence), resolver contract, parent event extraction, news fields, safety mechanisms, and resolution rules. No gaps for such a complex tool.

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

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

Schema has 100% description coverage for 3 parameters. Description adds value: for 'market' explains resolver and match confidence; for 'depth' clarifies quick vs thorough; for 'include_raw' explains response size trade-off. This goes beyond schema basics.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific verb ('Research') and resource ('Polymarket bet'). It distinguishes from siblings like ask_pipeworx (general Q&A) and polymarket_edges (edge-specific) by focusing on pulling evidence and comparison for bet decisions.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides examples of classifier triggers and fan-out behavior. Does not explicitly state when NOT to use, but context implies it's for research before betting, not for general queries.

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 significant behavioral context: what data is pulled for each type (company: latest 10-K financials; drug: FAERS counts, FDA approvals, trial counts), handling of off-calendar fiscal years, and sorting of results by primary metric. No contradictions.

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

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

The description is detailed but efficient, starting with example queries, then usage guidance, then type-specific details, and finally result format. Every sentence adds value, though slightly lengthy—could be tightened without losing clarity.

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

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

Given no output schema, the description explains it returns paired data with citation URIs. It covers all essential aspects for a tool with 2 parameters and clear behavior. No gaps remain for typical use cases.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds extra meaning by specifying that 'values' for company should be tickers/CIKs, for drug names, and that results are sorted by primary metric. This enhances 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 it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with examples like 'compare X and Y' and 'rank these companies'. It distinguishes from sequential lookups, which are sibling tools like entity_profile.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides clear context for when to use and suggests alternatives implicitly through sibling tool names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it returns a structured findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citation, plus explicit gaps[]. It also states facts are pre-verified and never invented, and mentions expected response time of 15-60s. 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 moderately long but highly informative, with no wasted words. It front-loads the core capability and then provides details on behavior, usage, prerequisites, and output. Every sentence adds unique value.

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

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

Given the complexity of the tool (orchestrating research across 3,772 tools and 894 sources), the description covers all necessary aspects: what it does, how it works, output format, prerequisites, limitations, and alternatives. No output schema is present, but the description explains the return structure sufficiently.

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

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

Schema description coverage is 100% with both parameters documented. The description adds value by explaining the depth levels: quick=3, standard=5, thorough=8, and that thorough requires a paid plan. While the schema already describes depth as 'How many facets to research in parallel', the description provides concrete mapping.

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

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

The description clearly states the tool performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to many tools in parallel. It distinguishes itself from sibling 'ask_pipeworx' by specifying that 'deep_research' handles broad or multi-part questions, while 'ask_pipeworx' is for single lookups.

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

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

Explicitly states when to use: 'Use for broad or multi-part questions' and provides an alternative: 'use ask_pipeworx for single lookups'. Also mentions prerequisites (Pipeworx account) and plan limitations for depth parameter.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly. This enriches transparency beyond annotations without contradiction.

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

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

The description is a single paragraph that front-loads the purpose, then lists domains, explains return value, and gives usage advice. Each sentence adds value, though it could be slightly more concise by combining some elements.

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 discovery tool with 6 parameters (1 required), no output schema, and good annotations, the description explains the return format (top-N with schemas) and that no second lookup is needed. It covers the essential context 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 coverage is 100% with descriptions for all 6 parameters. The description adds examples and clarifies aliases for 'query' (task, q, description, search), providing additional context beyond the schema. This is helpful but the schema already does most of the work.

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

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

The description clearly states the tool finds tools by describing data or task, listing many domains like SEC filings, FDA drugs, etc. It distinguishes from siblings by advising 'Call this FIRST when you have many tools', making the purpose specific and actionable.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools'. It provides clear context but lacks explicit when-not or alternative suggestions, which would increase clarity.

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 implies non-idempotent behavior ('add text') but annotation declares idempotentHint: true, creating a contradiction that misleads the agent. Also adds no additional behavioral context beyond purpose.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly concise and structured.

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

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

Adequate for a simple append tool with output schema and annotations, but could mention error scenarios or return value for full 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% with parameter descriptions, so description adds no extra meaning beyond schema. 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 'Add text to the end of a Google Doc', specifying verb and resource, and distinguishes from siblings like docs_insert_text which require insertion position.

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

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

Explicitly states 'Use when insertion position doesn't matter', providing context for when to use. Could be improved by mentioning when not to use, but the contrast with siblings is clear.

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

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

The description states the tool creates a new doc each time, implying non-idempotent behavior. However, the annotation indicates idempotentHint=true, a direct contradiction. Additionally, the description lacks details on permissions, error handling, or limits.

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 brief, to the point, and immediately conveys the essential purpose and return value. 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?

While the tool is simple, the description fails to address the annotation contradiction and omits key behavioral details such as idempotency, potential errors, or side effects. The output schema exists but its contents are not described.

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

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

The schema has full coverage of the single parameter 'title', and the description adds minimal extra context beyond the schema's description. Baseline is appropriate at 3.

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

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

The description clearly states the action (Create), the resource (a new Google Doc), and the outcome (returns document ID). It effectively distinguishes the tool from sibling tools like docs_append_text or docs_get.

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 when to use the tool—when you need to create a new Google Doc. It does not explicitly state when not to use or suggest alternatives, but the context of sibling tools makes it 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=true and destructiveHint=false, covering safety. Description adds return content context but doesn't disclose additional behavioral traits beyond annotations. Adequate but not enriched.

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

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

Two sentences, no wasted words. Front-loaded with verb and resource, then output summary. Highly efficient and easy to parse.

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

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

Given simple schema, comprehensive annotations, and presence of output schema, the description adequately covers what the tool does and returns. Minor gap: no mention of potential errors or limitations, but overall complete for the tool's simplicity.

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

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

Schema coverage is 100% and parameter description 'Document ID (from the URL)' is clear. Tool description does not add further parameter semantics beyond what schema provides, so 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?

Description clearly states specific verb 'Retrieve' and resource 'Google Doc by ID', and lists what is returned (title, body content, document structure), distinguishing it from sibling tools that modify or create docs.

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

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

No guidance on when to use this tool versus alternatives like docs_get_text. Agent must infer usage; explicit when-to-use or when-not-to-use would better support tool selection among siblings.

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

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

The description adds context beyond annotations by specifying the output is plain text without formatting. Annotations already declare readOnlyHint, idempotentHint, etc., but the description fills in the behavioral detail about the nature of the output. It does not cover error cases or limitations, but given the tool's simplicity, it is adequate.

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 short sentences that are highly concise and front-loaded. Every word adds value, with no redundancy or unnecessary details. The description is efficient and instantly understandable.

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, no nested objects, and an output schema (context signals indicate it exists), the description covers all necessary information: what it does, when to use it, and the nature of the output. No gaps identified.

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

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

Schema coverage is 100% with the only parameter 'document_id' described. The description does not add extra parameter information. Baseline score of 3 is appropriate as the schema already covers the parameter semantics adequately.

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

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

Description clearly states the tool extracts plain text from a Google Doc, specifying 'without formatting or structure'. This distinctively separates it from siblings like docs_get which likely returns formatted content. The verb 'extract' is specific and the resource 'Google Doc' is explicit.

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 advises 'Use when you need raw text content only', providing a clear condition for usage. However, it does not explicitly mention when not to use it or contrast with alternative tools like docs_get, though the sibling list includes many docs-related tools. Still, the guideline is useful and contextually relevant.

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 this is a mutation (readOnlyHint=false) and idempotent. The description adds value by explaining the insertion behavior and providing examples, but does not disclose any hidden side effects or requirements 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 a single sentence with an embedded example, front-loading the key information with zero wasted words. It is concise and to the point.

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

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

Given the tool's simplicity, complete schema coverage, and presence of an output schema, the description adequately covers all needed context. No missing information for a reasonable 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 has 100% description coverage for all parameters. The description's examples illustrate usage but do not add new semantic meaning beyond the schema. 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?

The description clearly states the action ('Insert text'), the resource ('at a specific position in a Google Doc'), and provides concrete examples (start, middle). It effectively distinguishes from sibling tools like docs_append_text and docs_replace_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?

The description implies when to use this tool (insert at a specific index rather than appending or replacing) but does not explicitly state alternatives or when not to use it. The examples and mention of 'specific position' provide good context.

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

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

The description contradicts the annotation readOnlyHint=true, as replacing text is a write operation. No additional behavioral details are provided beyond the schema.

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

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

The description is a single, concise sentence with no 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 an output schema, the description lacks completeness for a mutation operation, omitting details about scope (all occurrences) and potential implications.

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 no extra meaning beyond the parameter descriptions 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 it finds and replaces text in a Google Doc, distinguishing it from sibling tools like docs_append_text and 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?

The description implies usage for find-and-replace tasks but provides no explicit guidance on when to use this tool over alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral details: it fans out across multiple sources, notes that USPTO patents API sunset means soft-failure, and lists what data is returned. No contradictions.

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

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

The description is moderately long but well-structured: example queries first, then capabilities, then sources and return fields. Every sentence adds value, but it could be slightly more concise.

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

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

Despite lacking an output schema, the description thoroughly details the return fields (cik, company_name, recent_filings with URIs, fundamentals with specific fields, patents, news, LEI). Covers failure modes (USPTO sunset) and prerequisites.

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% (both parameters documented). The description adds meaning beyond the schema by explaining the type enum (only 'company') and value format (ticker or CIK, with examples), and explicitly states names not supported.

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 starts with concrete example queries ('Tell me about X', 'research Acme') and explicitly states the tool returns 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from sibling tools like resolve_entity by noting when to use this tool vs. others.

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 advises to prefer this tool over chaining individual lookups for holistic views and specifies that names are not supported (use resolve_entity first). This provides clear when-to-use and when-not-to-use guidance.

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

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

The description aligns with annotations (destructiveHint=true) by stating 'Delete' and adds context about clearing sensitive data, though annotations already indicate 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?

Two concise sentences with no wasted words, front-loaded with the core action and usage guidance.

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

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

Given the simple single-parameter tool with annotations, the description fully covers purpose, usage, and behavior without needing more details.

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

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

Schema coverage is 100% and the description does not add additional meaning beyond the schema's 'Memory key to delete'.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'), differentiating 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 provides when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with related tools.

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

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

Annotations already declare safe, read-only, idempotent behavior. The description adds specifics: fetches the page, extracts title/description/key links, and emits standard markdown. This goes beyond annotations by detailing what the tool actually processes and produces.

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

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

The description is two concise sentences plus a bullet-like list of uses. It is front-loaded with the core action and output, then provides context. 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?

Despite no output schema, the description clearly states the output is a 'single text blob ready to drop at site-root/llms.txt' and mentions the standard markdown format. Together with the input schema and annotations, it provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url with example, max_links with default and max). The description does not add new parameter-level detail beyond confirming the extraction of links, 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?

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It explains the process (fetches page, extracts info, outputs markdown) and the output format. No sibling tool does exactly this, so distinction is inherent.

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

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

The description lists three explicit use cases (client site indexing, own project drafting, competitor auditing), providing clear context for when to use. It does not explicitly mention when not to use or alternatives, but given the sibling set, no close alternative exists.

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 false, so safety is clear. The description adds value by specifying the returned fields (id, type, params, etc.) and the default scope (active subscriptions), which goes beyond annotations. No contradictions.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No unnecessary words, information is front-loaded and efficient.

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

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

Given low complexity (one optional parameter, no output schema), the description covers purpose, return fields, and usage guidance. It doesn't explain what subscriptions are, but that is implicit. The presence of sibling tools like subscribe and unsubscribe provides additional context. 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% for the single parameter include_inactive. The description does not add extra meaning beyond the schema description, but the schema itself is sufficient. Baseline 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb (List) and resource (subscriptions), and enumerates return fields. It distinguishes from siblings like subscribe and unsubscribe by explicitly mentioning listing for review before adding or finding an id to cancel.

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

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

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent to use it before subscribe or unsubscribe, providing clear context and 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 indicate non-read-only and non-destructive, which align with sending feedback. The description adds critical behavioral details: rate-limiting, free usage, and that the team reads digests and signal affects roadmap—information not present in annotations.

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

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

The description is compact yet comprehensive. It leads with the core purpose, then provides usage conditions, rate limits, and free status—all in four sentences. No extraneous 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?

For a feedback tool with no output schema, the description covers all necessary details: use cases, context structure, rate limiting, and free usage. It equips an agent to decide correctly when to use this tool vs. alternatives.

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 three parameters are described in the schema (100% coverage). The description adds value by explaining the meaning of each 'type' enum value and clarifying the optional 'context' object structure (pack, tool, vertical). This enriches the schema's basic 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?

The description clearly states the tool's purpose: to send feedback about bugs, missing features, data gaps, or praise. It specifies the exact scenarios (wrong data, missing tool, praise) and distinguishes itself from sibling tools like 'ask_pipeworx' which are for querying, not feedback.

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 tells when to use the tool: for bugs, feature requests, data gaps, or praise. It also advises against pasting end-user prompts, provides rate-limit info (5 per identifier per day), and notes it's free without quota impact.

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

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

Annotations declare safe read-only behavior, but description adds valuable context: data source ('CF analytics-engine'), privacy ('no PII'), caching ('5min-1h depending on window'), and output format ('(pack, tool, count)'). 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?

Two sentences plus a bulleted list. Front-heavy with key action and output. Every sentence adds unique value: purpose, use cases, data source, caching. No redundant or vague language.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully explains what, why, and how data is produced. Covers caching, data source, and privacy. No gaps remain.

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

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

Schema covers the only parameter with enum and description. Description adds nuance about window semantics ('shorter windows surface what's hot right now; longer windows show steady-state demand'). This adds value beyond schema.

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

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

Description clearly states it returns top tools, packs, and call volume over time windows. The verb 'returns' and specific resource ('top tools, top packs, total call volume') make purpose unambiguous. It distinguishes itself from sibling tools like 'discover_tools' by focusing on trending data.

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

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

Explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tool, checking alignment. This provides clear when-to-use guidance. Though it doesn't mention when not to use, the positive guidance is sufficient given the tool's simplicity.

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?

Provides detailed behavior beyond annotations, including walking child markets, checks ordering, partition sum computation, semantic similarity filtering, placeholder filtering, and fill check with explanation of when not to trade. 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 detailed and well-organized, with key information front-loaded (required args). However, it is somewhat verbose and could be slightly more concise, though every sentence adds value.

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

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

Despite no output schema, the description explains the response structure for both modes and covers fill check. Minor gaps: what happens when no opportunities found or error cases. Overall, very thorough given the tool's complexity.

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

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

Schema coverage is 100% with descriptions, and the tool description adds substantial value: explains the meaning of each parameter, gives examples of valid values, and explains the behavior of each mode. This compensates fully for any schema limitations.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes between single-event and cross-event modes. It provides specific examples and contrasts with siblings like polymarket_fill_risk.

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

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

Explicitly states the requirement to provide one of event or topic, gives recommendations for each mode, and provides examples. Includes constraints like Jaccard similarity threshold and partition filter, and references another tool for sizing.

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

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

Extensive disclosure of response structure (by_segment with three segments), edge calculation details, caching, tradeable-edge filters, and diagnostics. Adds significant context beyond annotations which already indicate read-only and idempotent.

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

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

Long but well-structured with logical sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). Every sentence adds value; no fluff. Front-loaded with 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?

Comprehensive for a complex tool with 9 parameters, no output schema. Covers response segments, edge calculation, knob usage, caching, and diagnostics for empty results. 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 good descriptions. Tool description adds extra context by explaining how knobs work together as filters (e.g., 'Tradeable-edge filter') and their interaction. Adds value beyond schema.

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

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

Clearly states it scans Polymarket markets for opportunities based on Pipeworx data disagreement with market price. Built for 'what to bet on today'. However, does not explicitly distinguish from sibling tools like polymarket_arbitrage or polymarket_kalshi_spread.

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 context: discovers opportunities without paging. Includes knobs like min_liquidity and max_spread_pp for filtering. But lacks explicit 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 read-only, idempotent, and non-destructive behavior. The description adds significant context: history depth bounded by 60-day TTL, snapshots written on cache-miss, decay computed from daily closes (not intraday). 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 thorough but not overly verbose. It front-loads the core purpose and then details response structure and limitations. Some redundancy could be trimmed, but every sentence serves a purpose.

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

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

Given no output schema, the description fully explains the response format (tracked, expired, snapshot_dates) and key fields. It also covers limitations and data sources. The tool is simple (2 optional params) and the description leaves no ambiguity.

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 'days' as lookback (default 14) and 'window' as snapshot family with default '1wk', plus clarifying the clamp range (2-30) and options (24hr, 1wk, 1mo). This is helpful context beyond schema descriptions.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It answers the specific question of how long an edge has existed and if it is shrinking. This distinguishes it from siblings like 'polymarket_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 when to use the tool (to assess edge persistence and decay) by contrasting a fresh wide edge with a 3-week-old wide edge. It does not explicitly state exclusions or alternatives, but the context is clear enough.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals that the tool walks the order-book ladder, returns fill quality metrics (slippage, shares filled), verdicts (clean/degraded/cannot_fill), and basket-specific details (thin legs, forced directional risk). It fully describes the behavior without contradiction.

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

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

The description is well-organized with clear sections for single-market and basket modes, and front-loaded with the core purpose. While slightly lengthy, every sentence serves a purpose given the tool's complexity. Could be slightly more concise but still effective.

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

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

Despite lacking an output schema, the description thoroughly covers all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp for single-market; theoretical_sum, realizable_sum, capture_ratio, thin_legs for basket). It also addresses edge cases and usage constraints, leaving no gaps for an AI 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?

With 100% schema coverage, baseline is 3, but the description adds significant context: mutual exclusivity of market/event, mode-specific interpretation of side and size_usd (spend vs. target proceeds for single-market; settlement notional for basket), and default behaviors. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check using live order book depth, explicitly distinguishes between single-market and basket modes, and lists return fields. It differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on feasibility and risk assessment.

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 instructs to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains the risk of partial fills converting arb into unhedged directional positions, providing clear when-to-use and why.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: it discloses the safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) and explains edge cases like non-equivalent bet shapes and temporal misalignment. It goes far beyond what annotations provide, making the tool's complex behavior fully transparent.

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

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

The description is relatively long but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence adds necessary information for a complex tool. It could be slightly tighter, but the detail is justified.

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 (3 parameters, no output schema), the description fully covers what the agent needs: input modes, response structure (leg-by-leg prices, spread array), safety fields, and edge-case handling. It explains compatibility_warning cases and temporal_alignment, ensuring the agent can interpret results correctly.

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

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

Schema coverage is 100% with descriptions for each property. The description adds value by explaining the two modes, giving examples for 'topic' (e.g., 'fed', 'btc'), and clarifying that explicit parameters override the topic mapping. It enriches the parameter meaning without being redundant.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs like 'compute' and 'compare' implicitly, and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue spread. The purpose is precise 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 extensive guidance on when to use each mode (topic shortcuts vs explicit tickers), explains two modes, and includes warnings about compatibility and temporal alignment. It also cautions that real spreads are rare and pre-mapped topics often return warnings. This gives the agent clear context for selection and invocation.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds scoping detail (identifier-based) and that omitting key lists all keys, supplementing annotations without contradiction.

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

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

Three sentences, front-loaded with primary action, no redundant phrases. Every sentence adds value.

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

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

For a simple retrieval tool with one parameter, rich annotations, and no output schema, the description covers purpose, usage context, scoping, and relationships fully.

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

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

Schema description coverage is 100%, and the parameter description already explains omission lists all keys. The description reinforces but does not add significant new meaning beyond the schema.

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

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

Description clearly states the tool retrieves a value saved via remember, or lists all keys if no key argument. Specific verb and resource, and distinguishes from its sibling tools remember and forget.

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

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

Provides specific use cases (e.g., retrieving user's target ticker, address, research notes) and mentions pairing with remember and forget. Lacks explicit when-not-to-use guidance but is clear for a simple retrieval 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about the mark_read side-effect (flags events as read so next call shows newer ones) and clarifies what the returned alerts carry. 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 a single paragraph of about 100 words, front-loaded with the primary purpose. Every sentence adds value without redundancy. It efficiently covers return fields, filtering, mark_read behavior, and an alternative access method.

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 adequately hints at return structure (source, citation_uri, raw event payload). It mentions pagination via limit and mark_read state tracking. However, it does not specify if there is cursor-based pagination or whether all events are returned in one call, which would be helpful for complete understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the mark_read parameter's effect ('flag returned events read so the next call only shows newer ones') and provides an example for type ('sec_8k'). This adds value over just the schema definitions.

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

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

The description opens with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly states the tool returns recent alerts with fields like source, citation_uri, and raw event payload. This distinguishes it from sibling tools like subscribe or list_subscriptions, which serve different purposes.

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

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

The description provides clear context: 'Polls work fine' and mentions an alternative API endpoint for scripts and dashboards. However, it does not explicitly state when to use this tool over a sibling or when not to use it, so it loses a point for lacking exclusion criteria.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details fan-out strategy, fallbacks (GDELT→GNews), and soft-fail for USPTO, providing rich behavioral context.

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

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

Efficient single paragraph: leads with examples, then sources, parameter details, and alternative tool. No redundancy.

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

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

Given no output schema, the description explains return structure (changes[], total_changes, URIs) and fallback behavior. Covers all needed aspects for a retrieval tool.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining 'since' accepts ISO or relative, and 'value' can be ticker or CIK, but does not add much beyond schema for 'type'.

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

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

The description clearly states the tool provides a change feed for a company over a recent time window, using multiple sources. It distinguishes from sibling 'entity_profile' by noting the alternative for static profiles.

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

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

Explicit usage examples like 'What's new with X' are given, along with when-not-to-use guidance by recommending 'entity_profile' for static profiles.

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 context beyond annotations: persistence scoping (authenticated vs anonymous), key-value storage, idempotent overwrite. 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?

Compact yet comprehensive: purpose, usage, technical details all in 3-4 sentences with 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?

Covers purpose, usage, persistence details, and links to related tools. Missing explicit return behavior but minor for a simple write tool.

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

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

Schema coverage is 100% with descriptions; description adds examples for key format and clarifies value as any text, enhancing understanding beyond schema.

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

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

Clearly states the tool saves data for later reuse across conversations/sessions, distinguishes from siblings recall and forget with specific verbs and examples.

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

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

Explicitly says when to use ('discover something worth carrying forward'), provides examples, and notes pairing with recall/forget. Lacks explicit 'when not to use' but it's strongly implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' It also details what each type returns (e.g., company: ticker, CIK, company name, citation URI). 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 detailed but well-structured, starting with query examples and then listing supported types. It is front-loaded with the most important information. While a bit verbose, every sentence earns its place by providing necessary context. Could be slightly more concise, but overall good.

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, internal cascading), the description is fully complete. It explains what each type returns (including citation URIs), covers both parameters, and aligns with annotations. There is no output schema, but the description compensates by listing return fields. No missing information for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description adds significant context beyond the schema's parameter descriptions: for the 'value' parameter, it gives examples (ticker, CIK, name for company; brand or generic name for drug) and explains accepted input formats. This adds real value for the agent.

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 starts with example queries like 'What's the ticker for...' and clearly states the tool resolves names to canonical identifiers. It explicitly distinguishes from sibling tools by noting that this is the first step when an ID is needed, and it lists supported entity types (company, drug) with details on what they return.

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 says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It does not explicitly state when not to use it or suggest alternatives, but the context implies that if an ID is already known, this tool may not be needed. Siblings like entity_profile could be used after, but this is not explicit.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check and returns specific fields (score, confidence, signal density). Does not mention API key requirement for Anthropic model, which is in schema but not description.

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

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

Two sentences, no fluff. First sentence states core action, second gives use case and output. Front-loaded and efficient.

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

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

Covers purpose, usage, output format, and underlying mechanism. Without output schema, description adequately describes return columns. Could mention minimum entity count (2) but schema implies it.

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

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

Schema coverage is 100% with descriptions. Description adds value by explaining that first entity is treated as subject and that returns ranked list with score, confidence, signal density. This exceeds baseline of 3.

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

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

The description clearly states it compares AI visibility across multiple entities, ranks them, and returns a ranked list. It distinguishes from sibling 'ai_visibility_check' by focusing on multi-entity comparison.

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

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

Explicitly mentions the use case (competitive AI-marketing audits) and provides an example question. While it doesn't directly compare to siblings, the context is clear; could explicitly note 'use instead of ai_visibility_check for multiple 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 already declare readOnlyHint, idempotentHint, destructiveHint=false. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 a single paragraph but relatively long. It front-loads the main purpose and every sentence adds value (purpose, usage, return format, error behavior). Could be slightly more compact but still effective.

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

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

No output schema, so description fully explains return values: summary block fields, per-advisory detail, links, and alternative versions. Also covers gracefull degradation and timeout behavior. Complete given the tool's complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds value beyond schema: clarifies that scoped packages are accepted and that version defaults to latest. This extra context justifies a score above baseline.

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

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

The description clearly states the tool's purpose: a composite check for evaluating whether to add an npm package, fanning out across deps.dev and bundlephobia for license, advisories, version history, bundle size, etc. It distinguishes itself from sibling tools (no similar scan_* tools) and includes a specific verb+resource combination.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also states ecosystem limitation: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear when-to-use and when-not-to-use with alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds rich behavioral details: BGE-base-en embeddings, 500-char windows, cosine similarity, 200K char limit with truncation flag, and offsets for verification. 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?

Efficiently structured: front-loads purpose, then usage guidance, then behavioral details. Every sentence adds value. No 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?

No output schema, but description explains return values (top-N passages with offsets and scores). Also covers pairing with other tools, which is valuable context. Complete for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value beyond schema: explains 'text' maximum length with truncation, provides example queries for 'query', and clarifies default and range for 'limit'.

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 performs semantic search inside a fetched record, specifying the resource (record text) and action (search within). It distinguishes itself from sibling 'ask_pipeworx_grounded' by describing how they pair together.

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

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

Explicitly says when to use: when the record is too large to fit in the prompt. Mentions an alternative (ask_pipeworx_grounded) and explains how to combine tools. No ambiguity.

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

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

The description adds behavioral context beyond annotations, including auth requirements, rate limits (SMS 10/day), webhook signing secret delivery, and auto-disable after failures. Annotations indicate idempotent and non-destructive, which aligns.

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 well-structured and front-loaded with purpose. It is somewhat lengthy but every sentence provides necessary detail, balancing conciseness with completeness.

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 (nested params, multiple types, output schema absent), the description covers all essential aspects: supported types, parameter examples, delivery options with constraints, auth requirements, and return value.

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

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

Schema coverage is 100%, but the description adds value by providing concrete examples for each type and delivery channel, explaining parameter constraints such as phone verification and webhook signing.

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

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

The description clearly states the verb 'Create', the resource 'proactive monitoring subscription', and lists specific supported types and delivery channels. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on subscription creation.

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 when-to-use guidance by describing the creation of subscriptions for live-data event streams. It mentions use of 'recent_alerts' for pulling the feed, but does not explicitly contrast with alternatives 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, openWorldHint, idempotentHint, and destructiveHint. The description adds value beyond these: it discloses that the tool returns category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog. No contradictions with annotations.

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

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

The description is front-loaded with trigger phrases. Each sentence serves a purpose: purpose, output details, parameter guidance, and usage context. It is appropriately sized for the complexity; slightly verbose but not wasteful.

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

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

Given the simple input schema (one optional parameter) and no output schema, the description covers all necessary aspects: purpose, usage context, parameter details, behavioral traits, and output structure. It feels complete for an onboarding tool.

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

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

Schema coverage is 100% (one optional parameter with description). The description adds concrete examples of valid topic values (finance, pharma, etc.) and explains the behavior difference when omitting the parameter (full spread vs. focused). This goes beyond the schema alone.

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

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

The description uses specific verbs ('suggests', 'returns') and clearly defines the resource (example questions about Pipeworx). It distinguishes from siblings by positioning itself as the first-step onboarding tool, mentioning meta-tools like ask_pipeworx. The list of trigger phrases makes the purpose unmistakable.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also gives usage patterns (call with no arguments or pass a topic). Lacks explicit 'when not to use' but the guidance is clear enough.

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

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

Annotations indicate non-read, open-world, idempotent, non-destructive. Description adds that the row is deactivated, not deleted, and historical events remain available via 'recent_alerts'. No contradictions with annotations.

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

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

Two sentences convey all necessary information: action, parameter, ownership constraint, and behavioral nuance. No superfluous text.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, and side effects completely. No gaps remain.

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 for the single 'id' parameter with a description. The tool description does not add additional semantic information beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and the deactivation behavior.

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

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

Explicitly states that ownership is enforced (only cancel own subscriptions) and explains the deactivation vs deletion difference. Does not explicitly mention alternatives, but the sibling context suggests using 'list_subscriptions' to find IDs.

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, openWorldHint=true. The description adds that it returns verdict types (confirmed, approximately_correct, etc.), extracted structured form, actual value with citation, and percent delta. It also notes it replaces 4-6 sequential calls.

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

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

Front-loaded with trigger phrases for quick identification. The description is thorough but not overly verbose; every sentence adds useful context.

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 explains the verdict options, output structure, data source, and scope. It addresses the tool's complexity and limitations 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 coverage is 100% for the single parameter 'claim', which has its own description. The description adds value by specifying supported claim types (company-financial) and providing example formats.

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 verifies natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. It distinguishes itself from sibling tools like deep_research or ask_pipeworx by focusing on fact-checking.

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 the agent needs to check whether something a user said is factually correct' and provides trigger phrases. It scopes to company-financial claims but doesn't explicitly state when not to use it.

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