Quotes

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable context: it probes LLMs, returns per-model data, and explains the _apiKey parameter's role in calling Anthropic with user-paid charges. 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 coherent paragraph that efficiently conveys purpose, usage, and output. Each sentence adds value, though it could be slightly more structured with bullet points.

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 explains the output format (per-model score, confidence, signals, raw_response + combined view) and provides use cases. With no output schema, this level of detail is adequate for an agent to understand what the tool returns.

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 schema by noting the default model (Workers AI) and that _apiKey is only needed for Anthropic, implying cost implications. It also clarifies the entity parameter's purpose.

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 brand/product visibility and scores it 0-100 per model. It uses a specific verb ('probe') and resource ('LLMs'), and distinguishes itself from siblings like 'deep_research' or 'scan_competitor_ai_presence' by focusing on visibility scoring.

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 use cases such as AI-marketing audits and pre-launch brand checks but does not explicitly state when not to use this tool or suggest alternatives. It implies usage context but lacks exclusionary guidance.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds context: routes to 4,774 tools, returns structured answer with citation URIs, works on all tiers with one fast call. 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 comprehensive but about 150 words, slightly verbose. However, it is front-loaded with the key directive 'PREFER OVER WEB SEARCH', includes examples and alternatives, and 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 tool with 6 params (only 1 required) and no output schema, the description covers capabilities, usage context, alternatives, and provides examples. It mentions structured answer with citation URIs, which is sufficient without output schema.

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

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

Schema coverage is 100% (all parameters described). Description clarifies multiple aliases (q, text, input, etc.) and states 'Your question or request in natural language', adding 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?

The description clearly states the tool answers factual questions about current/historical data from many sources. It lists specific domains (SEC, FDA, etc.) and contrasts with web search. It distinguishes from siblings ask_pipeworx_grounded and deep_research, making purpose unambiguous.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It provides when-to-use with examples ('what is', 'look up', etc.) and step-up alternatives for when to use other tools, giving clear guidance.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant value beyond annotations: it explains the extra LLM call cost, the routing mechanism ('picks the right tool from 4,774 across 1242 sources'), the refusal reasons, and the return format. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. Every sentence adds value: purpose, mechanism, return format, refusal reasons, usage guidance, and cost tradeoff. Despite length, it is efficiently written 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?

Despite no output schema, the description fully details the return format (answer, evidence, confidence, source, etc.) and refusal reasons. It explains the tool's behavior in selecting tools, fetching data, and extracting answers. Complexities like cost and use cases are covered comprehensively.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'Your question in natural language' but adds no semantic detail beyond what the schema already provides via the 'question' property and its aliases. No additional syntax or constraints are given.

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 precisely states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from its sibling 'ask_pipeworx' by specifying that it extracts answers only from tool results, providing refusals when data doesn't directly answer.

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 when to use the tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also advises preferring 'ask_pipeworx for casual lookups,' providing clear guidance on tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds significant behavioral detail beyond that. It explains the resolver contract (match confidence, alternatives), parent event extraction, news fallback fields, safety mechanisms (low-confidence match blocking), and resolution-rule risk analysis. This fully discloses the tool's behavior.

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

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

The description is very long and detailed, using section headings like 'RESOLVER CONTRACT' and 'NEWS FIELDS'. While comprehensive, it could be more concise; some sentences are verbose and could be trimmed without losing meaning.

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

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

Given the tool's complexity (no output schema), the description thoroughly explains return values (result.market, result.analysis, result.evidence) and covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules. It provides complete 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 description coverage is 100%, so baseline is 3. The description adds value by explaining how to use the market parameter (slug, URL, question text) with examples, and provides context for depth and include_raw parameters beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison), and distinguishes from sibling tools 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 explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples and fan-out patterns but does not explicitly mention when not to use or alternatives, which would elevate it to a 5.

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

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

The description discloses the four possible verdicts and their implications (e.g., 'verified' includes a citation, 'paraphrase_of_verified' returns actual text). Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds meaningful behavioral context beyond the 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 two sentences long, front-loading the core functionality in the first sentence. Every word adds value; there is no fluff or repetition of schema information.

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

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

Given the simple tool with only two parameters, full schema coverage, and an existing output schema, the description adequately covers the tool's behavior and use cases. It explains the verdict categories and their implications without needing to detail return values.

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

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

The description explains how the two parameters (text and claimed_author) are used to produce the verdict, adding context beyond the schema's parameter descriptions. The schema coverage is 100%, but the description ties the parameters to the tool's logic, improving usability.

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: given a quote and optional claimed author, return one of four specific verdicts. It distinguishes itself from siblings like 'search_quotes' or 'validate_claim' by focusing solely on quote attribution, and it names the exact verdict categories with their meanings.

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

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

The description mentions 'useful for journalists, researchers, and anyone tired of fake Mark Twain quotes,' which gives context but does not explicitly state when to use this tool versus alternatives (e.g., sibling tools like 'validate_claim' or 'search_quotes'). No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds rich detail: for 'company' it pulls latest 10-K financials from SEC EDGAR/XBRL with proper fiscal year handling, and for 'drug' it pulls FAERS, FDA approval counts, and trial counts. It also states results are sorted by primary metric and include citation URIs.

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

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

The description is dense but well-structured, starting with example queries and usage guidance, then detailing data sources for each type. Every sentence adds value; it is not overly verbose. Slightly longer than necessary but still 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 the complexity (two entity types, multiple data sources, no output schema), the description covers the key aspects: data sources, sorting, citation URIs, and special handling of fiscal years. It does not detail exact output format but provides sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds value by explaining what data each entity type retrieves and the sorting behavior, going beyond the schema's enum and string descriptions.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs, provides example queries, and distinguishes it from sequential single-pack lookups (e.g., entity_profile). The verb 'compare' and resource 'entities' are clear and specific.

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

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

The description includes a strong recommendation ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and gives concrete query examples. It does not explicitly state when not to use it (e.g., for a single entity), but the context makes the use case 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?

Beyond annotations (readOnly, openWorld, idempotent), the description details the parallel decomposition, output format (findings packet with evidence, confidence, source, gaps), and expected 15-60s response time. 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 somewhat lengthy. However, every sentence adds value, and key information (account requirement, alternatives) is front-loaded. Minor conciseness improvement possible.

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

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

Despite no output schema, the description fully explains return values (findings packet, gaps[], citations) and covers usage, behavior, parameters, and expected duration. Complete for 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 coverage is 100%, and the description adds meaning: explains depth values (quick=3, standard=5, thorough=8) and that the question can be broad/multi-part. Also links depth to account tiers.

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' across Pipeworx's structured data sources, distinguishing it from sibling tools like ask_pipeworx. It includes specific verb ('research') and resource ('1242 STRUCTURED data sources').

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

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

Explicitly tells when to use this tool (broad/multi-part questions over structured data) and when not to (single lookup or breaking news, recommending ask_pipeworx instead). Also notes account requirements and that 'thorough' depth needs a paid plan.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds that it returns top-N relevant tools with full schemas, consistent with 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?

Front-loaded with core purpose, lists domains, explains return value. Slightly verbose with alias repetition but overall efficient and informative.

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

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

No output schema, but description adequately explains return type (tool names, descriptions, schemas). Covers key usage scenarios and constraints. Sufficient for a discovery 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 100% with aliases and descriptions. Description reinforces natural language usage with examples but doesn't add significant meaning beyond schema.

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

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

Clearly states the tool finds tools by describing data/task, with specific domain examples and explanation that it returns ready-to-call results. Distinct from sibling tools like search_quotes.

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

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

Explicitly says call this first when many tools are available to see options. Provides strong contextual guidance, though doesn't enumerate all when-not-to-use scenarios.

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

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

Discloses key behaviors beyond annotations: highlights the USPTO PatentsView API sunset (soft-fail), describes the fan-out across multiple APIs, and details the return structure (e.g., up to 5 filings, latest fundamentals). No contradictions with annotations (readOnlyHint, idempotentHint are consistent).

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

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

The description is a single dense paragraph but is front-loaded with examples and key information. While it could be slightly better organized (e.g., bullet points), it avoids unnecessary words and efficiently conveys all essential details.

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

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

Given the tool's complexity (multiple data sources, fallback mechanisms, specific output fields), the description covers all critical aspects: sources, return values, limitations (soft-fail, name unsupported), and input format. No output schema exists, but the description compensates by listing 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?

Schema coverage is 100%, but the description adds important context: type is restricted to 'company', value must be ticker or zero-padded CIK, and names are unsupported. This adds meaning beyond the schema's basic 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 precisely states the tool's purpose: a single-call holistic profile of a US public company from multiple sources. It includes specific examples (e.g., 'Tell me about X', 'brief me on Tesla') and lists the data sources (SEC, XBRL, USPTO, news, GLEIF) and output fields, clearly differentiating it from related tools like resolve_entity.

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

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

Explicitly recommends using this tool over chaining individual lookups for holistic views. Specifies acceptable inputs (ticker or CIK) and explicitly states that names are not supported, directing users to resolve_entity first. 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?

Annotations already indicate destructiveHint=true and idempotentHint=true. Description confirms destruction but adds no further behavioral details (e.g., whether deletion is permanent, affects related entries). Does not contradict annotations.

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

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

Two efficient sentences: first states purpose, second provides usage guidance. No wasted words, front-loaded with critical 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 simple 1-parameter destructive tool with annotations, the description covers purpose and usage. However, it does not describe the return value or confirm success/failure behavior, which would be helpful given no output schema.

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

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

Schema coverage is 100% and already describes the 'key' parameter as 'Memory key to delete'. Description does not add extra meaning beyond the schema, so baseline of 3 is appropriate.

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

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

Clearly states 'Delete a previously stored memory by key,' specifying the verb (delete) and resource (memory). Distinguishes from siblings 'remember' and 'recall' which are for storage and retrieval respectively.

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 context is stale, task is done, or to clear sensitive data. Also mentions pairing with 'remember' and 'recall', guiding the agent on 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, and non-destructive behaviors. The description adds context by explaining the extraction process (fetches page, extracts title/description/links) and output format (single text blob ready for site-root). This is consistent and provides additional transparency beyond annotations.

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

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

The description is concise and front-loaded with the main purpose. It uses two clear sentences followed by a short list of use cases. No superfluous text; every sentence adds value.

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

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

Given the simple tool (2 params, no output schema, clear annotations), the description covers the purpose, process, and output format adequately. The 'Useful for' section adds context, and the output description ('single text blob') suffices without requiring an output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter-level semantics beyond what the schema provides; the 'url' and 'max_links' descriptions are essentially duplicated. The tool-level description gives context but not parameter-specific details.

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

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

The description clearly specifies the verb 'generate', the resource 'llms.txt file', and the context 'for any URL so AI crawlers can index the site cleanly'. It distinguishes itself from sibling tools by focusing on a specific output format and use case. The 'Useful for' section further clarifies the intended tasks.

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

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

The description provides explicit use cases (e.g., getting client site indexed, drafting for own project, auditing competitors) that guide when to use this tool. However, it does not explicitly state when not to use it or mention alternatives, keeping it from a 5.

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

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

The description adds value beyond annotations by specifying the output structure: 'containing nested scenes with their speeches and lines.' Annotations already indicate read-only, idempotent, non-destructive behavior; the description confirms and details the return format.

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

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

The description is extremely concise, consisting of two meaningful sentences that cover purpose and usage. No redundant or unnecessary information.

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

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

Given the tool's simplicity, annotations, output schema, and description, all necessary information is provided. The description explains what the tool returns and when to use it, leaving 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%, and each parameter is described in the schema. The description does not add further parameter detail beyond restating the use case. Per rules, baseline 3 is appropriate.

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

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

The description clearly states the tool returns the full text of an entire act including all scenes, distinguishing it from sibling tools like get_scene. The verb 'Return' and resource 'full text of an entire act' make the purpose 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 to use this tool to read a full structural unit at once, providing clear context. While it doesn't explicitly state when not to use it or mention alternatives, the sibling tools (e.g., get_scene) implicitly differentiate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns the full text in order and gives an example with specific content, but does not cover error conditions or edge cases. No contradiction.

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

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

Two sentences: one describing the primary function with a concrete example, and one recommending a prerequisite tool. No unnecessary words, front-loaded with key information.

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

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

Given the read-only nature, rich annotations, and existence of an output schema, the description is complete: it explains what the tool does, how to use it, and how to discover applicable works.

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

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

Schema coverage is 100%, so the baseline is 3. The description provides illustrative examples and links to a companion tool, but does not add detailed field-level semantics 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?

Clearly states it returns the full text of a chapter from a novel/prose work, with an example and specification of structure (all paragraphs in order). Distinguishes from siblings like get_act (for plays) by specifying 'novel/prose work'.

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

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

Explicitly recommends using list_full_text_works to discover chapter-based works, which provides clear context for when to use this tool. Does not directly exclude alternatives for plays, but the context of siblings and the description's focus on prose works is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable details: returns 'every speech, every line, in order', and gives a concrete example. 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 two sentences plus an example, all front-loaded. The first sentence immediately conveys the core function, and every part serves a purpose without redundancy.

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

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

Given the presence of an output schema and comprehensive annotations, the description appropriately explains what the tool returns and how to use it. No missing context for a simple retrieval tool.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description does not add new parameter semantics but provides examples illustrating valid values (e.g., author_id='william-shakespeare'), which aids understanding beyond the schema.

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

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

The description clearly states it returns the full text of a specific scene, using a specific verb ('Return') and resource ('scene from a play'). It provides an explicit example ('To be, or not to be'), and distinguishes from sibling tools like get_act and get_chapter by specifying scope.

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

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

The description mentions use cases ('context, citation, or close reading') but does not explicitly state when not to use it or recommend alternatives. However, the purpose is clear and examples guide proper 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 provide readOnlyHint, idempotentHint, etc. The description adds that it returns 'all authors' (scope) and enumerates the fields. No contradictions; it complements annotations with useful detail.

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

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

Single sentence front-loads the main action and then lists details efficiently. No wasted words.

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

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

Despite having an output schema, the description summarizes the return fields and highlights the author ID's cross-tool utility. For a simple tool, this is fully complete.

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

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

No parameters exist, so schema coverage is 100%. The description does not need to add parameter info, but it correctly omits irrelevant details. Baseline for zero parameters is 4.

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 'Return' and resource 'all authors available in the corpus', and specifies the fields in each entry. It differentiates from siblings by focusing on authors vs other entities like works or quotes.

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 when you need author info or IDs for other tools, but does not explicitly state when not to use or compare to alternatives. However, given zero parameters and a clear purpose, usage is intuitive.

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 safety hints (readOnly, idempotent, not destructive). The description adds behavioral context about what 'full text' means and the tool's role in a workflow, which is valuable 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, no wasted words. Front-loaded with purpose and value. Every sentence earns its place.

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

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

Given no parameters, rich annotations, and existing output schema, the description is fully complete. It explains the tool's purpose, why it exists, and how to use it in conjunction with other tools.

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

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

No parameters exist, and schema coverage is 100%. The description does not need to add parameter semantics. Baseline of 4 is appropriate for zero-parameter tools, and the description provides sufficient context about the tool's output.

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

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

The description clearly states the tool lists works with full text loaded, distinguishing it from sibling tools like search_quotes (excerpts) and get_scene/get_act (deep lookup). Verb 'list' and resource 'full text works' are specific.

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

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

Explicitly says to use this to discover what is available for deep structural lookup via get_scene and get_act, providing clear context for when to use this tool. Does not explicitly state when not to use, but the contrast with 'famous-quote excerpts' implies 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 and non-destructive. Description adds that only active subscriptions are returned by default and lists specific return fields, providing additional 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?

Two concise sentences: first defines action and return values, second gives usage guidance. No wasted words.

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

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

For a simple list tool with one optional parameter and comprehensive annotations, the description covers purpose, return format, and usage context. No output schema, but return fields are listed.

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%. Description implies default filtering (active only) which aligns with the 'include_inactive' parameter, adding meaning beyond schema.

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

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

Clearly states the action (List) and resource (the caller's active subscriptions) and distinguishes from sibling tools subscribe and unsubscribe. Also specifies return fields.

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

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

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

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

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

Annotations indicate this tool is not read-only (writes feedback) and not destructive. The description adds important context: rate-limited to 5 per identifier per day, free, doesn't count against quota. No contradictions.

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

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

The description is a single paragraph but well-front-loaded, stating purpose first, then usage cases, then important constraints. Could be slightly more concise, but every sentence adds value.

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

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

For a feedback tool with three parameters (type, context, message), the description covers usage and constraints. Missing detail about response or success/failure indication, but that's acceptable given the tool's nature.

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 parameters are well-documented. The description reiterates the enum options briefly and adds behavioral notes (rate limits) but doesn't add significant semantic value beyond the schema.

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

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

The description clearly states it sends feedback to the Pipeworx team, listing specific feedback types (bug, feature, data_gap, praise). It distinguishes from all sibling tools, which are unrelated analytical or retrieval tools.

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

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

Explicitly describes when to use each feedback type: bug for wrong/stale data, feature/data_gap for missing tools or data, praise for good experiences. Lacks explicit 'when not to use' guidance, but coverage is clear.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds important context: source (CF analytics-engine), no PII, caching window (5min-1h), and self-aggregating nature. No contradiction.

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

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

Four sentences, well-organized: first sentence states purpose, second lists use cases, third adds technical context, fourth notes caching. No wasted words, front-loaded.

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

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

For a read-only tool with one parameter and no output schema, the description completely explains what it returns and caching behavior. 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?

Only parameter 'window' has 100% schema coverage. Description enhances it by explaining the tradeoff between shorter windows (hot right now) and longer windows (steady-state demand). 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 the tool returns top tools, packs, and total call volume over a window. Distinguishes itself from siblings by focusing on trending data, unlike other tools for queries, research, or alerts.

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

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

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, seeing use case alignment). Also explains window length tradeoffs. Does not explicitly mention when not to use, but the use cases cover common scenarios.

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, etc.), the description details internal logic: monotonicity checks, partition_sum, Jaccard similarity filter, partition filter, fill check against live depth. It warns that realizable_edge_pp ≤ 0 means the trade should not be executed. This adds significant behavioral context.

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

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

The description is thorough but somewhat lengthy. It is well-structured with a clear introduction, mode explanations, and details on filters and output. While every sentence adds value, some details could be slightly condensed without loss of 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 the tool's complexity (multiple modes, filters, fill-check) and no output schema, the description covers all necessary aspects: input usage, internal checks, output fields (opportunities[], partition_check, fill check results), and edge cases (low similarity, placeholder filters, thin legs). It is comprehensive.

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

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

The description enriches the schema's parameter descriptions with concrete examples (e.g., 'fed-decision-may-2026'), explains the behavioral difference between event and topic modes, and details the semantic anchor and partition filter conditions. Schema coverage is 100%, yet the description adds substantial meaning.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three modes (trending_scan, event, topic) and distinguishes from siblings like polymarket_fill_risk and polymarket_edges by mentioning custom sizing and fill-check details.

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

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

Explicitly tells when to use each mode: no args for trending_scan, event for a specific market (recommended), topic for cross-event scanning. Also states when not to use it for sizing ('For custom sizing use polymarket_fill_risk'), providing clear 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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds extensive behavioral context: data sources (FRED, GDELT), caching policy (1h KV), edge calculation details, slippage assumptions, and diagnostics for empty segments. 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 very detailed and structured with segments, but it is overly verbose. The first sentence front-loads the purpose, but many technical details could be summarized more concisely.

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 no output schema, the description thoroughly explains the return structure (by_segment, fed_note, diagnostics) and covers all parameter contexts. Given the complexity (9 params, detailed logic), the description is complete and leaves no major 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%, so baseline is 3. The description adds meaningful context beyond schema descriptions, e.g., explaining that min_liquidity avoids walking the book past breakeven and that min_partition_leg_kelly applies to per-leg Kelly inside partitions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market prices. It differentiates from siblings by focusing on edge detection and provides detailed segmentation (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT).

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

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

The description explicitly frames the tool as 'what should I bet on today' and explains how agents can discover opportunities without paging. It details tradeable-edge knobs but does not directly compare with sibling tools like polymarket_arbitrage, leaving some ambiguity on when to use this vs 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 declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds significant behavioral context: it reads snapshots, returns time-series, trend, decay, expired opportunities, and snapshot dates. It explains that decay numbers come from daily closes. 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 front-loaded with the core purpose. It follows a logical structure: purpose, what it answers, response structure, limits. Every sentence adds value, though it is somewhat lengthy. Could be slightly more concise.

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

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

Given the complexity (time-series, decay, snapshots) and no output schema, the description covers input parameters, response fields (tracked, expired, snapshot_dates), semantics (edge_pp_net, trend, decay_pp_per_day, lifespan_days), and limits. It is sufficient for an AI 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?

Input schema covers 2 parameters with descriptions and default values. The description adds context: 'days' default 14, max 30 (schema says clamp 2-30); 'window' default '1wk' with explanation as 'snapshot family'. This enhances 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?

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates by emphasizing that a fresh wide edge and a 3-week-old one are different trades, indicating use case distinction from sibling tools like polymarket_edges.

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

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

The description provides a clear use case ('Answers how long has this edge existed and is it shrinking?') and includes an example contrasting fresh vs old edges. It also mentions limits (60-day snapshot TTL, snapshot start). However, it does not explicitly state when not to use this tool or list alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe read operation. The description adds behavioral details: it walks the order book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, and verdict. It also explains basket mode behavior, including forced_directional_risk. This extra context enriches transparency 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 lengthy but well-structured with clear sections (SINGLE-MARKET, BASKET) and bullet-style enumeration of return fields. Every sentence adds useful information; there is no redundancy. It is front-loaded with the core purpose and usage directive.

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

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

Given the tool's complexity (two modes, no output schema), the description thoroughly covers both modes, lists all return fields, explains edge cases (thin_legs, forced_directional_risk), and provides actionable context. It is self-contained and leaves no major 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%, but the description adds significant value: it explains the difference between single-market and basket modes, default values (side default auto for basket, size_usd default 1000), and interpretation of size_usd per mode. This goes beyond the schema's descriptions.

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

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

The description explicitly states the tool's function as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two distinct modes (single-market and basket). It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying when this tool should be used.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround on thin books is not capturable, partial basket fills create directional risk) and gives clear context for when to use versus alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description extensively discloses behavioral details: compatibility_warning, temporal_alignment, skipped_cross_type/subtype counters, and the rarity of real spreads. This far exceeds the baseline provided by annotations.

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

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

The description is dense but efficient, front-loading the purpose and modes. It could be slightly more structured (e.g., bullet lists for modes or warnings), but no sentences are wasted given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains response fields (leg-by-leg prices, top_spreads_pp, safety fields) and their semantics. It also covers edge cases like non-equivalent bet shapes and temporal misalignment, making it fully actionable.

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 the dual-mode logic, that topic overrides work, and by providing examples and context for each parameter (e.g., 'Pre-mapped: fed | btc | ...').

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage by being cross-venue, and specifies two operational modes (topic shortcuts and explicit parameters).

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

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

The description explains two usage modes (topic shortcuts for pre-mapped macros, explicit ticker/slug for custom pairings) and warns that pre-mapped topics often return compatibility warnings. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe look-up. The description adds that it retrieves quotes by structural address, which is the core behavior. It does not disclose any additional behavioral traits such as pagination, error handling, or performance characteristics. Given the strong annotation coverage, a score of 3 is appropriate.

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

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

The description is concise: two sentences and an example, with no unnecessary words. Every sentence is informative. The structure is front-loaded with the core action, followed by a clear example. It earns its space.

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 complexity (5 parameters, 2 required), the description is sufficient for basic usage. The example covers both play and novel scenarios. The presence of an output schema reduces the need to describe return values. However, it does not explain what happens if both act and chapter are provided, which could be a valid edge case.

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 parameter. The description adds value by explaining the relationship between act/scene (plays) and chapter (novels), and provides a concrete example. This helps agents understand the parameter grouping and usage pattern beyond the basic 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 looks up quotes by structural address (act/scene or chapter) for a given work. The example reinforces the purpose. However, it does not explicitly differentiate from sibling tools like 'get_act', 'get_chapter', 'search_quotes', or 'random_quote', which could lead to confusion about when to use each.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it, what prerequisites exist, or how it compares to sibling tools like 'search_quotes' or 'random_quote'. The usage is only implied by the example, which is insufficient for clear decision-making.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds that results include citation details (work, year, speaker, source URL), which is useful context 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?

The description is a single sentence that efficiently communicates the tool's purpose and result structure with zero waste.

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

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

Given the rich annotations and output schema, the description adequately covers the main purpose and result format. It could mention randomness behavior (e.g., if results are reproducible), but overall it's sufficient.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description does not add new semantic information beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states it returns a random quote with optional filters, and it distinguishes from sibling tools like search_quotes (searching) and quote_by_location (by location).

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 fetching a random quote with filters, but does not explicitly mention when not to use or compare alternatives. It is clear but lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds scoping to identifier and pairing with remember/forget, providing useful behavioral context beyond annotations.

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

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

Three sentences, no fluff: first states action, second gives usage context and examples, third explains scope and pairing. 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 optional parameter and no output schema, the description covers purpose, usage, scope, and pairing with siblings. 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?

The sole parameter 'key' is fully described in schema (100% coverage). Description further clarifies semantics: omit to list all keys, provide to retrieve specific value, adding 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?

The description clearly states it retrieves values saved via remember or lists all keys, with concrete usage examples like ticker, address, research notes. It distinguishes from 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?

It says 'use to look up context the agent stored earlier' and pairs with remember/forget, implying appropriate scenarios. However, it does not explicitly state when not to use or provide alternatives.

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

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

The description states that setting mark_read:true flags returned events read, which is a side effect (mutation of read status). This contradicts the annotation readOnlyHint: true, which implies no state modification. According to rules, contradiction yields score 1.

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 4 sentences, front-loaded with purpose. Each sentence adds distinct information: purpose, return fields, filtering options with mark_read behavior, and alternative access. No unnecessary words.

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

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

Given 5 parameters and no output schema, the description covers return fields, filtering, mark_read behavior, polling friendliness, and external alternative. Missing details on limit parameter behavior and ordering. Fairly complete.

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

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

Schema coverage is 100%, baseline 3. Description adds value by providing examples for type (e.g., 'sec_8k') and format for since (ISO timestamp), and explains the behavior of mark_read. However, unread_only is not elaborated. So 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 starts with 'Pull fired events from your subscription feed,' which clearly specifies the verb (Pull) and resource (fired events from subscription feed). It also describes the return fields (source, citation_uri, raw event payload), making the tool's purpose distinct from sibling tools that likely don't focus on alerts.

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

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

The description provides no guidance on when to use this tool versus alternative tools like list_subscriptions or recall. It only mentions an external URL as an alternative access method, not tool comparisons. Missing 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 extensively details behavioral traits: fan-out to multiple sources, fallback from GDELT to GNews, USPTO soft-fail, date format support, and return structure. Annotations already indicate read-only, idempotent, open-world, non-destructive; description adds rich context 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-structured with example queries upfront and detailed explanations. It is slightly lengthy but every sentence provides necessary information for correct usage, earning a 4.

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

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

Given the tool's complexity (multiple sources, fallback logic, parameter variations), the description is complete. It explains the return structure despite no output schema, and covers all necessary context for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the since parameter format (ISO or relative) with examples, noting type is limited to 'company', and clarifying value accepts ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company, specifying it fans out to SEC, GDELT/GNews, and USPTO. It distinguishes from sibling tool entity_profile with an explicit when-to-use alternative.

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

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

The description gives explicit example queries ("What's new with X") and directly tells when to use entity_profile instead for static profiles, providing clear guidance.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. The description adds that memory is scoped by identifier, with different persistence for authenticated vs anonymous users, which is 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 a compact paragraph with four sentences, front-loading the primary purpose. No extraneous words, but could be slightly more concise.

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

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

Given no output schema, the description adequately covers purpose, usage, persistence, and links to related tools. It provides a complete picture for a simple key-value memory 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 for key and value. The description adds naming conventions (e.g., 'subject_property') and notes value can be any text, adding value beyond the schema.

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

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

The description explicitly states the tool saves data for reuse and distinguishes it from siblings recall and forget. It clearly identifies the verb (save) and resource (key-value pair).

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 when to use: 'when you discover something worth carrying forward.' It also mentions pairing with recall and forget. While it does not explicitly state when not to use, the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: cascading lookups, internal endpoints, and replaces manual steps. No contradictions.

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

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

Description is well-structured with examples first, then detail. Some redundancy (e.g., repeated examples), but all information is relevant and front-loaded.

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

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

Covers all aspects: supported types, input/output formats, data sources, and internal behavior. No output schema, but description sufficiently explains return values.

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

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

Schema coverage is 100%. Description adds meaning: explains what each type yields (ticker+CIK for company, RxCUI for drug), input formats, auto-disambiguation, and citation URIs.

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

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

Description uses specific verb 'resolve' and resource 'entity name to identifier', with clear examples ('What's the ticker for…'). It differentiates from sibling tools by focusing solely on identifier lookup.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID.' Provides clear context for when to use, but does not explicitly list when not to use or alternative tools.

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

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

The description adds significant behavioral detail beyond annotations: it reveals the tool calls ai_visibility_check, ranks results, treats first entity as subject, and returns specific fields (score, confidence, signal density).

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

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

The description is three sentences: first states main action, second explains the process, third provides a concrete use case. It is front-loaded and every sentence adds value.

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

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

Given no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also explains the probing mechanism and use case, making it complete for an agent.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning by stating the first entity is treated as the subject and rest as competitors, which is not in schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check. It distinguishes from the sibling ai_visibility_check by explicitly mentioning it probes multiple entities and ranks them.

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

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

The description provides a clear use case for competitive AI-marketing audits, implying when to use. However, it does not explicitly state when not to use or mention alternatives beyond the inference.

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, indicating safe read operation. The description adds crucial behavioral context: fans out across deps.dev and bundlephobia, mentions that bundlephobia's first measurement can take 5-30s and partial failures are handled gracefully with sources_failed. 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 somewhat lengthy (4 sentences) but front-loaded with the key purpose and usage. Every sentence adds valuable information: composite check, when to use, ecosystem limitation, and partial failure behavior. Could be slightly more concise but overall well-structured.

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

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

Given the tool's complexity (multiple data sources, multiple return fields, partial failures), the description covers most aspects: it lists return fields (summary block, per-advisory detail, links, alternative versions), mentions partial failures and timeouts, and notes ecosystem limitations. No output schema exists, so the description compensates moderately well, though a more detailed return structure example would improve 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 description coverage is 100%, so the description's parameter information (package name, version defaults to latest, scoped packages accepted) is largely redundant with the schema. Baseline 3 is appropriate as no additional semantic value is added beyond what the schema already provides.

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

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

The description explicitly states 'Composite should I add this npm package to my project check in ONE call', clearly identifying the verb (check) and resource (npm package). It also distinguishes from any sibling tool by focusing on npm dependency analysis, which is unique among the listed siblings.

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

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

The description provides explicit usage directives: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states ecosystem limitations ('NPM ecosystem only in v1') and mentions alternatives for other ecosystems, giving 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?

Annotations already indicate read-only, idempotent, open-world behavior. The description adds specific behavioral traits: matching paraphrases and canonical text, which goes beyond annotations and helps the agent understand the search scope.

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: the first states the core purpose, the second provides an illustrative example. No wasted words, front-loaded with essential information.

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

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

Given the output schema exists, return values are documented. The description covers the key non-obvious behavior (paraphrase matching). It doesn't mention pagination or limit details, but those are in the schema. Adequately complete for a search tool.

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

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

Schema coverage is 100%, but the description adds richer semantics for the 'query' parameter by explaining substring matching, case-insensitivity, and paraphrase handling. For other parameters, it doesn't add beyond schema, so slight 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 'Search quotes by substring' and distinguishes the tool by mentioning it matches both canonical text and popular paraphrases, which differentiates it from sibling tools like 'check_attribution' or 'random_quote'.

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 effectively explains how to use the tool (substring search, case-insensitive, paraphrase matching) with a helpful example. It lacks explicit guidance on when not to use it or alternatives, but the context is clear.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond by detailing the embedding model (BGE-base-en), windowing (500-char overlapping windows), character cap (200K chars with truncation and flagging), and output specifics (offsets, similarity scores). 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?

Five sentences, front-loaded with purpose, then details. Every sentence adds value: use case, how it works, pairing suggestion, implementation details, and limits. No redundancy or filler.

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

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

Despite no output schema, the description covers the return format (top-N passages with character offsets and similarity scores), the truncation behavior, and the pairing with ask_pipeworx_grounded. For a search tool with good annotations, this is sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the 200K char cap for the 'text' parameter (already in schema) and notes truncation behavior, but does not significantly augment meaning beyond the schema. The output format is described but not parameter-specific.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and explains the tool's function: it takes a text and query, returns passages. It distinguishes itself from siblings like ask_pipeworx_grounded (by pairing with it) and provides a specific use case. The verb 'search' and resource 'within a fetched record' are precise.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. It provides a clear when-to-use context but does not explicitly state when not to use (e.g., when the document fits in context). This is a minor gap.

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?

Disclosure of OAuth requirement, return of subscription id, delivery channel constraints (SMS cap, webhook secret once, auto-disable), which goes beyond annotations. 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?

Well-structured with main purpose first, then requirements, types, delivery. Every sentence adds value; could be slightly more concise but 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?

Given complexity (3 params, nested objects, no output schema), the description covers all necessary aspects: requirements, types, delivery details, constraints, making it fully actionable.

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

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

100% schema coverage and description enriches each parameter with examples, constraints, and detailed explanations for 'type', 'params', and 'delivery'.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the subscription id. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides explicit context: requires Pipeworx OAuth account, lists supported types and their parameters. Does not explicitly exclude other tools but gives clear when-to-use guidance.

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

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

Beyond annotations, description discloses that it returns category-bucketed examples from a live catalog, that no args gives full spread, that topic focuses, and that it provides exact tool+argument shapes. 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 front-loaded with common queries and well-structured, but slightly verbose. Every sentence adds value, but 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, description fully explains what the tool returns (category-bucketed example questions with exact shapes) and how to use it. Complete for an onboarding tool with one optional parameter.

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

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

Schema coverage is 100% with description for 'topic'. Description adds usage examples ('finance', 'pharma', 'betting') and clarifies behavior when omitted vs provided, enriching what schema alone provides.

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 is the onboarding entry point returning category-bucketed example questions with exact tool+argument shapes. It also lists example user queries and distinguishes itself from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions alternatives: 'meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. Also explains when to pass optional topic vs no arguments.

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 important behavioral details beyond annotations: ownership enforcement, row deactivation (not deletion), and data retention for historical events. 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 concise sentences with front-loaded action. Every word adds value—purpose, 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 fully covers purpose, usage constraints, and side effects. Annotations support the behavioral description. Complete for its 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?

The sole parameter 'id' is fully described in the schema (coverage 100%). The description does not add parameter-level information beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Description clearly states the action ('Cancel a subscription by id') and provides specific context about ownership enforcement and behavior (deactivate vs delete), distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states when to use (cancel by id) and imposes ownership condition. While no explicit alternatives are listed, the context makes usage clear given sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds behavioral context by revealing the underlying data sources (SEC EDGAR + XBRL), the return format (verdict, structured form, citation), and the version scope (v1). No contradictions with annotations.

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

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

Description is concise (about 8 sentences), front-loaded with example intents, then states purpose, domain, and return details. Every sentence adds value without redundancy. Perfectly structured for quick agent comprehension.

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

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

Given there is no output schema, the description fully compensates by describing the return verdict, structured form, actual value with citation, and percent delta. It also explains the tool's value proposition (replacing 4-6 calls). No gaps for the given 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?

The sole parameter 'claim' has 100% schema description coverage, providing clear examples and format. The tool description enriches this by explaining how the claim is processed (NL parsing, entity resolution, data lookup, numeric comparison), adding meaning 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?

Description starts with natural-language examples of user intents and clearly states it performs claim verification against authoritative sources, specifying the domain (company-financial claims). It distinguishes itself from sibling tools by explaining it consolidates multiple sequential calls, making the purpose very specific.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and limits scope to company-financial claims for public US companies. While it doesn't list explicit when-not-to-use scenarios, the domain restriction provides clear context. No direct sibling alternative exists for claim verification.

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