Pangaea

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable context: the free default model (Workers AI Llama-3.3-70b), the requirement of a BYO API key for Anthropic, and the return structure. This goes beyond annotation safety flags, though it doesn't discuss rate limits or error handling.

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 with clear, front-loaded information: the core action first, then details on models and API key, followed by return format and use cases. Every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

Given that there is no output schema, the description adequately explains the return format (per-model fields plus combined view). It covers the entity parameter, optional models list, API key requirement, and optional context. It is complete for a probe tool, despite lacking explicit error handling or timeout details.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the default model, the pass-through nature of _apiKey, and the optional context parameter for disambiguation. This enriches the schema-provided 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 it probes LLMs for knowledge about an entity and scores visibility, which is a specific verb+resource. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, which may have overlapping functionality. The purpose is clear but lacks sibling distinction.

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

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

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and mentions default vs paid models, which provides implicit usage context. However, it does not explicitly state when to use this tool versus alternatives or when not to use it, leaving some ambiguity for 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable context: it routes to 4,774 tools across 1,242 sources, returns structured answers with citation URIs, works on every tier, and makes 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 relatively long but well-structured: it starts with a strong preference directive, then explains scope, usage, examples, and escalation. It is front-loaded with key guidance. While some redundancy exists, each sentence serves a purpose.

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

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

Given the tool's complexity (4,774 tools, many use cases) and the schema's 100% coverage, the description is highly complete. It explains when to use, what it does, how it works (routing, citations), provides examples, and distinguishes from siblings. No output schema, but return values are described (structured answer with citations).

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

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

Schema description coverage is 100% with all parameters documented (question and its five aliases). The description mentions 'question' in natural language but does not add significant meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes factual questions to a large array of verified sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each, and provides concrete examples.

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

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

The description explicitly advises 'PREFER OVER WEB SEARCH' and provides detailed guidance on when to use this tool (factual questions about real-world entities, events, numbers) and when to step up to alternatives (hallucination-resistant or broad multi-part questions). It also gives clear examples.

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

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

Annotations already provide safety hints (readOnlyHint, idempotentHint, destructiveHint=false). The description adds valuable behavioral context: extra LLM call, extraction behavior from only tool results, explicit refusal reasons (not_in_source, no_tool_match, etc.), and 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 dense but efficient: front-loaded with purpose, followed by usage context, return format, and comparison to sibling. Every sentence adds distinct value, no redundancy. Appropriate length given complexity.

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

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

Given the tool's complexity (4,774 tools, 1,242 sources, multiple refusal reasons) and lack of output schema, the description is highly complete. It explains return structure, refusal reasons, cost trade-off, and use cases, leaving no critical gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'question' as the primary parameter and lists aliases, but the schema already fully documents them. The description adds minimal new parameter semantics beyond reinforcing natural language input.

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 is a 'hallucination-resistant answer mode for high-stakes reads' and details its function: it routes questions through tool selection, extracts answers only from tool results, and returns explicit refusals when data doesn't directly answer. It distinguishes from sibling ask_pipeworx by noting extra cost and preference for casual lookups.

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

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

The description explicitly says when to use the tool (high-stakes reads, when answer will be quoted, cited, or acted on, e.g., financial/legal/medical) and when not (prefer ask_pipeworx for casual lookups). It provides clear guidance and alternatives.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, so the description carries low burden for safety, but it adds extensive behavioral details: resolution process, fan-out logic, low-confidence handling, closed market handling, wide spread warnings, cancellation rule parsing, and response shapes. No contradictions with annotations; the description enhances transparency significantly.

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

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

The description is very long (multiple paragraphs) and contains extensive detail on fan-out examples, response shapes, and edge cases. While the structure is logical and the information is valuable, it could be more concise for an AI agent to parse quickly. The verbosity reduces the efficiency of the description.

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

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

Despite the lack of an output schema, the description thoroughly explains return values, including market fields, analysis block, evidence keys, resolver contract, parent event extractor, news fields, and safety measures. It covers numerous edge cases (low confidence, closed markets, wide spreads, cancellation rules). For a tool of this complexity, the description is exceptionally 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% for all three parameters, so baseline is 3. The description adds meaningful usage guidance beyond the schema: examples for market input, explanation of 'quick' vs 'thorough' for depth, and rationale for include_raw (summarized vs full payloads). This adds value, warranting a 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 it researches a Polymarket bet by pulling Pipeworx data, specifies input types (slug, URL, question text), and explains the output (evidence packet + market-vs-model comparison). However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, though usage examples imply its role.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when to use depth and include_raw parameters, but does not state when not to use the tool or list alternatives. This gives clear context but lacks explicit exclusions.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 efficient and front-loaded with common queries, but slightly long. However, every sentence adds value, covering usage, data sources, and behavior with minimal 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?

Without an output schema, the description explains return values (paired data, citation URIs, sorted by primary metric). It also covers data freshness and edge cases like off-calendar fiscal years, making it complete for a 2-parameter 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 significant meaning: explains type values with data sources, gives concrete examples for values (tickers/CIKs for companies, drug names), and specifies min/max items. This enriches the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call, with specific query examples like 'X vs Y' and 'rank these companies'. This distinguishes it from siblings like entity_profile or search.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups' when comparing entities, and provides common query patterns. It implicitly suggests alternatives by noting it replaces 8–15 sequential lookups.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds no extra behavioral context beyond 'full metadata', which is acceptable given the low risk nature.

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?

One concise sentence containing the essential information with 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 lookup tool with full annotations, one parameter, and an output schema, the description is adequately complete. It could mention that metadata is full, but the description already implies that.

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

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

The input schema fully describes the parameter 'id' with example. The description adds no additional meaning beyond the schema.

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

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

The description clearly states the tool retrieves full metadata for a PANGAEA dataset by numeric ID, with an example. This distinguishes it from sibling tool 'dataset_by_doi' which uses DOI.

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 a numeric ID is available, but does not explicitly mention when not to use or name 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 provide readOnlyHint, idempotentHint, etc. The description adds context that it returns 'Full metadata' and accepts DOI or URL, but does not detail potential limitations or behavior beyond that.

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, front-loaded sentence with no excess words; it is concise and structured effectively.

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 existence of an output schema, the description is largely complete. However, it could be improved by briefly noting that the metadata pertains exclusively to PANGAEA datasets.

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

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

Schema description coverage is 100%, but the description adds value by clarifying that the DOI can be in URL form, enriching the parameter semantics.

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

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

The description uses specific verb 'Full metadata' and resource 'PANGAEA dataset by DOI', clearly distinguishing it from the sibling 'dataset' tool by specifying the input type.

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

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

The description implies usage for retrieving metadata by DOI but lacks explicit when-to-use or when-not-to-use guidance or alternatives like 'dataset' for broader searches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's behavioral additions are not critical but add value: describes return format (findings packet with evidence, confidence, source, fetched_at, citation) and that the tool never invents (gaps[]). Also mentions potential empty gaps for uncatalogued topics. No contradiction.

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

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

The description is relatively long but well-structured, with critical information front-loaded (account requirement, alternative). Every sentence adds value, though a minor reduction could improve conciseness. It remains clear and scannable.

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 lack of an output schema, the description thoroughly explains the return format (findings packet) and tool behavior. It mentions the scale of data sources (1242) and tools (4774), parallelism, and explicit gaps handling. For a complex research tool, this is comprehensive.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds value by specifying exact facet counts for each depth level ('quick=3, standard=5, thorough=8 (paid plans)') and clarifying that the question can be broad/multi-part. This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources' and distinguishes it from siblings like ask_pipeworx (single lookup) and ask_pipeworx (for breaking news). It gives examples of appropriate queries, making the purpose highly specific and distinguishable.

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 (broad/multi-part questions over structured data) and when not to (single lookup, breaking/colloquial news). Specifies account requirement and that 'thorough' depth needs a paid plan. Names alternative tool ask_pipeworx for cases where this tool is inappropriate.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces that it is a read-only discovery tool and adds behavioral details: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly'. This adds value beyond annotations without 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 well-structured with the core purpose first, followed by details. It lists many domains, which is helpful but slightly verbose. Each sentence adds value, and the overall length is appropriate for the information conveyed.

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

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

Despite lacking an output schema, the description fully explains what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly'. It also mentions default and maximum limit, covering all agent needs 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 is 100%, and the description adds significant meaning: it explains that 'query' accepts natural language descriptions, provides multiple examples, and lists aliases (q, task, search, description). This goes beyond the schema by clarifying usage patterns and parameter flexibility.

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 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, FDA, etc.). It explicitly distinguishes itself from siblings by advising 'Call this FIRST when you have many tools available and want to see the option set', which differentiates it from other search or data 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?

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: [domains]' and 'Call this FIRST when you have many tools available and want to see the option set'. It does not explicitly say when not to use, but the context implies it is for discovery before taking action, making it clear enough.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds that patents soft-fail after May 2025 and outlines the multi-source fan-out behavior. No contradiction with annotations.

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

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

The description is informative with example queries front-loaded. While lengthy, it avoids redundancy and structures information logically. Could be slightly more concise but 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's complexity and lack of output schema, the description covers return fields, sources, and caveats (patent sunset, name limitation). It is reasonably complete for an agent to understand what to expect.

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

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

Schema coverage is 100% with clear descriptions. Description adds that value accepts ticker or zero-padded CIK but not names, and the enum type is 'company' only. This enriches 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 states exactly what the tool does: 'full cross-source profile of a US public company' and lists the data returned (CIK, filings, fundamentals, patents, news, LEI). It clearly distinguishes from siblings like resolve_entity and compare_entities.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view' and 'names not supported – use resolve_entity first if you only have a name'. This tells when to use and when not.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description does not need to restate safety. It adds context about aggregation and counts, but does not explain scope of 'matching datasets' or behavior on non-existent fields. The description complements annotations without contradiction.

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

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

The description is a single, well-structured sentence that front-loads the action ('Aggregate matching datasets by a facet') and includes concrete examples. No wasted words; every part 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 low complexity of the tool (3 parameters, simple aggregation) and the presence of an output schema, the description is fairly complete. It explains the core function, facet field examples, and optional query scope. Could be slightly more complete by mentioning the return type (buckets with counts) if not covered by the output schema.

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

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

Schema coverage is 100%, so baseline score is 3. The description adds example field values and notes 'query' is optional, which provides some additional context. However, it does not detail parameter semantics beyond what the schema already provides, such as default size or how field format is enforced.

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 aggregates datasets by a facet field, giving specific examples like 'agg-mainTopic'. It uses a specific verb ('Aggregate') and resource ('matching datasets'), making the purpose clear. However, it does not explicitly differentiate from siblings like 'search' or 'dataset', which could confuse which tool to use.

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

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

No guidance on when to use this tool versus alternatives like search or dataset. Does not mention when not to use it or any prerequisites. For example, it does not state that the field must be a keyword-type facet field. This lack of context hinders correct 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 indicate destructive and idempotent behavior. The description adds context: it only works on previously stored memories and is intended for clearing sensitive data. 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 three short sentences, each earning its place: the first states the primary action, the second provides usage guidance, and the third links to related tools. Front-loaded and efficient.

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

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

For a simple one-parameter delete tool with no output schema, the description covers purpose, usage conditions, and related tools. It could mention behavior on missing key, but the idempotent annotation mitigates that. Complete enough for effective use.

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

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

Schema coverage is 100% and the parameter description in schema is 'Memory key to delete'. The tool description repeats 'by key' but adds no new semantic detail beyond what the schema provides. Baseline is 3.

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

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

The description clearly states 'Delete a previously stored memory by key.' It specifies the action (delete), resource (memory), and method (by key). It distinguishes from siblings by mentioning pairing with remember and recall, which are for storing and retrieving.

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

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

Explicitly provides three clear scenarios for use: when context is stale, task is done, or to clear sensitive data. It also advises pairing with remember and recall, indicating alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds specifics: fetches the page, extracts title/description/key links, emits standard markdown format, and suggests placement at site-root/llms.txt. 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 clear sentences with a bullet list of use cases. No wasted words; every sentence adds value. Information is front-loaded with the main purpose and format.

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

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

Despite no output schema, the description fully explains the output format ('standard llms.txt markdown', 'single text blob') and use cases. It covers what the tool does, how it works, and what to expect.

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

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

Schema has 100% coverage, so baseline is 3. The description adds context beyond schema: it explains that max_links controls link entries with defaults and maximum, and implies the URL parameter is for summarizing a site. This adds meaningful guidance.

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 generates a llms.txt file for any URL, specifying the verb (generate) and resource (llms.txt file), and distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation for AI crawlers.

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

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

The description explicitly lists use cases (client site indexing, personal project drafting, competitor auditing) but does not provide explicit when-not-to-use or compare to alternatives, though 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 (readOnlyHint, idempotentHint, destructiveHint) already confirm safe read operation. Description adds field list but no additional behavioral traits like pagination or rate limits.

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

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

Three focused sentences: purpose, returned fields, usage guidance. No redundant information, front-loaded with key action.

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

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

Adequately covers purpose, return fields, and usage for a simple list tool with one optional parameter. Could potentially explain the 'params' field further but not a major gap.

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

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

Schema coverage is 100% with clear description for the only parameter (include_inactive). Description does not add any extra meaning beyond the schema.

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

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

Clearly states the verb 'list' and resource 'subscriptions'. Explicitly lists the fields returned, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly indicates scenario for 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 are all false, but description adds rate-limiting (5/day), free usage, and that feedback doesn't count against quota. Mentions feedback directs roadmap. Additional 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, front-loaded with purpose. No wasted words. Efficient and clear.

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 schema covers parameters and no output schema, description is complete: explains what, when, how, and constraints. No missing information for a feedback tool.

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

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

Input schema fully describes parameters with 100% coverage. Description adds guidance on writing messages (specific, tool-oriented, no user prompts). Enhances semantic clarity.

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 sends feedback about bugs, feature requests, data gaps, or praise. Distinct from sibling tools which are primarily query or action tools.

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

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

Explicitly lists when to use: bug, feature, data_gap, praise. Guides how to describe issues in terms of tools/packs, and notes team reads digests daily. No alternatives mentioned but clear use cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral traits beyond this: self-aggregating signal, derived from CF analytics-engine, no PII, and caching behavior (5min-1h). 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 informative but not overly concise. The first sentence states the core purpose. The numbered use cases add value but could be slightly trimmed. Overall, it is well-structured and front-loaded.

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

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

Given no output schema, the description explains the return content (top tools, packs, total call volume) and format (pack, tool, count). It also mentions caching. This is sufficient for a read-only aggregator, though adding an explicit return type 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% for the single parameter 'window'. The description adds semantic value by explaining that shorter windows surface hot items and longer windows show steady-state demand, which complements the schema's enum list.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It specifies the verb 'returns' and the resource 'Pipeworx trending data'. It distinguishes itself from siblings like ask_pipeworx and search by focusing on aggregate signals rather than individual queries.

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: discovering hot data sources, confirming popular tools, and checking alignment. It does not explicitly say when not to use or name alternatives, but the context is clear enough for an agent to understand when this tool is appropriate vs. others like search or ask_pipeworx.

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: monotonicity violations, partition-sum checks, semantic anchor with Jaccard similarity, partition filter, fill check against live order book. No contradictions with annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true).

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

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

The description is well-structured with a summary sentence, then sections for each mode, then details on semantic anchor and partition filter. However, it is quite long and could be slightly more concise without losing 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?

No output schema, but the description thoroughly explains the response structure (opportunities[] with fields, partition_check, fill_check) and covers edge cases like skipped_low_similarity and placeholders. It is 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%, but description adds significant value by explaining event vs topic mode, providing example slugs and seed questions, and detailing how each parameter affects the scan. This goes well beyond the schema descriptions.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes (no args, event, topic) with specific use cases. It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance for when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Recommends event mode for specific markets and directs to polymarket_fill_risk for custom sizing.

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

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

The description adds extensive behavioral context beyond annotations: caching behavior (1h KV cache keyed on knobs), technical details about the three model segments (log-normal barriers, GDELT momentum, partition overround with sport-specific alphas), placeholder slug filtering, and diagnostics for empty segments. It explains that Fed bets are surfaced but excluded from ranking due to unreliable signals. Annotations already confirm read-only, open-world, and idempotent behavior, and the description does not contradict them.

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

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

The description is very long and contains many technical details (specific α values, run gates) that may be excessive for an AI agent. The first sentence is strong, but the middle section reads like internal documentation. It could be streamlined by moving implementation details to a separate note or trimming to essential decision-making information.

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

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

The description covers response structure (by_segment, fed_candidates, _diagnostics) and explains why segments can be empty, which is valuable. It mentions key fields like edge_pp_net, kelly_fraction, and liquidity but does not provide a full list or formatting. Given the absence of an output schema, this is nearly complete but could be more explicit about the exact fields returned for each opportunity.

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

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

The input schema has 100% coverage with descriptions for all 9 parameters, so the bar is high. The description adds value by grouping parameters into 'tradeable-edge knobs' and providing reasoning for default values and usage (e.g., 'Set to 5000 to drop thin-book opportunities'). It explains how min_kelly and min_partition_leg_kelly differ in application, which is not evident from the schema alone.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It positions the tool for 'what should I bet on today', distinguishing it from related siblings like polymarket_arbitrage which likely focuses on arbitrage across platforms.

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 the use case: discovering betting opportunities without manually paging through hundreds of markets. It provides context on when to use (daily bet discovery) but does not compare directly to sibling tools like polymarket_arbitrage or bet_research. Implicitly it suggests this is for edge-based opportunities rather than simple market scanning.

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 extensive behavioral details beyond annotations: it explains response structure (tracked, expired, snapshot_dates), limits (60-day TTL, decay from daily closes), and computation details (trend, decay_pp_per_day). Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description reinforces this without 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 well-structured with clear sections (purpose, args, response, limits). It is somewhat long but every sentence adds value. Front-loads the core purpose and use case effectively.

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

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

Despite lacking an output schema, the description fully explains the response format (tracked array with fields, expired array, snapshot_dates) and limits. For a tool with 2 optional params and read-only behavior, this provides complete context for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with good parameter descriptions. The description only reiterates defaults and clamp (max 30 for days, default window '1wk'), adding marginal value beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and distinguishes itself from siblings like polymarket_edges by focusing on historical trends rather than current snapshots.

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 strong context for when to use the tool: 'Answers how long has this edge existed and is it shrinking?' It implies usage for historical analysis vs current edges, but does not explicitly name alternatives or state when not to use it.

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

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

Annotations indicate readOnlyHint, idempotentHint, openWorldHint. Description adds behavioral details like walking the ladder, returning specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced directional risk and thin books. 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 lengthy but well-structured with mode headers and bullet points for return fields. Every sentence adds value, but could be slightly more concise 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 complexity (two modes, many return fields) and no output schema, description thoroughly lists return fields for both modes, explains edge cases (thin books, forced directional risk). Slightly missing specifics on exact types of some fields but overall 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 covers all 4 parameters with descriptions. Description adds extra context: default values (size_usd=1000), range (10-1,000,000), and mode-specific interpretations (size_usd as settlement notional in basket mode). Provides more meaning than 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 clearly states the tool performs 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It differentiates from siblings by specifying when to use it before polymarket_arbitrage or polymarket_edges trades above ~$500.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills lead to directional risk). Also specifies required parameters and modes.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral context: compatibility warnings for non-equivalent bet shapes or temporal misalignment, skipped cross types, and the fact that most pre-mapped topics return warnings. This goes well 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 verbose and repeats information (e.g., compatibility warnings explained twice). While well-structured with clear sections, it could be more concise without losing 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 (cross-venue spread with multiple safety checks), the description covers modes, compatibility warnings, temporal alignment, skipped comparisons, and response structure. No output schema exists, but the description compensates by explaining the response. 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?

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning by explaining the two modes, providing examples of topic values, and detailing how explicit tickers override the topic. This adds value beyond the schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit tickers), making the purpose specific and distinguishable from sibling tools.

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

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

The description explains when to use the tool (to compare prices) and provides conditions for when spreads are not meaningful via compatibility warnings. However, it does not explicitly mention alternatives among sibling tools, such as polymarket_arbitrage, which might be related.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds scoping to user identifier and behavior when key omitted, adding value beyond annotations.

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

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

Two sentences with some redundancy (e.g., 'previously saved via remember' is clear from context). Still efficient but could be tighter.

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

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

For a simple read-only tool with one optional parameter, the description covers retrieval, listing, scoping, and pairing with siblings. No output schema, but behavior is explained adequately.

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

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

Schema coverage is 100% and description adds meaning: omitting key lists all, retrieving specific value with key. Provides clear semantics 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 retrieves a value by key or lists all keys if omitted, distinguishing it from siblings 'remember' and 'forget'.

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

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

Provides explicit guidance to use for looking up previously stored context, and mentions pairing with remember/forget, but doesn't explicitly state when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds ordering and source context but does not disclose additional traits like pagination or rate limits. 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?

Single sentence that is front-loaded with purpose. No waste, every word adds value.

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

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

With output schema present, return values are covered. Parameters are well-documented in schema. Description is sufficient for a simple list-retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions (days and size). Compensates minimally.

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

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

Description states it returns 'most recently published PANGAEA datasets' ordered by newest DOI first. It uses a specific verb ('published') and resource ('PANGAEA datasets'), clearly distinguishing from sibling tools like 'search' or 'dataset_by_doi'.

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

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

The description implies use for retrieving recent datasets but does not explicitly state when to use vs alternatives like 'search' or 'dataset_by_doi'. No exclusions or alternative suggestions are 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 declare readOnlyHint and idempotentHint. The description adds context about the feed being persisted, the structure of returned events (source, citation_uri, raw payload), and the effect of mark_read. 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 four sentences, each serving a purpose: purpose, return fields, parameters/behavior, and alternative access. No fluff, well-structured.

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

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

Covers purpose, return fields, filtering, mark_read behavior, and alternative access. Missing details on limit parameter interpretation and pagination, but these are minor given the tool's simplicity and the high schema coverage.

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 extra meaning for type (example 'sec_8k'), since (ISO timestamp), and mark_read (flag to mark read, affecting next call). This goes 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 clearly states the tool pulls fired events from the subscription feed and lists return fields. It distinguishes from generic 'recent' siblings by specifying 'alerts' from a subscription feed, but does not explicitly differentiate from similar tools like 'recent_changes'.

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

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

Provides guidance on filtering by type and since, and explains the mark_read parameter's effect on subsequent calls. Mentions polling is fine and gives an alternative endpoint. However, it does not explicitly state when to use this tool over siblings or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant value: details the multi-source fan-out (SEC, GDELT, GNews, USPTO), notes USPTO soft-fail due to sunset, and describes return structure (changes[] grouped by source + total_changes + citation URIs). No contradictions.

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

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

The description is packed with information but remains well-structured: front-loaded purpose with examples, then fan-out details, parameter guidance, return format, and sibling distinction. Every sentence earns its place, though the length is justified by the tool's complexity.

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

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

Given the tool's complexity (multiple sources, fallback, date handling) and no output schema, the description covers the return structure and source behavior thoroughly. It even notes limitations (USPTO soft-fail). No gaps remain for an AI agent to misuse the tool.

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

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

Schema coverage is 100%, so baseline 3. The description adds context: explains acceptable formats for since (ISO date or relative shorthand with examples), recommends typical usage ('30d' or '1m'), and clarifies value can be ticker or CIK. This enriches the schema descriptions.

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

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

The description uses specific verbs and resources: 'change feed for a company', lists query examples like 'what's new with X', and explicitly distinguishes from sibling entity_profile by contrasting it as 'static profile regardless of window'. The purpose is unmistakable.

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

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

The description provides explicit when-to-use with example queries, and gives a clear when-not by directing users to entity_profile for static profiles. It also explains fallback behavior (GDELT preferred, GNews when rate-limited) and parameter guidance (use '30d' for typical monitoring).

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, destructiveHint=false. Description adds critical context: persistence varies by authentication (persistent for authenticated, 24h for anonymous), scoping by identifier. No contradictions.

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

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

Three sentences, front-loaded with main purpose. Each sentence adds distinct value: purpose, usage examples, persistence/companion tools. No redundancy or 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?

For a simple key-value storage tool with two required parameters and no output schema, the description covers purpose, usage, persistence, and companion tools completely.

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

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

Schema covers both parameters with clear descriptions (100% coverage). Description adds the operational context of scoping and pairing, which enhances understanding beyond the schema alone.

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

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

The description clearly states 'Save data the agent will need to reuse later' with a specific verb (save) and resource (data). It distinguishes from sibling tools like 'recall' and 'forget' by mentioning them and pairing with 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?

Provides explicit when-to-use guidelines: 'when you discover something worth carrying forward' with concrete examples. Mentions pairing with recall and forget. Lacks explicit when-not-to-use, but context is strong.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that each call cascades through several endpoints internally, details return values for each type, including citation URIs. No contradictions.

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

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

Description is concise yet info-dense. Front-loaded with example queries, then explains supported types and return values. Every sentence adds value; no fluff.

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

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

No output schema, but description thoroughly explains return values for each type, including citation URIs. Covers auto-disambiguation and internal cascading. Complete for the tool's complexity.

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

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

Schema coverage is 100%. Description enriches each parameter: explains how 'value' is used for each type (ticker, CIK, name for company; brand/generic for drug) and what 'type' refers to. Provides actionable context beyond enum labels.

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

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

The description states the tool resolves names to canonical identifiers, provides example queries ('What's the ticker for...'), and lists supported types (company, drug). It clearly distinguishes from sibling tools by specifying its unique role.

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 FIRST whenever you have a name but need an ID.' It explains that it replaces multiple manual lookups, implying efficiency. Lacks explicit when-not-to-use or alternatives among siblings, 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 declare readOnly, openWorld, idempotent, non-destructive. Description adds that it probes each entity and returns a ranked list. 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 with no fluff, front-loaded with action 'Compare AI visibility...', efficient and clear.

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

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

Despite no output schema, description specifies return fields (score, confidence, signal density per entity). Covers purpose, usage, and behavior fully.

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

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

Schema coverage is 100%, so parameters are already well-documented. Description explains how 'entities' are used (first is subject) but adds no new parameter details beyond schema.

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

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

Description uses specific verb 'compare' and resource 'AI visibility across multiple entities', and distinguishes from sibling 'ai_visibility_check' by emphasizing side-by-side comparison and ranking.

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 it's 'useful for competitive AI-marketing audits' and gives a concrete example question. Does not provide exclusions or 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?

Beyond annotations (readOnly, idempotent, etc.), description adds important details like bundlephobia's first-measurement delay (5-30s) and failure handling with sources_failed. No contradiction.

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

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

Three-sentence description is dense but well-structured, front-loading the main purpose. Slightly long 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 complex composite tool with no output schema, description thoroughly explains return fields, failure modes, and ecosystem scope, making it complete for agent decision-making.

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

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

Schema covers 100% of parameters. Description adds context about version defaulting to latest and acceptance of scoped packages, enriching beyond the schema.

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

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

Description clearly states the tool's purpose as a composite check for adding npm packages, combining data from deps.dev and bundlephobia. It distinguishes from siblings by specifying npm-only and mentioning alternatives for other ecosystems.

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

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

Explicitly tells when to use ('is X safe / popular / small') and when not to (other ecosystems), with graceful degradation on partial failures.

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

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

Beyond the provided annotations (readOnlyHint, openWorldHint, etc.), the description adds that search returns dataset title, DOI, authors, year, and topics, and clarifies it is full-text. 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?

Very concise: three sentences. First sentence states purpose and domain, second lists returned fields, third gives usage examples. No redundancy.

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

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

Given tool complexity (simple search with 3 optional params and output schema), the description covers use cases, returned fields, and domain. Lacks details on sorting or default behavior but is largely 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% and descriptions are already informative. The description adds marginal value through examples, but does not enrich parameter understanding beyond what the schema 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 the tool is for full-text search of PANGAEA datasets and lists specific domains. It mentions returned fields but does not explicitly differentiate from sibling tools like 'search_within' or 'dataset'.

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

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

Provides concrete examples of questions to use with the tool (e.g., 'ocean temperature datasets'), indicating appropriate usage contexts. Does not specify when not to use or mention alternatives.

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

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

Disclosures beyond annotations: mentions use of BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and return of character offsets and similarity scores. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destruction; description adds technical and behavioral details 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?

Single paragraph with clear structure: purpose, usage context, pairing suggestion, then technical details. Every sentence adds value; no redundancy. 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?

Despite no output schema, the description explains return format (top-N passages with character offsets and similarity scores), input constraints (200K char cap), and behavior (overlapping windows, truncation flag). It also provides a pairing strategy. Complete for a tool of this complexity.

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

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

Schema description coverage is 100% (all three parameters described). The description adds contextual usage guidance like 'Pass the text you already pulled' and reinforces the purpose of each parameter, but does not provide additional technical details beyond the schema. Richer context warrants a slight upgrade from baseline 3.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the verb 'search within' and the resource 'a fetched record'. It distinguishes from siblings like general 'search' by requiring pre-fetched text, and provides concrete examples (SEC 10-K, article, etc.).

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Also gives an alternative pairing with 'ask_pipeworx_grounded', indicating how to use it together with another tool. No misleading 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?

Discloses numerous behavioral traits beyond annotations: creates subscription, requires OAuth, details delivery channels with constraints (SMS cap, webhook auto-disable after 10 failures), and notes that webhook secret is returned only once. 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 examples and bullets, but somewhat verbose. Still, every sentence adds value and is front-loaded with the core purpose.

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

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

Given the tool's complexity (3 params with nested objects, no output schema), the description comprehensively covers behavior, types, delivery, constraints, and return value. Sufficient for an agent to invoke correctly.

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

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

With 100% schema coverage, the description adds substantial meaning: explains each type enum with concrete examples, details the params object for each type, and clarifies delivery options and constraints (e.g., email validation, SMS cap, webhook signing). Significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying the creation action.

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

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

The description provides clear context on when to use the tool (creating a subscription) and prerequisites (requires Pipeworx OAuth account). It implies alternatives by mentioning pull methods like recent_alerts but does not explicitly state when not to use.

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

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

Annotations already declare readOnly=true, idempotent=true, non-destructive. Description adds that it returns category-bucketed example questions with exact tool+argument shape, which is useful context beyond annotations.

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

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

Description is lengthy but front-loaded with synonyms and role. Every sentence adds value, though some repetition could be trimmed. Adequate for a complex onboarding tool.

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

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

For a non-destructive, read-only tool with one optional parameter and no output schema, the description fully explains purpose, usage, and output, sufficient for an agent to use 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%; description adds context for the optional topic parameter (e.g., 'finance') and explains behavior when omitted (full spread), enhancing 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 that this is the onboarding entry point, returns example questions and tool calls, and differentiates from sibling tools like ask_pipeworx.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use and alternative guidance.

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

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

Discloses ownership enforcement and that deactivation is non-destructive, surpassing the annotations (which already indicate idempotent, non-destructive). No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, every sentence adds necessary detail. No superfluous content.

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

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

Given the tool's simplicity (one parameter, no output schema), the description provides comprehensive coverage: purpose, constraint, effect, and reference to related tool. Complete for agent decision-making.

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% for the 'id' parameter. The description adds context about ownership, which the schema lacks, justifying a score above baseline.

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

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

Clearly states 'Cancel a subscription by id' — a specific verb and resource. Distinguishes from siblings 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 mentions ownership enforcement ('you can only cancel your own subscriptions') and the effect on historical data ('deactivated not deleted, events stay via recent_alerts'). Provides good context for when and how to use, though lacks explicit when-not-to-use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it returns a verdict with categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), extracted structured form, actual value with pipeworx:// citation, and percent delta. It also explains the underlying data source (SEC EDGAR + XBRL). 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 efficiently written with front-loaded purpose and examples. Every sentence adds value: it covers usage, supported claims, output format, and efficiency benefits. No superfluous content.

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

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

Given the tool's complexity (claim verification), the description fully covers input format, supported claim types, output verdict categories, and underlying source. There is no output schema, so the description compensates thoroughly. It also explains when the tool is beneficial (replaces sequential calls).

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

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

Schema description coverage is 100% with a clear description of the 'claim' parameter. The description reinforces this by providing example claims and explaining the tool's efficiency. It adds context beyond the schema, such as replacing multiple sequential calls, which aids understanding.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides example queries and specifies it handles company-financial claims for public US companies via SEC EDGAR + XBRL. It distinguishes itself by noting it replaces 4-6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported claim types (company-financial claims for public US companies). While it doesn't explicitly state when not to use it, the context is clear enough. No sibling alternatives are named.

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