Airtable

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

The description matches the annotations (readOnlyHint=false indicates write operation) and adds that it returns the created record ID and full data. However, it does not elaborate on idempotency (despite idempotentHint=true) or potential side effects, adding limited 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?

The description consists of two concise sentences that succinctly state the tool's purpose and output. No redundant or irrelevant 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 (create record) and presence of output schema and annotations, the description covers the essential behavior and return value. It could optionally mention error handling or authentication details, but current completeness is adequate.

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

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

Input schema description coverage is 100%, so the schema already documents all parameters. The description only generically mentions 'specified field values' without adding syntax, format, or usage tips beyond the schema.

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

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

The description explicitly states the tool adds a new record to an Airtable table with specified field values, clearly distinguishing it from sibling tools like airtable_get_record (read) and airtable_list_records (list).

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

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

The description implies usage when creating a new record but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It lacks 'when-to-use' or 'alternatives' context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds minimal extra transparency. It mentions 'all tables, field names, field types, and configurations', which is slightly more detail but not essential. No additional behavioral context like rate limits or authentication nuances is added.

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, followed by usage guidance. Every sentence adds value, no filler.

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

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

Given the output schema exists, the description need not explain return values. It sufficiently covers the tool's purpose, usage context, and output nature. All necessary information is present for an agent to use this tool correctly.

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

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

Input schema has 100% coverage with descriptions for both baseId and _apiKey. The description does not add any further meaning to the parameters beyond what the schema provides, so 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 'Get the structure of an Airtable base—all tables, field names, field types, and configurations', using a specific verb and resource. It effectively distinguishes from sibling tools like airtable_list_bases and airtable_get_record.

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 second sentence 'Use first to understand available data before querying or creating records' provides explicit guidance on when to use this tool as a preliminary step. It does not mention when not to use, but the advice is clear and useful.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds useful detail about return values (all field values and metadata like timestamps), which goes beyond the annotations without contradicting them.

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

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

Two sentences that are front-loaded with the action and inputs, followed by output details. No redundant information or unnecessary words.

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

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

Given an output schema exists, the description appropriately focuses on the tool's purpose and key inputs. It covers the essential aspects (base, table, record ID, returns fields and metadata) without missing critical details. Could mention error handling but not required.

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

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

Schema description coverage is 100%, so the description adds minimal new information beyond the schema. It mentions the record ID format (recXXXXXXXXXXXX) but does not explain other parameters. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Fetch', the resource 'a single Airtable record', and specifies the key identifiers (record ID, base, table). It distinguishes from siblings like airtable_list_records (which retrieves multiple records) and airtable_create_record.

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

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

The description implies usage when you have a specific record ID, but does not explicitly state when to use this tool versus alternatives (e.g., listing records with airtable_list_records). No direct comparison or exclusions 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 indicate readOnly and idempotent. The description adds that the token must be provided and the output includes base IDs, names, and workspace info, 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?

Two sentences that efficiently convey action, condition, output, and purpose. No superfluous words. Front-loaded with essential information.

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

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

For a simple list tool with rich annotations and a single parameter, the description provides all necessary context: what it does, what it returns, and why to use it. An output schema exists, so return values are detailed separately.

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 one parameter. The description mentions '_apiKey' as token but adds no additional meaning beyond the schema description ('Airtable personal access token'). 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 it lists all accessible Airtable bases, with verb 'list' and resource 'bases'. It distinguishes from sibling tools by explaining the output (IDs, names, workspace info) is used to discover baseId values needed by other Airtable tools.

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

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

The description explicitly states the use case: 'discover baseId values needed by other airtable tools', implying it's a prerequisite. It does not mention when not to use or alternative tools, but among siblings it's the only base-listing tool, so guidance is sufficient.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds value by specifying what is returned (record IDs, field values, metadata), which clarifies the output beyond the annotations.

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

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

The description is a single, front-loaded sentence that is 20 words. Every part is informative: the action, the resource, the optional filtering, and the return content. 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?

Given that the tool has a read-only annotation, a full input schema with descriptions, and an output schema (not shown but present), the description completes the picture by summarizing the action and return. No additional context is necessary.

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 parameters. The description goes beyond the schema by providing an example usage of filterByFormula, which adds practical context. For a schema with full coverage, this is slightly above baseline.

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

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

The description clearly states the verb 'Fetch', the resource 'records from an Airtable table', and the optional filtering capability. It distinguishes itself from siblings like airtable_create_record (write) and airtable_get_record (single record) by being a list operation.

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

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

The description provides clear context on when to use the tool (fetching records with optional formula filtering) and gives a concrete example. It does not explicitly state when not to use or list alternatives, but the context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: default model is free (Workers AI), Anthropic requires a BYO key and direct payment, and _apiKey is passed straight through. This informs the agent about cost and dependency.

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

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

The description is front-loaded with the core action, then explains optional parameters and use cases. Every sentence adds value: defines output, explains default vs paid, and gives examples. No waste.

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

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

The tool has 4 parameters (high schema coverage) and no output schema. The description explicitly states the return format: 'per-model {score, confidence, signals, raw_response} + a combined view.' This is sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining 'entity' as brand/product/topic, 'models' as list with supported values and default, '_apiKey' as optional with condition, and 'context' for disambiguation. This adds value without repeating 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 uses specific verbs and resources: 'probe one or more LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model.' It clearly distinguishes this tool from siblings like compare_entities or scan_competitor_ai_presence by focusing on AI visibility scoring.

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

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

The description provides clear context for usage: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the _apiKey parameter. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant context: it routes to internal tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and handles live news. No contradictory or hidden behavior is omitted.

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

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

The description is longer than average but densely packed with actionable guidance. It front-loads the 'PREFER OVER WEB SEARCH' directive and includes examples that directly aid usage. Some redundancy exists (repeated mentions of 'current or historical data'), but each sentence contributes 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 tool with no output schema, the description covers return format, data domains, alternative tools, and use-case triggers. It fully equips an agent to decide when to invoke this tool and what to expect from the result, making it complete despite the lack of a structured output definition.

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

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

Schema coverage is 100% with aliases clearly documented. The description adds value by providing example questions and trigger phrases ('what is', 'look up', 'find') that help agents formulate the question parameter, going beyond the basic schema description.

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

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

The description clearly states the tool routes questions to one of 5,344 tools across verified sources, fills arguments, and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning as the default entry point.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', provides alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), and gives trigger phrases and concrete examples. This is exemplary usage guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses that candidate routing improvements may be enabled live, that currently no candidate is active (with a specific retirement date), and that it is a fully working router despite being experimental. This adds behavioral context not present in 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 compact and front-loaded, starting with the core purpose ('Beta version of ask_pipeworx'), then covering current state, usage, and the fallback behavior. Every sentence contributes to understanding the tool without redundancy.

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

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

Given the lack of an output schema, the description compensates by specifying 'same response shape' as ask_pipeworx. It covers the tool's identity, current experimental status, usage, and reassures that it is a complete working router. This is sufficient for a tool with rich annotations and clear sibling context.

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

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

The input schema has 100% description coverage, documenting the 'question' parameter and five aliases. The description adds no additional parameter semantics beyond saying 'same arguments' as ask_pipeworx, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,344 tools. It explicitly states it has the same tools, arguments, and response shape, and distinguishes it from the stable ask_pipeworx and ask_pipeworx_grounded siblings by noting it is the experimental edge.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the experimental context and that results are compared against the stable router, implying the alternative is to use ask_pipeworx for stable routing.

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

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

Adds substantial behavioral context beyond annotations: refusal behavior with refusal_reason enum, grounding constraint 'using ONLY what the tool result contains', and cost overhead. No contradiction with annotations. The description fully discloses success and failure modes.

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

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

The description is longer than average but every sentence earns its place: purpose, mechanism, return format, refusal cases, use cases, and cost trade-off. It is front-loaded with the core value proposition ('Hallucination-resistant answer mode') and flows logically.

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

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

No output schema exists, yet the description comprehensively documents the return shape for both success and refusal, including specific refusal_reason values. It also covers when to use, cost comparison, and grounding behavior, making it complete for a high-stakes tool.

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

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

Schema coverage is 100% with parameter descriptions for question and all aliases. However, the description adds no parameter-specific semantics beyond what the schema already provides, so 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?

Description clearly identifies the tool as a 'hallucination-resistant answer mode' with a specific verb ('extracts') and resource ('answer'). It explicitly contrasts with sibling ask_pipeworx by detailing the routing and extraction process, making tool selection unambiguous.

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

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

Provides explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete domains. Also names the alternative (ask_pipeworx) and rationalizes preference based on cost, giving clear decision criteria.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, confirming safe, non-destructive behavior. The description goes far beyond annotations, detailing edge cases: low-confidence resolutions short-circuit with status, closed/dead markets return status, wide-spread markets carry tradeability note, and cancellation rules. 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 very long (multiple paragraphs) and covers extensive detail. It is well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), but could be more concise. Some redundancy exists, e.g., the fan-out examples are repeated in different contexts.

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

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

Despite no output schema, the description thoroughly explains response fields (result.market, result.analysis, result.evidence), resolver contract (market_match_confidence, alternatives), parent event extractor, news fields with fallback details, and safety mechanisms (short-circuit, blocking routes). All edge cases and user concerns are addressed.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It clarifies that 'market' can be a slug, URL, or question text; 'depth' (quick vs thorough) is explained with default; 'include_raw' includes size implications and when to use. The examples provide concrete usage context.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). The scope is well-defined, and the tool is distinct from siblings like polymarket_edges or polymarket_arbitrage.

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

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

Explicit when-to-use guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Examples of classifiers and fan-outs further clarify contexts. However, no explicit when-not-to-use or alternative tools are mentioned, though the description implicitly suggests its primary role.

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) are present, and the description adds substantial behavioral context: it's a single parallel call, returns paired data with citation URIs, and details data sources per entity type. 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 moderately concise, front-loaded with example queries. Every sentence contributes value, though it could be slightly tighter (e.g., the explanation of fiscal year handling is useful but verbose).

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

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

Given the tool's complexity (two entity types, multiple data sources), the description covers the key aspects: input constraints, data sources, sort behavior, and output format (paired data with URIs). Lacks details on response structure but sufficient for most agents.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema by explaining the behavior of each type ('company' pulls financial data, 'drug' pulls FAERS counts) and giving concrete examples for values.

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

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

The description uses specific verbs like 'compare', 'side-by-side comparison', and lists example queries, clearly distinguishing it from sequential lookups. It identifies the resource (companies/drugs) and the scope (2-5 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. However, it doesn't specify when NOT to use it (e.g., if only one entity needed).

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 reveals extensive behavioral traits beyond the annotations: it 'never invented' answers, returns gaps[] and contradictions[], performs 'gap recovery' and 'second-hop iteration,' semantically excerpts large records, and has performance expectations (15-60s). This complements and enriches the readOnlyHint/openWorldHint 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 dense and front-loaded but somewhat long, packing in account details, mechanics, output structure, and performance. Every sentence carries useful information, but the single-paragraph format and inclusion of signup URL details slightly reduce scannability. Still, it is efficiently written with near-zero waste.

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

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

Without an output schema, the description fully explains return values: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding,' plus gaps[], contradictions[], and hop fields. It also covers edge cases (e.g., breaking news yielding empty gaps) and depth behaviors, making it self-sufficient 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?

Though the schema covers both parameters, the description adds meaning by explaining depth tiers in behavioral terms ('quick=3 (single hop)', 'standard=5 (default; adds a gap-recovery hop...contradictions[] scan)', 'thorough=8 (paid; adds a full iterative hop...)') and how the question should be phrased ('Broad/multi-part is fine'). This goes beyond mere schema definitions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources' that 'decomposes your question into focused facets' and 'returns a findings packet.' It explicitly distinguishes itself from siblings by being a multi-tool parallel research orchestrator, not a single lookup or open-web 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?

Usage guidance is explicit with when-to-use and when-not-to-use: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also explains depth-tier selection and account requirements, giving clear decision criteria.

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

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

Annotations already indicate readOnly=true, idempotent=true, destructive=false. The description adds valuable behavioral context: it returns top-N relevant tools with names, descriptions, full schemas, and curated examples, and notes that each result is ready to call without a second lookup. No contradictions with annotations.

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

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

The description is a single paragraph but front-loads the purpose and key usage. It is dense yet clear, with no redundant sentences. Could be slightly more structured with bullet points, but it is well-written and efficient for its length.

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

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

Given no output schema, the description adequately describes the return value (names, descriptions, schemas with examples). It covers when to use, what domains it covers, and that results are callable directly. The long list of example domains adds completeness. The description is sufficient for a discovery tool with these context signals.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor value by confirming that 'task', 'q', 'search', and 'description' are aliases for 'query', which the schema already indicates. The 'limit' parameter's default and max are also stated in the schema. No significant additional semantics.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the action (find/browse/search/discover) and resource (tools). It also distinguishes from siblings by explicitly noting to call this FIRST when you need to see the option set, implying it is not for executing specific tasks like its siblings.

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

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

The description provides clear when-to-use scenarios: 'Use when you need to browse, search, look up, or discover what tools exist for: [list].' It also advises to 'Call this FIRST when you have many tools available and want to see the option set.' It does not explicitly state when not to use it, but the guidance is strong enough to infer exclusion criteria.

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

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

Annotations already declare read-only and non-destructive. The description adds valuable context: fans out across multiple sources, returns specific fields, includes caveat about patents sunsetting (soft-fails), and mentions fallback for news. 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?

Relatively long but well-structured, starting with example queries, then purpose, then details. Every sentence adds value. Could be slightly tighter, but complexity justifies length.

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

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

No output schema, so the description must explain returns. It covers all major return categories (CIK, filings, fundamentals, patents, news, LEI) with caveats. Lacks details on error handling, but complete for a profile tool.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description reaffirms the name limitation and gives examples, but doesn't add new meaning beyond the schema. Baseline score appropriate.

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

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

The description clearly states it produces a full cross-source profile of a US public company, with specific examples like 'tell me about X' and 'company profile for Microsoft'. It 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?

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also specifies when not to use: if only have a name, use resolve_entity first. Provides clear context.

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

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

Annotations provide destructiveHint=true and idempotentHint=true. The description adds context about why to delete (stale context, done tasks, sensitive data), which is beyond the annotations. No contradiction noted.

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 waste. The first sentence states the core action, and the second provides usage context and sibling relationships. 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 tool with one parameter and clear annotations, the description is complete enough. It covers purpose, usage, and relationships to remember/recall. No output schema exists, so no need to explain return values.

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

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

Schema coverage is 100% with a description for the 'key' parameter. The description does not add extra meaning beyond the schema's 'Memory key to delete', so baseline of 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key, using the verb 'Delete' and the resource 'memory'. It distinguishes from siblings by mentioning 'Pair with remember and recall', clarifying its role in the memory triad.

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 usage scenarios: when context is stale, task is done, or to clear sensitive data. Does not explicitly state when not to use, but the positive guidance is clear and sufficient for most 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, openWorldHint, idempotentHint=true, and destructiveHint=false. The description adds valuable context: fetching the page, extracting title/description/links, emitting markdown format, and output placement. No contradictions. Could mention error handling 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 sentences: purpose, process, use cases. Front-loaded with main action, no unnecessary words. Each sentence serves a distinct role.

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 two parameters, no output schema, and rich annotations, the description covers key aspects: what it generates, how it works, and output format. Could include caveat about URL accessibility or size limits, but sufficient for typical 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% with clear descriptions for both parameters (url, max_links). The description does not add parameter-level details beyond what schema provides, so baseline score of 3 is appropriate. Contextual framing (e.g., 'maximum number of link entries') adds minimal value.

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

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

States specific verb 'generate', resource 'llms.txt file', and target audience 'AI crawlers (ChatGPT, Claude, Perplexity)'. Clearly differentiates from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on a specific file format generation.

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

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

Explicitly lists three concrete use cases: indexing client sites, drafting for own project, auditing competitors. Does not explicitly state when not to use or mention alternatives, but the context is clear and actionable.

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

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

Annotations already declare safety (readOnly, idempotent). Description adds value by specifying return fields and caller scoping, beyond what annotations provide.

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

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

Two concise sentences with no wasted words, front-loaded with core 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?

Given the simple tool (1 optional param, no output schema, strong annotations), description is fully complete: what, returns, when to use, and parameter behavior.

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

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

Schema coverage is 100% and the parameter description in schema is adequate. Description adds no new semantics beyond noting default behavior, so baseline 3.

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

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

Description clearly states it lists active subscriptions and enumerates returned fields. It distinguishes itself from siblings like subscribe/unsubscribe, though not explicitly naming 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?

Description recommends using the tool to review monitoring before adding more or to find an id to cancel, providing clear usage context. It implicitly contrasts with subscribe/unsubscribe.

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

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

The description discloses key behaviors beyond annotations: it is rate-limited (5 per identifier per day), free, and does not count against tool-call quota. It also mentions that the team reviews digests daily and feedback affects the roadmap. No contradictions with annotations (readOnlyHint=false, destructiveHint=false).

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

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

The description is concise yet comprehensive, using six well-structured sentences. Each sentence serves a purpose: stating the action, listing use cases, providing formatting rules, explaining impact, noting rate limits, and clarifying cost. Information is front-loaded with the main 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 simplicity (no output schema needed), the description covers all necessary aspects: purpose, usage scenarios, parameter guidance, and behavioral traits. It is complete for an AI agent to understand when and how to invoke the tool correctly.

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

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

The input schema has 100% description coverage, but the description adds value by providing usage context for parameters, especially for the 'message' field (recommending 1-2 sentences, 2000 char max) and explaining the enum values for 'type' in detail. 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the types of feedback (bug, feature, data_gap, praise) and provides context for when to use each. It uniquely serves as a feedback channel, distinct from sibling tools which are functional tools.

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

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

The description explicitly states when to use the tool: for bugs, feature requests, data gaps, or praise. It provides guidance on how to structure feedback (describe in terms of Pipeworx tools/packs, avoid pasting prompts). It does not specify when not to use it, but the positive usage is well-covered.

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 (readOnly, idempotent, not destructive). Description adds significant detail: self-aggregating from analytics engine, no PII, cached 5min-1h, and what data is returned. This greatly exceeds annotation coverage.

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

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

Description is front-loaded with the core purpose, then lists use cases, then adds behavioral notes. Every sentence adds value with no repetition or fluff.

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

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

Given the tool's simplicity (1 optional param, no output schema, rich annotations), the description fully covers what an agent needs: what it returns, when to use it, caching behavior, and data source. Nothing is missing.

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

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

Schema has 100% coverage with enum descriptions. Description adds contextual meaning: shorter windows for 'hot right now', longer for 'steady-state demand'. This adds value beyond the schema's enum listing.

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 what the tool returns (top tools, top packs, call volume) and provides three specific use cases. No sibling tool duplicates this functionality, making the purpose distinct.

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

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

Explicitly lists three scenarios for using the tool (discovering hot data, confirming canonical tool, aligning use case). Does not explicitly mention when not to use it, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with a read-only analysis tool. Description adds rich behavioral details: monotonicity checks, partition filter, semantic anchor, fill check with live CLOB depth. 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 verbose but well-structured: front-loaded with purpose, then mode details, then technical filters, response, and fill check. Every sentence adds value, though some redundancy exists (e.g., 'Cross-event mode catches...' repeats earlier point). Still, clarity benefits from thoroughness.

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 and two parameters, the description covers input modes, behavioral details, response structure, and trade execution criteria. References sibling for custom sizing. No gaps identified; agent has enough context to select 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% but description adds substantial meaning: explains event slug format with examples, topic as seed question, and details on modes. Goes well beyond baseline 3 by providing practical usage context and constraints.

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

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

Description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) with specific verbs and resources. No ambiguity with sibling tools like polymarket_edges or 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: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Also warns when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing. Covers when to use and 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?

The description adds substantial behavioral context beyond annotations. It details model families, cache behavior (cached 1h), edge calculation (net of slippage), and output structure (by_segment, diagnostics). It describes the Fed signal limitation and knob effects. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is verbose and contains multiple paragraphs of technical detail (model formulas, knob explanations). While informative, it lacks conciseness; an agent may need to parse dense text. Front-loading is present (first sentence states purpose), but subsequent details could be streamlined.

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

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

Despite no output schema, the description covers return structure (by_segment, diagnostics), cache behavior, and edge attributes (edge_pp_net, kelly_fraction, liquidity, spread, volume). It explains why Fed bets are excluded (unreliable signal) and how knobs affect results. This is comprehensive for a complex tool with 9 parameters.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains the purpose of knobs (e.g., 'Tradeable-edge filter' for max_spread_pp and min_liquidity), provides example values (e.g., 5000 for min_liquidity), and clarifies interactions (e.g., min_partition_leg_kelly applies to partition arbs where min_kelly doesn't).

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 ('scan', 'return') and resources ('Polymarket markets', 'opportunities where Pipeworx data disagrees with market price'). It clearly distinguishes from siblings by describing unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) not present in siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 tool is for discovering betting opportunities ('what should I bet on today') and provides context for when to use it (e.g., to avoid paging hundreds of markets). It implies exclusions (Fed bets are excluded from ranking due to unreliable signal) but does not explicitly mention alternatives. While clear, it lacks explicit when-not guidance.

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

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

Annotations indicate read-only and idempotent behavior, which the description consistently supports. The description adds significant behavioral details: data comes from daily snapshots, gaps occur when polymarket_edges doesn't run, decay is computed from daily closes, and limits like 60-day TTL. This exceeds annotation content.

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

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

The description is front-loaded with the core purpose but then becomes dense with response structure details. While informative, it could be more concise by separating response format into an output schema or a separate note. Currently, it reads as one long block, reducing scannability.

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 absence of an output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and their semantics. It also covers limits (history depth, decay computation). This provides sufficient context for an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100%, with both parameters described. The description adds some context (defaults, valid values for window) but does not provide substantial meaning beyond the schema. Baseline is 3 for full schema coverage.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific analytical question ('how long has this edge existed and is it shrinking?'), distinguishing it from sibling tools like 'polymarket_edges' (likely raw data) or 'polymarket_arbitrage' (specific strategy analysis).

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

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

The description implies when to use this tool (for analyzing edge persistence and decay trends) but does not explicitly state when not to use it or list alternative tools. It provides context about history depth and snapshot TTL, which helps set expectations. The purpose is well-defined, but clearer exclusion criteria would improve score.

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, indicating safety. The description adds behavioral detail: it walks the order book ladder, returns fill quality metrics, and warns about directional risk from partial fills. 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 verbose but well-structured: it starts with the core requirement, then details each mode with return fields, and ends with usage guidance. Every sentence adds value, and the structure supports quick scanning. 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?

With no output schema, the description must cover return values, and it does: it lists fields like top_of_book, vwap_fill_price, slippage_pp, verdict, etc., for both modes. It also explains the verdict categories and warns about thin legs and directional risk. An agent has enough context to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value: it explains the dual purpose of size_usd (buy spend vs sell proceeds for single-market; settlement notional for basket), clarifies the side default (auto for basket), and distinguishes market vs event parameters. This goes beyond the schema to explain behavior.

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and differentiates between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, stating when to use this tool before them.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about risks of partial basket fills, giving enough context for when to use. It does not explicitly list exclusions for small trades but implies a threshold.

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 and idempotentHint, which the description does not contradict. The description adds rich behavioral context: it explains safety fields (compatibility_warning, temporal_alignment, skipped counters), the meaning of top_spreads_pp, and when spreads are meaningless. This exceeds annotation coverage.

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

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

The description is informative but somewhat lengthy. It is well-structured: purpose first, then modes, then response details, then safety fields. Every sentence adds value, but a slight trimming could improve conciseness. Still above average.

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 absence of an output schema, the description explains the response fields (leg-by-leg prices, top_spreads_pp, safety fields) sufficiently for an agent to interpret results. It covers edge cases (temporal alignment, mismatched bet shapes). However, a few specifics like the exact JSON structure are omitted, which could be inferred.

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

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

Schema coverage is 100% and each parameter has a description. The topic parameter's enum values are explicitly listed in the description, and the override behavior of kalshi_event_ticker and polymarket_event_slug is clarified. Examples in schema complement the description.

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

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

The description specifies a concrete verb-resource pair ('cross-venue spread') and clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on the Kalshi-Polymarket comparison. It explicitly states two modes and the goal of identifying price differences.

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

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

The description provides explicit when-to-use guidance (e.g., to find spreads, for macro topics or custom pairs) and when-not-to-use warnings (e.g., compatibility_warning cases, temporal misalignment). It even cautions that most pre-mapped topics are not tradeable, setting realistic expectations.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping details (by identifier), 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?

Two sentences: first states action, second provides guidelines and pairing. 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?

Complete for a read tool with good annotations: explains return behavior, scoping, and relationship to siblings.

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

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

Schema covers 100% of parameters, but description adds clarity on omitting key to list all, enhancing understanding beyond schema.

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

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

Clearly states it retrieves a saved value or lists all keys, distinguishes 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?

Explicitly describes when to use: recall previously stored context, with examples like ticker or notes, and mentions pairing with remember and forget.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds details: mark_read side-effect (flags events read), returned fields, polling suitability, and alternative endpoint. No contradictions. Adds 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?

Three sentences, each essential: purpose and return fields, filtering, mark_read effect, alternative access. Front-loaded, 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?

Returns structure described, filtering and read-state behavior explained, alternative endpoint mentioned. Lacks description of unread_only parameter, but otherwise complete for a medium-complexity tool with no output schema.

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

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

Schema coverage is 100%; description adds context for type (example value), since (fired_at >=), and mark_read effect. However, limit and unread_only are not described beyond schema. Baseline 3 with minimal added value.

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 pulls fired events from subscription feed, returns specific fields (source, citation_uri, raw event payload), and describes filtering options. Differentiates from sibling tools which cover Airtable, research, subscriptions, etc., none of which overlap with recent alerts.

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

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

Provides clear context for usage: filter by type and/or since, manage read state with mark_read, polling is appropriate, alternative HTTP endpoint available. No explicit 'when not to use' guidance, but no direct sibling tools, so implicit usage is sufficient.

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

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

Discloses fan-out behavior to multiple sources, fallback logic for GDELT->GNews, soft-fail for USPTO, and return format with grouped changes and citation URIs, going 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?

Dense but efficient single paragraph front-loads purpose and examples; all sentences contribute value, though could be slightly restructured for easier scanning.

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

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

Comprehensive for a complex tool without output schema; covers multiple data sources, error handling, and return structure, leaving no major gaps.

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

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

Schema descriptions are clear; description adds examples of relative shorthand for 'since' and explains sources, enhancing understanding beyond 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 it provides a change feed for a company over a specified window, aggregating from multiple sources. Distinguishes from sibling tool 'entity_profile' by specifying when to use each.

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

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

Explicitly provides example queries showing when to use, and directs to 'entity_profile' for static profile, clarifying when NOT to use this tool.

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

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

Discloses key-value scoping, persistence details (auth vs anonymous), and idempotency hints. No contradiction with annotations; annotations only hint at idempotent and non-destructive, and description aligns.

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

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

Three concise sentences. First sentence states core purpose, second adds usage guidance, third provides behavioral detail. No wasted words.

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

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

Despite no output schema, the description fully explains what the tool does, how to use it, and its behavior. For a simple key-value store, this is complete.

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

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

Schema already covers both parameters fully (100% coverage). Description adds usage examples and naming conventions, providing extra value beyond schema descriptions.

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

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

The description uses specific verbs ('Save data') and resources ('across this conversation or across sessions') with concrete examples (ticker, address, preference). It clearly distinguishes from sibling tools recall 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?

Explicitly states when to use ('discover something worth carrying forward') and pairs with recall/forget. Provides clear context for invocation.

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

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

Discloses internal cascading behavior ('Each call cascades through several lookup endpoints internally') and efficiency benefit ('replaces 2-3 manual lookups'). Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and description adds valuable context without contradiction.

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

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

Description is front-loaded with examples and guidance. Every sentence is useful, though slightly verbose with the 'replaces 2-3 manual lookups' statement which could be integrated. Overall efficient for the detail provided.

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

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

Covers all key aspects: purpose, usage scenario, supported types, return values (ticker, CIK, RxCUI, etc.), and internal behavior. Without output schema, description adequately explains what the agent can expect. Context is complete for a lookup 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. Description adds meaningful examples for each type (e.g., 'ticker (AAPL), CIK (0000320193), or name') and clarifies auto-disambiguation for company type. This adds value beyond the schema.

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

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

Description clearly states resolve name to canonical identifier with specific examples (ticker, CIK, RxCUI). Explicitly says 'Use FIRST whenever you have a name but need an ID', distinguishing it from sibling tools like entity_profile or compare_entities that likely consume these IDs.

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

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

Provides clear guidance on when to use ('Use FIRST whenever you have a name but need an ID') and lists supported types with return values. Could be more explicit about when not to use (e.g., if you already have an ID), but context strongly implies that.

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

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

The description adds behavioral context beyond annotations, explaining that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also mentions the need for an _apiKey if using the anthropic model. 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?

Three well-structured sentences: purpose, usage example, output description. Front-loaded with the core action and efficiently written without waste.

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

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

Given the complexity (4 params, no output schema), the description adequately covers the process and return fields. It could mention the entity count limit (2-8) but that is already in the schema parameter description. Overall sufficient for the tool's purpose.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the process (probing, ranking) and output fields (score, confidence, signal density), and clarifying that the first entity is the subject.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It uses a specific verb ('scan' + 'compare') and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (more generic).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use the tool or directly compare to alternatives like compare_entities, though the context is clear enough.

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

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

The description goes beyond annotations (readOnlyHint, etc.) by disclosing behavioral traits: it fans out to two services, returns specific fields, notes that bundlephobia's first measurement can take 5-30s, and mentions graceful degradation with partial failures. 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 appropriately sized and well-structured: it front-loads the main purpose, then details return values, ecosystem notes, and failure behavior. Every sentence provides necessary information without redundancy.

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

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

Despite lacking an output schema, the description fully lists return fields (summary block, advisories, links, alternative versions) and covers edge cases like partial failures and timeouts. It provides sufficient information for the agent to understand the tool's behavior and return format.

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

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

Schema coverage is 100%, so the description adds value beyond the schema by clarifying that version defaults to latest and scoped packages are accepted. This provides helpful context not present in 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's purpose: a composite check for adding an npm package, with specific verbs ('fans out', 'returns') and resources (deps.dev, bundlephobia). It distinguishes itself by focusing on npm ecosystem and combining multiple checks in one call, differentiating from other scanning tools.

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

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

Explicit guidance is given on when to use: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'.' It also provides a when-not-to-use example: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' clarifying alternatives for other ecosystems.

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 valuable behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. This goes beyond what annotations offer.

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

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

Two efficient sentences that are front-loaded with the core action. No wasted words—every sentence adds value (purpose, use case, technical 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?

Despite no output schema, the description covers return format (top-N passages with character offsets and similarity scores) and technical constraints. With 3 params and no output schema, this is sufficiently complete for the complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context beyond schema: examples for 'query', default value for 'limit', and max length for 'text'. This provides meaningful extra information.

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

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

The description clearly states 'Semantic search INSIDE a fetched record', using a specific verb and resource. It distinguishes from siblings like ask_pipeworx_grounded by explaining the pairing and different use case.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Also provides a clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Description contradicts the idempotentHint=true annotation. 'Create a subscription' and 'Returns the new subscription id' imply each call creates a new resource, which is not idempotent. Annotations promise idempotency, creating confusion.

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

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

Description is well-organized with front-loaded purpose, then requirements, types, and delivery details. Somewhat lengthy but justified by complexity; no wasted sentences.

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 covers return value, auth requirements, type-specific parameters, delivery channels with constraints, and idempotency contradiction aside, it provides all necessary context for a subscription creation tool.

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

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

Schema coverage is 100%, and description goes beyond with concrete examples, structure, constraints (e.g., 10/day SMS cap), and additional details like webhook HMAC signing.

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

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

Description clearly states the verb 'Create', the resource 'proactive monitoring subscription', and the return of a subscription ID. It distinguishes from sibling tools like list_subscriptions 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 clear context: requires Pipeworx OAuth account, lists supported types with examples, and mentions delivery options and constraints (phone verification, daily cap). Does not explicitly state when not to use or alternatives, but context is adequate.

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, and destructiveHint. The description adds the crucial detail that results are 'category-bucketed example questions... each with the exact tool + argument shape that answers it' and that they come from a live catalog of thousands of tools, enhancing understanding of the tool's dynamic behavior.

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

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

The description is a single paragraph that efficiently includes common user queries, purpose, output details, parameter usage, and advice. Every sentence adds value, and the structure front-loads the most important information about what the tool does and when to use it.

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 optional param, no output schema), the description fully covers what it returns (category-bucketed example questions with tool + argument shape), how to use it (with or without topic), and its role as an onboarding entry point. No gaps remain for an agent to understand its function.

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 one optional parameter described. The description adds the list of possible topic values ('finance, pharma, economics, real-estate, betting, weather, government, science, news') beyond the schema's generic description, and explains the behavior when omitted ('full spread'), providing significant added meaning.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses multiple user queries to signal its role and distinguishes itself from siblings like ask_pipeworx and entity_profile by being the first step for learning what Pipeworx can do.

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

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

The description explicitly tells when to use this tool first ('Use this FIRST when you do not yet know what Pipeworx can do for you') and how to call meta-tools. It also explains the optional topic parameter and the full spread without it, providing clear context for decision-making.

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

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

Description discloses soft-delete behavior ('deactivated not deleted') and that historical events remain available via 'recent_alerts', adding value beyond annotations. Ownership enforcement is also stated.

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 zero wasted words. Every sentence conveys essential information: action, ownership, id requirement, and behavioral outcome.

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 single-parameter tool with no output schema and clear annotations, the description fully covers all necessary context: what, who (ownership), and effect (deactivation vs deletion).

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

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

Only one parameter 'id' with full schema coverage. Description adds that the id is 'returned by subscribe', which provides useful context but does not significantly extend beyond the schema definition.

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 'Cancel a subscription by id' with a specific verb (cancel) and resource (subscription), clearly distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. Ownership enforcement adds precise scope.

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

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

Ownership condition ('you can only cancel your own subscriptions') is clearly stated, but no explicit when-not-to-use or alternative tool references. The context is clear enough given sibling names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: the two routing paths (SEC EDGAR vs grounded pipeline), the verdict types (confirmed, etc.), and the use of exact percent-delta math. 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 relatively long but well-structured, front-loading example phrases and clarifying the routing logic. Every sentence adds value, though minor redundancy could be trimmed.

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

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

Given the tool's complexity (two pipelines, multiple verdict types, integration with external sources) and lack of output schema, the description covers all key aspects: input examples, routing logic, return values (verdict, value, reasoning), and citation format. It is complete and self-contained.

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

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

Schema coverage is 100%, with both parameters described. The description adds value beyond the schema by explaining that tolerance_pct overrides the claim's implied tolerance and defaults to 5, and provides concrete examples for the claim parameter.

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

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

The description starts with natural-language examples ('Is it true that...', 'fact check') and clearly states the tool's purpose: claim verification against authoritative sources. It distinguishes itself from siblings by detailing the routing to structured SEC data vs. grounded pipeline, and notes it replaces multiple sequential calls, making its role unique among sibling tools like deep_research or ask_pipeworx_grounded.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates between company-financial claims and other factual claims. It implies when not to use by outlining alternatives in sibling tools, but lacks explicit exclusions or when-not-to-use guidance.

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