Data Piercecounty

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds operational details: default model (free), optional Anthropic probing with BYO key, and return structure. No contradictions, but lacks info on rate limits or failure 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?

Four sentences: purpose, model details, return format, use cases. No fluff, every sentence adds essential information. Front-loaded with the 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?

With no output schema, description covers key return fields (score, confidence, signals, raw_response, combined view). Could detail the combined view structure, but overall adequate for a 4-parameter tool with clear annotations.

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

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

Schema description coverage is 100%. Description adds value by explaining default model behavior, cost implications of _apiKey, and that entities can be brand, product, person, or topic. This enriches understanding beyond schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model, with a specific verb ('probe') and resource ('LLMs for business/brand/product/topic'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring.

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

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

Explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Does not specify when not to use or differentiate from similar sibling tools, but context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds meaningful behavioral context beyond annotations: internal routing across thousands of tools, automatic argument filling, coverage of both current and historical data, and the stable pipeworx:// citation URI return format. No contradiction with the annotations — a read-only answer-generation profile is consistent throughout.

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 most important directive ('PREFER OVER WEB SEARCH') and each section earns its place: scope, mechanism, triggers, examples. However, the phrase 'even if web search could also answer it' appears twice, and the repeated ALL-CAPS directives ('PREFER', 'START HERE') add mild redundancy, preventing a 5.

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

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

For a tool with one required parameter, no output schema, and rich annotations, the description covers the essentials: when to use it, what it does internally, and what the agent can expect back ('structured answer with stable pipeworx:// citation URIs' — important since there is no output schema). It omits failure modes, latency expectations, and sibling differentiation, but nothing an agent needs to invoke it correctly 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 coverage is 100% — the schema fully documents 'question' and its five aliases. The description adds value by illustrating acceptable parameter values: trigger phrases and seven concrete example questions ('current US unemployment rate', 'Apple's latest 10-K', 'patents Tesla was granted last month'). This tells the agent what kind of natural-language input belongs in the parameter beyond the schema's generic 'Your question or request in natural language.'

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

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

The description states a specific mechanism: 'Routes the question to the right one of 5,798 tools across 1517 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This is a concrete verb+resource+behavior statement that leaves no ambiguity about what the tool does, and it explicitly contrasts with web search ('PREFER OVER WEB SEARCH'). The tool's role as a factual-answer router is unmistakable.

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

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

Exceptional when-to-use guidance: a domain list (SEC filings, FDA data, FRED/BLS, patents, weather, clinical trials, etc.), trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and a strong preference directive ('even if web search could also answer it') with concrete examples. It lacks exclusions or differentiation among close siblings like ask_pipeworx_beta, ask_pipeworx_grounded, and deep_research, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat safety traits. The description adds valuable live behavior context: it is a candidate-testing edge, currently matches stable exactly, and results are compared against the stable router — context an agent cannot get from annotation fields.

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 but information-dense: it defines what the beta is, states its current exact equivalence, gives invocation guidance, and notes the comparison purpose. Every sentence earns its place and the most decision-relevant facts come first.

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 schema, full parameter coverage, and safety annotations, the description covers what an agent needs to call the tool correctly. The only gap is that it doesn't speak to the output/response shape, but no output schema exists and the description states the same response shape as ask_pipeworx, which is reasonably sufficient.

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

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

Schema coverage is 100% and the schema itself names the single required parameter question with four documented aliases. The description repeats identical/universal arguments but adds no semantic detail beyond the schema. Baseline 3 is appropriate given full 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 identifies this as a beta variant of ask_pipeworx with the same universal routing behavior, and explicitly states it is currently identical because no candidate is active. It distinguishes itself from the stable sibling by being the experimental edge, so an agent can tell it apart from ask_pipeworx and 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 says to use it exactly like ask_pipeworx when you want the newest routing, and clarifies it is a full working router rather than a fallback or stub. This provides concrete when-to-use guidance relative to its primary sibling.

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 refusal behavior with enumerated refusal_reason values, evidence as a verbatim quote, confidence, source, fetched_at, and the extra LLM call cost. These go well beyond the annotations (read-only, open-world, idempotent, non-destructive) and match them, so there is 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 dense but every sentence earns its place: purpose, routing, success/refusal output shapes, high-stakes use cases, and the cost tradeoff vs ask_pipeworx. The core distinction is front-loaded, and there is no redundant verbiage.

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 fully documents the return shape, including success and refusal variants with specific refusal_reason values. It also covers usage context, cost implication, and behavioral guarantees, making it complete for an agent to decide when to use the tool and what to expect.

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

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

The input schema has 100% coverage and fully documents the single required 'question' parameter and its aliases, so the description does not need to add parameter-level detail. The description adds no new constraints or formats beyond the schema, which is acceptable given the high 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 names a specific behavior: a hallucination-resistant Q&A mode that extracts answers only from fetched tool results, with an explicit refusal path. It also contrasts with the sibling ask_pipeworx by noting the extra LLM call cost, making differentiation immediate.

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

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

It provides explicit when-to-use guidance: whenever answers will be quoted, cited, or acted on and fact invention is unacceptable, with concrete examples (financial, legal, medical, public statements). It also states the inverse, preferring ask_pipeworx for casual lookups, giving clear 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses resolver contract, parent event extraction, news fallback behavior, cancellation rule risk, and blocking conditions. This far exceeds what annotations provide, ensuring the agent understands behavioral traits.

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

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

The description is well-structured with sections and bullet points, front-loading the purpose. It is somewhat long due to the tool's complexity, but every part contributes useful information. A slightly more concise phrasing could improve 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 complexity (classifiers, fan-outs, response shapes, resolver contract, edge cases), the description is remarkably complete. It covers low-confidence matches, closed markets, wide spreads, resolution rules, and cancellation risk. No output schema exists, so the description compensates thoroughly.

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

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

Schema coverage is 100%. The description adds significant meaning: market can be slug, URL, or text; depth enum explained; include_raw describes when to use true/false. Examples and behavior details go beyond the schema.

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

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

The description clearly states it researches Polymarket bets by pulling Pipeworx data. It lists specific inputs (slug, URL, question text) and outputs (evidence packet + comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, which overlap in purpose.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers when not to use via safety mechanisms (low-confidence resolutions, closed markets, wide spreads). No explicit alternative tools are named, but the context is complete.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies with correct fiscal year handling, FAERS for drugs), sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is well-structured with front-loaded examples and purpose. It is slightly verbose but every sentence adds value. Could be more concise but remains clear.

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

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

Despite no output schema, the description explains the return structure (paired data + citation URIs). It covers both entity types, data sources, sorting behavior, and the efficiency gain over sequential lookups. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds meaning beyond schema by explaining what the values parameter expects (tickers/CIKs for company, names for drug) and what the type parameter controls (data source and metrics).

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

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

The description uses specific verb+resource (compare entities) and provides clear examples of invocations. It distinguishes itself from sibling tools by explicitly stating 'ALWAYS PREFER over sequential single-pack lookups when comparing 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?

The description gives explicit guidance on when to use this tool (comparing 2-5 entities) and what it replaces ('Replaces 8–15 sequential lookups'). It also explains the behavior for different types (company vs drug).

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 context about return fields (resource_id, name, description, category, update date) which is helpful but does not contradict annotations. It lacks details on sorting, rate limits, or error conditions.

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

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

Single sentence, front-loaded with action and resource, no fluff. Every element earns its place, efficiently conveying purpose and output.

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

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

Given 3 parameters, no output schema, and annotations providing safety context, the description is fairly complete. It covers the tool's operation and output format, though it could mention pagination defaults or result ordering. Lacks nothing critical for basic 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 description coverage is 100% with clear parameter descriptions. The description does not add extra semantic meaning beyond the schema; it only reiterates keyword search and mentions return fields which are not parameter-specific. Baseline score of 3 is appropriate.

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

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

Description clearly states verb ('Search'), resource ('Pierce County Open Data catalog'), and scope ('by keyword'). It distinguishes from siblings by specifying the exact catalog source and the return fields, making it 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?

Description implies usage for keyword search and hints at chaining with 'query/metadata' tool via resource_id. However, it does not explicitly state when to use this tool over alternatives or when not to use it. With sibling tools being diverse, this is adequate but not exceptional.

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 readOnly/openWorld/idempotent annotations, the description discloses contract requirements (account, paid tier), latency expectations, the findings packet structure, gap[] behavior, contradiction detection, stable resolvable citations, semantic excerpting instead of head-truncation, and the iterative multi-hop nature. This is unusually full behavioral disclosure for a tool with annotations already covering safety hints.

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

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

The description is long and dense, but nearly every clause carries unique operational information, and it is structured with clear separators and parentheticals. It is not as front-loaded as it could be — the account-required notice precedes the core purpose — but the density is justified given the tool's complexity and the absence of an output schema.

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

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

Despite having no output schema, the description fully describes what the agent will receive: a findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, hop field, gaps[], contradictions[], and semantic excerpting. It also covers account/auth requirements, latency, depth semantics, and exclusions (single lookups and open-web queries). An agent has everything needed to invoke this tool correctly and interpret results.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds meaningful extra nuance: depth:'thorough' is paid, standard is the default and includes gap recovery plus contradiction scanning, thorough uses 6 facets and an iterative lead-chasing hop, and the question parameter is explicitly described as accepting broad/multi-part natural language. This goes beyond the schema without needing to repeat it.

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

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

The description states a specific resource (Pipeworx's 1517 structured data sources), a clear action (grounded multi-source research decomposing questions into facets and routing them in parallel), and explicitly differentiates itself from open-web search and single-lookup tools. The phrase 'this is NOT open-web search' and the best-use examples make the tool's identity unmistakable.

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

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

Usage guidance is explicit and actionable: it names ask_pipeworx as the alternative when not signed in, specifies that thorough depth requires a paid plan, says it is 'best for broad/multi-part questions over structured data,' and directs single lookups to ask_pipeworx. It also explains the different depth tiers' behaviors, leaving little ambiguity about when to select this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool returns top-N relevant tools with full input schemas and curated examples, ready to call directly, which is useful behavioral context beyond annotations.

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

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

The description is a single paragraph that is informative but slightly verbose in listing data categories. It front-loads purpose and usage effectively. Could be more concise, but every sentence adds value.

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

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

Fully explains what the tool does, when to use it, what it returns (tool names, descriptions, schemas), and the nature of the query parameter. No output schema exists, but the description compensates by describing the output format. Complete for this tool's role.

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

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

Schema description coverage is 100% for all 6 parameters, so the baseline is 3. The description reinforces that the query parameter accepts natural language and aliases, but does not add significant meaning beyond the schema.

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

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

Clearly states the verb 'Find' and resource 'tools by describing the data or task'. Explicitly differentiates from siblings by stating 'Call this FIRST when you have many tools available', which is a unique role among the sibling tools.

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

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

Explicitly tells when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Provides strong guidance but does not explicitly state when not to use; however, the context implies it is for exploration rather than single-answer retrieval.

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 readOnly/openWorld/idempotent annotations, the description discloses fan-out sources, soft-failure of the USPTO patents source, empty-section semantics ('an empty section is a real "no data", not a bug'), and private-company resolved:false behavior. This gives the agent essential behavioral context not present in annotations.

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

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

The description is dense and long, but it front-loads use cases and every sentence carries operational meaning for a complex tool with no output schema. It could be improved by sectioning, but it is not padded.

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 fully enumerates returned sections (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) and failure modes, so an agent can both invoke it and interpret the result 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 the description adds value by giving concrete examples (AAPL, 0000320193, Moderna), clarifying that type=company and type=ticker are interchangeable, and explaining name resolution via SEC EDGAR. This goes beyond the schema without being strictly necessary.

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

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

The description opens with concrete user phrasings and defines the tool as a 'full cross-source profile of a US public company in ONE parallel call.' This is a specific verb+resource that clearly separates it from siblings like compare_entities or deep_research.

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

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

It explicitly instructs agents to 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested. It does not, however, name exclusions for closely related siblings such as compare_entities, so the guidance is clear but not fully exclusionary.

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 set destructiveHint=true and readOnlyHint=false. The description adds behavioral context about sensitivity and task completion, explaining why deletion is appropriate, which 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?

Two sentences with front-loaded purpose: first sentence states action, second adds usage guidance. No wasted words.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all needed information: purpose, triggers, and relationship to sibling tools. No gaps.

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

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

Schema coverage is 100%, and the description simply restates 'by key' without adding detail beyond the schema's 'Memory key to delete'. 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 states 'Delete a previously stored memory by key', which uses a specific verb ('Delete') and resource ('memory'), clearly distinguishing it from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall', providing good context, though no explicit when-not 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 mark it as read-only, idempotent, non-destructive. The description adds valuable behavioral detail: the tool fetches the page, extracts title/description/key links, and outputs the standard markdown format. 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 front-loaded with the main purpose and followed by details and use cases. It is concise but could be slightly shorter without losing clarity.

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

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

Given the simplicity (2 params, no output schema), the description is complete: it explains the process, output format, and use cases. The output is described as a text blob, which is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra semantics beyond the schema; it mentions 'fetches the page' which implies URL usage, but doesn't elaborate on max_links or 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?

The description specifies the verb 'generate', the resource 'llms.txt file', and the purpose of enabling AI crawlers to index sites. It clearly distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than 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 lists concrete use cases (client indexing, personal drafting, competitor auditing) but does not explicitly state when not to use it or mention alternative tools. The context is clear enough for appropriate selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return field details but no further behavioral traits.

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, front-loaded purpose, zero 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?

Simple tool with one optional param, description covers return fields and usage context adequately.

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

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

Schema coverage is 100%, description does not add meaning beyond schema's description of 'include_inactive'.

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

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

Clearly states verb 'List' and resource 'caller's active subscriptions', distinguishes from sibling tools 'subscribe' and 'unsubscribe'.

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

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

Explicitly recommends use for reviewing subscriptions before adding/canceling, but does not mention when not to use.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive hints. The description adds value by specifying the exact metadata returned (columns, types, row count, category, last-updated). No contradictions or missing behavioral traits 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?

Single sentence efficiently conveys purpose, input, and output. No extraneous words. Front-loaded with the key action and resource.

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 lists the expected returned fields (columns, types, row count, etc.). However, it does not explain how to obtain the resource_id or any potential limitations. For a simple tool, this is sufficient.

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

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

Schema coverage is 100% with a clear description of resource_id. The description reinforces the parameter with an example ('hmbh-c3hw'), adding semantic context beyond the schema. No other parameters exist.

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 gets schema and metadata for a Pierce County Open Data dataset by resource_id, with specific details like columns, types, row count. It includes an example, making the purpose unambiguous and distinct from sibling tools like query or datasets.

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?

While the description implies usage for retrieving dataset metadata, it does not explicitly state when to use this tool versus alternatives (e.g., query for data retrieval) or provide any conditions. The usage context is inferred but not guided.

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

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

Annotations are all false, offering no safety profile, so the description carries full weight. It discloses rate-limiting ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token return/follow-up flow, and that the team reads digests daily. No contradiction with the annotations exists.

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 and then logically covers use cases, exclusions, token mechanics, and limits. Every sentence earns its place—there's no repetition or filler despite the length, making it dense but highly readable.

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 explains the return value (claim_token) and the follow-up mechanism to check resolution. It covers rate limits, cost, and the feedback-to-roadmap connection, giving the agent everything needed to select and invoke the tool correctly. It's a complete, self-contained description.

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?

Although schema coverage is 100%, the description adds crucial semantic guidance: clarify that `message` should not contain user prompts and should be specific, explain the claim_token round-trip for reading status, and define that `context` should reference Pipeworx tools/packs. It also reiterates the `type` categories with real-world examples.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb and resource that clearly defines the tool's purpose. It distinguishes itself from all sibling tools by being the only feedback-reporting tool and explicitly scopes to 'tools served by this Pipeworx connection.'

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 use cases (bug, feature/data_gap, praise) with clear examples for each. It gives a concrete exclusion—do not report tools from other MCP servers—and directs users to file with that server instead, offering an alternative path. It also instructs users to describe issues in terms of Pipeworx tools/packs, not user prompts.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds caching details (5min-1h window-dependent), confirms no PII, and explains the data source (CF analytics engine). 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?

Four sentences with no redundancy. First hooks by describing what it returns, then lists use cases in a bullet-like format, then adds technical details. Every sentence earns its place.

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

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

Given no output schema, the description adequately describes return shape (top tools, top packs, total call volume) and caching behavior. For a read-only trending tool with one optional parameter, 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 coverage is 100% with a clear enum description. The description adds valuable nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents select the right window.

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

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

The description clearly states it returns top tools, top packs, and call volume over configurable windows. It uses specific verbs and noun phrases that distinguish it from sibling tools like 'discover_tools' and 'datasets'.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, checking alignment) and explains the trade-off between window lengths. Lacks explicit 'when not to use' or alternative tool mentions, but the guidance is strong.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds extensive behavioral detail: scanning scope (top 200 markets), algorithmic checks (Jaccard similarity, partition filter, fill check against live CLOB depth), and response structure. 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 well-structured with a clear front-loaded summary followed by detailed explanations of each mode and sub-mechanisms. While somewhat verbose, every sentence adds value and the organization aids comprehension.

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

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

Despite no output schema, the description fully documents the response structure (opportunities[], partition_check, fill_check) and important thresholds (3pp, 0.30 Jaccard, 20% placeholder). It covers all necessary context for an agent to use the tool effectively.

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 contextual meaning beyond the schema, such as accepting full Polymarket URLs for event, and providing example values and functional explanations for each 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It explicitly distinguishes three modes (no args, event, topic) and references sibling tool polymarket_fill_risk for custom sizing, providing clear differentiation.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning).' It also includes when-not-to-trade advice based on fill_check results and references an alternative tool for custom sizing.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds significant behavioral detail: caching for 1 hour, grouped response by segments, diagnostics for empty results, and edge calculation methodology. No contradictions with annotations, and it discloses how results are ranked and filtered.

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 disproportionately long and dense with technical jargon (e.g., 'GDELT 7d/21d article-volume ratio', 'favorite-longshot bias correction'), making it hard to parse quickly. While front-loaded with the purpose, the volume of detail could be streamlined for better conciseness.

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

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

Given the complexity (9 parameters, no output schema), the description is exceptionally complete. It explains the response structure (by_segment, diagnostics), assumptions (slippage, caching), and edge calculation logic. It covers all needed context for correct usage.

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

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

Schema description coverage is 100%, and parameter descriptions in the schema are already detailed. The tool description does not add new meaning to individual parameters beyond explaining the overall logic of segments and knobs. Baseline 3 is appropriate as the description does not need to compensate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan') and resource ('Polymarket markets'), and its intended use ('what should I bet on today') distinguishes it from sibling tools 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 explains the tool is for daily discovery of opportunities without paging, and mentions caching and knobs. However, it does not explicitly state when to use this tool versus alternatives like polymarket_edge_tracker or polymarket_arbitrage. The usage context is implied but not contrasted with 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 declare readOnly, openWorld, idempotent, not destructive. The description adds significant detail: data from daily snapshots bounded by 60-day TTL, decay computed from daily closes not intraday, gaps in snapshot dates. 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 thorough and well-structured, with clear sections for args, response, and limits. It is slightly lengthy but every sentence provides necessary detail. Front-loaded with the core question.

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

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

Given the tool's complexity and no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) with field details. Covers edge cases like gaps and TTL. Annotations and schema are rich, leaving no gaps.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by specifying the days clamp range (2-30) and giving examples for window (24hr, 1wk, 1mo) beyond the schema's 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 provides edge persistence and decay telemetry from Polymarket snapshots. It answers a specific question about edge age and trend, distinguishing it from related tools 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?

The description explains when to use it (to assess edge persistence/decay) and provides rationale for why old vs new edges matter. It does not explicitly compare to sibling tools, but the context is clear enough.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral detail: walks the ladder, returns verdicts per mode, and highlights risks like forced_directional_risk. No contradictions with annotations.

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

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

The description is thorough but somewhat lengthy; however, it is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence contributes to understanding, so it earns its length.

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

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

Given the tool's complexity (two modes, multiple outputs, no output schema), the description completely covers all necessary information: input parameters, output fields per mode, and usage context with sibling tools. It leaves no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains side options for each mode, size_usd interpretation (spend vs proceeds vs settlement notional), and default/clamp. This adds clear value over 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 defines the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth, with two distinct modes (single-market and basket). It differentiates itself from siblings like polymarket_arbitrage and polymarket_edges by explicitly stating when to use it.

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 this tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains the rationale (theoretical overround not capturable on thin books, partial fills creating unhedged positions). No exclusions 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?

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive. The description goes far beyond that by disclosing safety fields, compatibility codes, the gross-vs-net fee caveat, skipped-leg counters, and the fact that pairing is keyword-based rather than source-verified. This is exceptionally transparent about what the tool does and does not guarantee.

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

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

The description is long and dense, but it is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every sentence conveys a necessary caveat or specification. Some repetition exists, such as warning multiple times that returned pairs can still carry warnings, but the complexity of the tool justifies most of the 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?

With no output schema, the description carries the full burden of explaining the response shape, and it does so thoroughly: it describes venue prices, top_spreads_pp, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped cross-type/cross-subtype counters. An agent has enough context to interpret results and act on warnings without guessing.

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, but the description adds real semantics: it defines the topic shortcuts, explains that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and clarifies that both modes run the same matcher. This gives an agent a stronger mental model than the bare 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 opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the resource, the comparison, and the output. It distinguishes itself from sibling tools by focusing specifically on the Kalshi–Polymarket spread rather than generic arbitrage or edge tracking.

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

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

The description provides clear usage context: it explains the two modes (pre-mapped topic vs explicit ticker/slug), when each should be used, and cautions that pre-mapped topics often return warnings and are not necessarily tradeable. It does not explicitly name alternative sibling tools or state 'use tool X instead,' but the mode selection and caveats give an agent adequate routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's mention of returning JSON and explaining SoQL syntax adds useful behavioral context beyond what is in the annotations. No contradictions are present.

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

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

The description is extremely concise, consisting of only two sentences. It front-loads the action and resource, and every word serves a purpose. No unnecessary information.

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

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

Given the lack of an output schema, the description appropriately states that the tool 'Returns matching rows as JSON', which is sufficient. The parameters are well-documented in the schema, and the description covers the main functionality. It could mention pagination limits, but overall it is complete enough.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by clarifying that SoQL clauses should be provided without the leading $ (e.g., 'where' not '$where'), and provides an example. This reduces potential confusion.

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 runs a 'Socrata SoQL query' against a 'Pierce County Open Data dataset by resource_id', which is a specific verb and resource. It mentions filtering capabilities, distinguishing it from sibling tools like 'datasets' which list available datasets.

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

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

The description provides clear context for use: it specifies that SoQL clauses should be used without the leading $ and mentions parameters like limit/offset. It does not explicitly state when not to use the tool or provide alternatives, but the context is sufficient for basic 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?

The description adds behavioral context beyond annotations: scoping (anonymous IP, BYO key hash, account ID), the ability to list all keys by omitting the argument, and pairing with remember/forget. 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?

Three sentences, front-loaded with core function, succinct yet complete explanation of usage and scoping. No unnecessary words.

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

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

For a tool with one optional parameter, no output schema, and comprehensive annotations, the description covers purpose, usage, behavior, and parameter meaning adequately.

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

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

The only parameter 'key' is fully described in the schema (100% coverage). The main description reiterates its purpose but adds minimal extra value beyond 'retrieve a value saved via remember'.

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 indicates the tool retrieves a value saved via 'remember' or lists all keys when the key is omitted, distinguishing it from sibling tools like remember and forget.

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

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

It explains when to use (look up context stored earlier, avoid re-deriving) and mentions scoping, but does not explicitly state when not to use or provide alternatives beyond the mentioned paired tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description reinforces this by stating polling works fine and describing the return payload (source, citation_uri, raw event). 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?

Reasonably concise single paragraph. Front-loaded with purpose. Could break into bullet points but clear and efficient as is.

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 adequately explains what each alert contains. Mentions the alternative GET endpoint. Covers key aspects but could clarify sorting or pagination beyond the limit parameter.

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

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

All 5 parameters have schema descriptions (100% coverage). The description adds meaningful examples (e.g., 'sec_8k' for type, ISO timestamps for since) and explains the effect of mark_read, going beyond the schema.

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

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

Clearly states the tool pulls fired events from a subscription feed and returns recent alerts. It distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on the alerts themselves.

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

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

Provides guidance on filtering (type, since), mark_read behavior, and mentions polling works. Also notes the same feed is accessible via an HTTP endpoint for scripts. Lacks explicit when-not-to-use instructions but covers key usage scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral details: fans out to multiple sources, fallback chain (GDELT→GNews), soft-fail for USPTO, accepted date formats, and return structure. 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 dense but well-structured, with example queries front-loaded. Every sentence adds value, though some details (e.g., API sunset for USPTO) could be more concise. Still, it is appropriately sized for the tool's complexity.

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

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

Given no output schema, the description adequately explains return format (structured changes[], total_changes, URIs). All 3 parameters are well-documented. The tool has moderate complexity (multiple sources, fallback), and the description covers this completely, including cross-referencing entity_profile.

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: explains 'since' format with examples and typical use, notes 'type' only supports 'company', and clarifies 'value' can be ticker or CIK. This extra context justifies a 4.

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

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

The description clearly states it provides a change feed for a company, listing example queries like 'What's new with X'. It specifies multiple sources (SEC EDGAR, GDELT, GNews, USPTO) and what it returns (structured changes with URIs). It distinguishes from the sibling tool entity_profile, which is for static profiles.

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

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

The description gives explicit when-to-use guidance via example queries and states alternatives: 'Use entity_profile instead when you want the static profile'. While it doesn't list all sibling tools, the key alternative is clearly named, providing strong usage 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 indicate idempotent and non-destructive. Description adds key behavioral context: scoped by identifier, persistent vs 24-hour retention, and that it's a key-value store. 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?

Four sentences, each carrying essential information. Purpose is front-loaded. No redundancy or filler.

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

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

Given simple params (2 required strings, no output schema), description covers purpose, usage, behavioral nuances, and pairing with siblings. Completely adequate for effective tool selection.

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 adequate descriptions for both key and value. Description provides examples but adds minimal extra meaning beyond the schema. 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 uses specific verbs ('save', 'reuse later') and resource ('key-value pair stored by identifier'). Provides concrete examples (ticker, address, preference). Clearly distinguishes from sibling tools like '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: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget. Notes scope differences between authenticated and anonymous sessions.

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 well beyond the read-only annotations, revealing that each call cascades through multiple lookup endpoints and that enrichment degrades gracefully when GLEIF or OpenFIGI is unavailable. It also discloses ambiguity handling via `figi_candidates`, the explicit `unresolved` field instead of silent omission, and source labeling per identifier. These are substantive behavioral details an agent needs to trust the result.

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 query examples and the "Use FIRST" directive, which aids quick understanding. It is long and dense with long parentheticals, but each statement conveys useful operational detail rather than filler. The structure is workable but the supported-types section could be broken up 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?

Despite having no output schema, the description conveys enough about return behavior: identifiers with sources, unresolved fields, and candidate lists on ambiguity. It covers all supported input types, failure/degradation behavior, and special cases like bonds and ISINs. An agent has what it needs to choose and invoke the tool correctly across a wide range of entity-resolution questions.

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 substantial meaning: it lists accepted input forms including ticker, CIK, ISIN, or company name, explains ISIN-to-LEI mapping, and warns to pass the entity name only, not the full noun phrase. The `value` parameter's edge cases are richly documented beyond the schema's basic examples. This clearly helps the agent construct correct calls.

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

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

The description states a precise action: resolve user-spoken names to canonical/official identifiers other tools require as input. It distinguishes itself from siblings by covering company, drug, and non-equity instruments, and gives concrete query examples. This is a specific verb+resource with clear 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?

It explicitly says "Use FIRST whenever you have a name but need an ID," giving a clear trigger condition. It also explains behavior for ambiguous matches and unsupported cases, such as returning `figi_candidates` instead of asserting. However, it does not name specific alternative tools or exclusions, so it stops short of full when-not-to-use guidance.

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

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

Annotations already indicate safety and idempotency. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score/confidence/signal density. It also clarifies API key handling for Anthropic model. No contradictions.

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

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

Three sentences: first states purpose, second explains mechanism, third gives example. Front-loaded with key function. No unnecessary words. Every sentence adds value.

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

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

Covers purpose, mechanism, use case, and parameter nuances well. However, lacks output format details beyond listing fields (order, structure, potential errors) and no output schema is provided, leaving some incompleteness for complex multi-entity ranking.

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

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

Schema coverage is 100% but description adds significant meaning: explains that first entity is the 'subject' for narrative, rest are competitors; clarifies models (workers-ai vs anthropic) and API key requirement. This goes well beyond the schema descriptions.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities.' It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying side-by-side ranking and competitive auditing context.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' and a concrete example. However, it does not explicitly state when not to use or mention alternatives, though the sibling relationship to ai_visibility_check is implied.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral details: partial failure handling, bundlephobia timeout (5-30s), sources_failed listing, and graceful degradation. No contradictions with annotations.

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

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

Description is relatively long but every sentence adds value. It is front-loaded with purpose and usage, followed by behavioral details and limitations. Could benefit from minor structuring (e.g., bullet points) but remains clear and efficient.

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

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

Given the complexity (multiple external sources, no output schema, partial failures), the description fully covers what the tool returns (summary block, advisory detail, links, alternative versions), how it handles failures, and its limitations (npm only). No output schema exists, so the description carries the full burden and does so well.

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. Description adds value by noting that scoped packages are accepted and that version defaults to latest. Also explains the return structure (summary block, advisories, links, alternatives) which helps parameter understanding indirectly.

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 opens with a specific verb ('composite check'), names the exact resources (npm package, deps.dev, bundlephobia), and clearly states what it evaluates (license, advisories, bundle size, etc.). It distinguishes itself from over 30 sibling tools by targeting npm packages exclusively.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also clarifies ecosystem scope ('NPM ecosystem only in v1') and where other ecosystems fall. Does not include negative examples (when not to use), but positive guidance is clear.

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

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

Discloses embedding model, window size, character cap with truncation behavior, and that offsets are returned for verification. Adds significant 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?

Four sentences, front-loaded with core purpose, followed by use case, pairing, and technical details. 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, description explains returned passages with offsets and similarity scores, and notes truncation flag. Complete for agent usage.

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

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

Schema coverage is 100%. Description adds examples for queries and clarifies the text parameter's max size, providing valuable context beyond schema descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes by pairing with ask_pipeworx_grounded, setting it apart from 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?

Explicit when-to-use: 'Use when the record is too big to cram into the prompt — search_within saves context.' Also mentions pairing with another tool, but no explicit when-not-to-use.

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

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

The description adds behavioral context beyond annotations: it states the tool is a write operation (consistent with readOnlyHint=false), requires OAuth, has SMS rate limits (10/day), and describes idempotency? It doesn't clarify if repeated calls create duplicates (idempotentHint=true not explained). No contradiction with annotations.

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

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

The description is well-structured with bullet-like formatting and front-loaded purpose. It is fairly long but each sentence adds value. Could be slightly more concise by merging some examples, but overall effective.

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

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

The description covers required authentication, supported types, delivery channels, and constraints. Missing output schema is partially mitigated by mentioning 'Returns the new subscription id', though a full response structure description would be beneficial. Given the tool's complexity, it is nearly complete.

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

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

Schema coverage is 100% and the description enriches every parameter with concrete examples (e.g., items:["5.02"], topic:"fed", series_id:"UNRATE"). Delivery channels are explained in detail, including webhook signing, phone verification, and rate limits, adding significant 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?

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It lists specific types (e.g., sec_8k, polymarket_edge, fred_series) with examples, distinguishing it 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?

The description specifies the OAuth account requirement and supported types with parameter examples. It explains delivery channels, but does not explicitly mention when to avoid using it (e.g., for pull-based alerts use recent_alerts). However, the context is clear enough for appropriate use.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: it's an onboarding entry point, returns example questions, and can be called with no arguments. 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?

Well-structured with alternative queries at start, function description, parameter usage, and usage advice. All sentences are informative and concise, with no redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, parameter, usage context, and return structure comprehensively.

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

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

Schema coverage is 100% and description explains the topic parameter's purpose and values. Adds meaning beyond schema by clarifying omitting topic gives a full cross-category spread, which is helpful.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx by specifying it helps users discover what to ask.

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

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

Explicitly says to use this tool first when unsure about Pipeworx's capabilities and to learn meta-tool calls. Also explains that passing a topic focuses results, providing clear guidance on when and how 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?

Adds context beyond annotations: ownership enforcement and deactivation behavior. Annotations indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true), which are consistent with the description.

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

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

Two concise sentences: first states the action and constraint, second explains the behavioral effect. No superfluous 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 tool with one parameter and no output schema, the description covers all essential aspects: action, ownership restriction, and data lifecycle consequence, linking to a related sibling 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?

The sole parameter 'id' is fully described in the schema ('Subscription id (uuid) returned by subscribe.'). The description does not add additional semantic meaning, so baseline score of 3 is appropriate.

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

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

Clearly states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific, and it distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement — 'you can only cancel your own subscriptions' — and explains the effect: deactivated, not deleted, with historical events available via 'recent_alerts', providing clear when-to-use and alternatives.

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

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

Annotations already provide readOnly/openWorld/idempotent hints, so the bar is lower. The description adds valuable behavioral context: the automatic routing to different pipelines, the exact verdict vocabulary with meaning, and the critical semantic distinction between could_not_verify (failed check, not evidence) and unsupported (no source found). It does not repeat annotation data, and there is 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 longer than ideal but well-structured: trigger phrases, usage instruction, routing detail, return value summary, and two crucial caveats. Every sentence carries informational weight, though the final 'Replaces 4–6 sequential calls' is somewhat redundant with the automatic-routing explanation. It is front-loaded with the most important usage cue.

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 2-param tool with full schema coverage and rich annotations, this description is complete: it covers what, when, how (two pipelines), what the verdicts mean, and the critical gotcha about could_not_verify. No meaningful gaps remain for an agent to select and invoke it correctly.

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

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

The schema already covers both parameters 100%, so baseline is 3. The description adds value by explaining claim is a natural-language statement with examples, and that tolerance_pct overrides implied tolerance and caps at 5, plus a use-case (hallucination detection). It does not fully document formatting edge cases, but it enhances schema semantics enough to justify a 4.

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

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

The description starts with natural-language trigger phrases and explicitly states the tool verifies factual claims against authoritative sources, distinguishing it from siblings like ask_pipeworx or search_within. It clearly separates two pathways (SEC EDGAR for company-financial vs. grounded pipeline for other claims) and names the return verdicts, so the agent knows exactly what this tool does and how it differs.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates the structured SEC fast path from 'ANY OTHER factual claim' that 'automatically falls through to the grounded pipeline.' It also warns when NOT to use it (could_not_verify means check didn't happen, not evidence), giving clear actionable guidance.

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