Data Mesa

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: default model is free, Anthropic requires BYO key and direct payment, and the return structure (per-model fields plus combined view). No contradictions with annotations.

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

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

The description is a single paragraph of about 100 words, front-loaded with the main action. It efficiently covers purpose, default behavior, optional key usage, and return structure. No unnecessary sentences.

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

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

The description adequately covers the tool's purpose, parameters, and return format (per-model fields and combined view). With a complete schema and no output schema, this provides sufficient information for an agent to use the tool correctly. Lacks examples but not needed for this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning: explains that '_apiKey' is only needed if 'anthropic' is in models and that it is passed directly to Anthropic API, and clarifies the cost implication. This goes beyond the schema descriptions.

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

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

The description uses specific verbs ('Probe', 'score') and resources ('LLMs', 'visibility') and clearly states the tool's function: probing LLMs for knowledge about a business/brand/product/topic and returning a visibility score. It distinguishes itself from sibling tools by focusing on AI visibility measurement rather than general Q&A or 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?

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly list when not to use or name alternative tools, but the context is sufficient for an agent to decide.

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

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

Annotations already mark readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavior beyond those flags: it routes to internal tools, fills arguments automatically, returns stable citation URIs, and handles both current and historical data. It also warns that web search should be avoided in favor of this tool, which is useful behavioral guidance.

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 but front-loaded with the most important directive (PREFER OVER WEB SEARCH), followed by scope, examples, and sibling routing. The example list is somewhat expansive, but each block earns its place in guiding tool selection.

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

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

Given there is no output schema, the description still conveys the output shape (structured answer with pipeworx:// citations) and covers scope, triggers, examples, and alternatives. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100%, with all parameters documented as aliases for the question string. The description gives example questions but does not add meaning beyond the schema, which matches the baseline for fully documented schemas.

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 definitive verb and resource: ask_pipeworx routes natural-language questions to one of 5,767 tools across verified sources and returns structured answers with citations. It is clearly distinguished from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Explicitly instructs to prefer this tool over web search for factual questions, lists trigger phrases and examples, and gives concrete routing rules: ask_pipeworx_grounded for single-answer/low-latency, deep_research for broad/multi-part queries, and news routing for breaking-news queries. No ambiguity about when to choose 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?

The description goes well beyond the read-only/idempotent annotations by disclosing that candidate routing improvements are enabled live only while under test, that none is currently active, and that the tool currently behaves identically to ask_pipeworx. It also clarifies that this is a full working router with no fallback, which is useful operational information.

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 beta identity and then moves through current status, usage instruction, and the fallback clarification. Each sentence earns its place, though the detailed date and count of tools add depth beyond the minimum.

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

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

The description covers the crucial operational state, parity with ask_pipeworx, usage guidance, and response-shape equivalence, which is sufficient given the full annotations and rich schema. The only minor gap is that the actual response contents are not described beyond matching ask_pipeworx.

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

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

Schema coverage is 100% with the single required question parameter and all aliases documented. The description adds no parameter-specific semantics beyond saying arguments are identical to ask_pipeworx, so the baseline of 3 is appropriate.

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

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

The description identifies the tool as a beta version of ask_pipeworx and states it is the same universal router with the same tools, arguments, and response shape. The role of an experimental routing entry point is clear, though the core 'answer a natural-language question' behavior is implied rather than explicitly stated.

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 tells the agent to use it like ask_pipeworx when the newest routing behavior is desired, and notes that results are compared against the stable router. It does not list formal exclusions, but the experimental-versus-stable distinction gives a clear 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 mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail above that: explicit refusal reasons, evidence quoting, refusal_reason values, and the guarantee that no invented facts will be returned. There is no contradiction with the annotations.

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

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

The description is dense but every sentence earns its place: purpose, behavior, return contract, usage guidance, and cost trade-off. It is front-loaded with the primary purpose and avoids fluff.

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

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

Because there is no output schema, the description correctly supplies the return shape and refusal contract. It also covers the cost implication and the alternative tool, making it sufficiently complete for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, with the single canonical `question` parameter and its aliases fully documented. The description adds no parameter-specific meaning, but it does not need to because the schema already carries that burden. Baseline 3 is appropriate.

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

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

The description clearly defines what the tool does: it is a hallucination-resistant, grounded answer mode that extracts answers using only tool-result content. It explicitly contrasts itself with ask_pipeworx, making the differentiation from its sibling 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?

It states exactly when to use this tool ('whenever an answer will be quoted, cited, or acted on') and gives an explicit alternative path ('prefer ask_pipeworx for casual lookups'). It also discloses the extra LLM call cost, giving the agent a concrete decision rule.

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

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

The description extensively discloses behaviors beyond annotations, including resolution, fan-out, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms, and cancellation rules. Annotations (readOnlyHint, idempotentHint, etc.) are consistent and fully supported.

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 a clear summary and well-structured into sections. While lengthy, the depth is justified by the tool's complexity, and every sentence provides useful information. Could be slightly 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?

The description is extremely thorough, covering edge cases (closed markets, low-confidence matches, wide spreads), response shapes, resolver contracts, parent events, news fallback, and cancellation rules. It provides all necessary context for correct agent behavior without an output schema.

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

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

Schema coverage is 100%, and the description adds significant value by explaining what the 'market' parameter accepts (slug, URL, question), the effect of 'depth' (quick vs thorough), and the 'include_raw' usage and implications. Examples are given.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data in one call, specifying the resource and action. It distinguishes from sibling tools by focusing on comprehensive research rather than specific tasks like 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?

Explicitly states use cases (e.g., 'should I bet on X', 'what does the data say') and provides numerous examples. While it doesn't explicitly state when not to use, the specificity of the tool's purpose implicitly covers exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds: for type='company' it pulls specific financial metrics from EDGAR/XBRL with correct fiscal year handling; for type='drug' it pulls adverse-event, approval, and trial counts. Also notes sorted results and citation URIs. No contradictions.

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

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

Concisely packed with value: front-loaded with common query patterns, then gives concise technical details. Every sentence adds information without redundancy.

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

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

For a tool with 2 parameters, 100% schema coverage, and no output schema, the description is fully complete. It explains data sources, specific metrics, sorting, citation URIs, and even edge cases like off-calendar fiscal years.

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 expands on both parameters: explains enum values for 'type' (company vs drug) and provides concrete examples for 'values' (tickers/CIKs for companies, drug names). Also explains downstream behavior per type.

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

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

The description begins with explicit user query examples and clearly states it performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from siblings by preferring over sequential lookups and notes it replaces 8–15 calls.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also emphasizes efficiency via parallel execution, helping the agent choose this tool over alternatives like entity_profile.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds context about return fields and next step (pass resource_id to metadata), which provides behavioral insight beyond annotations but does not contradict them.

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

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

Two sentences, front-loaded with purpose, followed by output details and usage hint. 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 search tool with 3 parameters and no output schema, the description sufficiently covers return value details, pagination hint (implicit from offset/limit), and linkage to metadata tool. Annotations cover safety and idempotency, so no gaps.

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

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

Schema coverage is 100% with descriptions for all parameters. The tool description adds no additional parameter-level meaning beyond what schema already provides, so baseline of 3 is appropriate.

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

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

Description uses specific verb 'Search' and resource 'Mesa Open Data catalog of open datasets', and lists exactly what is returned (resource_id, name, description, category, update date). It is clear and distinguishes from other tools by focusing on open 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?

Implies usage for keyword searching of datasets and hints at using resource_id for further metadata queries, but does not explicitly state when not to use or compare with sibling tools like query or deep_research.

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/open-world/idempotent annotations by disclosing the findings packet structure: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations, and explicit gaps[] for unanswered facets with a never-invented guarantee. It also reveals account/tier gating and the non-open-web nature of the tool.

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 tightly organized, front-loading the critical account/tier prerequisite before moving through purpose, mechanics, return format, and best-use guidance. Every sentence contributes substantive information, with no filler or wasted repetition.

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

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

Despite lacking an output schema, the description explains what callers receive: findings with evidence, confidence, source, fetched_at, citations, gaps[], and the no-fabrication guarantee. Combined with a fully documented input schema and informative annotations, an agent has enough information to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so both question and depth are already well documented. The description adds only marginal parameter-level context, such as reinforcing that broad questions are acceptable and that thorough requires a paid plan, which the schema already states. It does not materially enrich parameter understanding beyond the schema.

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

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

The description clearly states the tool performs grounded multi-source research over 1506 structured data sources in one call, with explicit details about facet decomposition and parallel routing. It distinguishes itself from open-web search and from sibling ask_pipeworx, making the tool's purpose and scope unmistakable.

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

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

The description explicitly says deep_research is best for broad/multi-part questions over structured data and tells users to use ask_pipeworx instead for single lookups or when not signed in. It also warns that depth:'thorough' requires a paid plan, giving clear selection criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable context about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.'

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

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

The description is a single paragraph, but it is well-structured with the main purpose upfront, followed by domain examples, then behavioral details. It is slightly long but every sentence adds value; no wasted words.

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

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

Despite no output schema, the description fully explains what the tool returns: top-N tools with names, descriptions, and full schemas. Combined with high schema coverage and explicit usage guidance, the description is complete for an AI agent to use the tool correctly.

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

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

Schema description coverage is 100% (all 6 parameters documented in schema). The description adds meaning by explaining that the tool accepts natural language descriptions and mentions aliases (q, task, description, search) and provides examples, reducing ambiguity.

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 function: 'Find tools by describing the data or task.' It provides a comprehensive list of example domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being the tool for discovering other tools.

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

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

Explicit instruction to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to use the tool and implies when not to use it (when you already know the 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, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds meaningful context beyond annotations: parallel fan-out across multiple sources, resolved_from/resolved_to behavior, empty-section semantics (real no data vs bug), and graceful handling of private companies. It doesn't document every source detail, but it covers the important behavioral surprises.

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 information-dense and front-loaded with usage triggers, but it is largely a single long paragraph with many compressed clauses and parentheticals. Every sentence carries information, yet the density hurts skimmability; an agent parsing it quickly could miss details like the `sources_used`/`sources_failed` semantics. It earns a 3: no fluff, but structure is suboptimal.

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

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

For a complex fan-out tool with no output schema, the description is quite complete: it enumerates source domains, return sections, input formats, resolution behavior, private-company fallback, and error interpretation. It doesn't deeply describe pagination or the exact shape of `fundamentals`, but the `sources_failed`/`sources_used` disclosure compensates for much of the uncertainty an agent would otherwise have.

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

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

Schema coverage is 100%, so the baseline is 3. The description, however, adds substantial semantic value: it clarifies that `type` is effectively redundant, that `value` accepts the same shapes regardless of `type`, and that company-name resolution goes through SEC EDGAR. It also hints at future person/place support. This goes beyond the schema's own 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 opens with concrete trigger phrases and names a specific verb+resource: generate a full cross-source profile of a US public company in one parallel call. It clearly distinguishes itself from targeted lookups (SEC/XBRL/news) and from sibling tools like resolve_entity by emphasizing the holistic, one-call aggregation.

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

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

Explicitly says ALWAYS PREFER over chaining single-pack lookups when a holistic view is requested, which is a crisp selection rule. It also specifies accepted input shapes (ticker, CIK, company name), behavior for private companies, and what `type` values are interchangeable. No ambiguity remains about when or how to invoke it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description aligns with those. It adds no contradictory info but provides usage context beyond annotations.

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

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

Two sentences, front-loaded with action, no wasted words. Efficient and clear.

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

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

For a simple delete operation with one parameter and no output schema, the description covers purpose, usage, and relationships to siblings completely.

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

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

Schema coverage is 100% and describes the 'key' parameter as 'Memory key to delete'. The description adds little beyond that, so baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself from siblings by mentioning '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?

Provides explicit usage contexts: when context is stale, task is done, or clearing sensitive data. Also mentions pairing with remember and recall, offering 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 declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds behavioral details: fetches page, extracts title/description/key links, emits standard markdown format. This exceeds annotation-only information without contradiction.

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

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

The description is two sentences with a bullet list of use cases, all front-loaded and efficient. Every sentence adds value with 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 the tool has 2 parameters and no output schema, the description fully explains the process, output format, and intent. It also covers practical applications, making it self-contained for an agent.

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

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

Schema coverage is 100% for both parameters. The description restates max_links defaults and limits (default 25, max 50) but adds no new 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?

The description uses a specific verb 'Generate' and resource 'llms.txt file for any URL', clearly distinguishing its purpose. It explicitly states it produces a standard markdown format for AI crawlers, differentiating from siblings like 'ai_visibility_check' or 'scan_competitor_ai_presence'.

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 lists concrete use cases ('getting a client's site indexed by AI, drafting llms.txt, auditing competitor AI crawl'), providing clear context. However, it does not explicitly exclude scenarios or mention alternatives among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by specifying return fields and scope (caller's active subscriptions). No contradictions.

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

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

Two sentences, front-loaded with purpose and return fields. Zero wasted words; 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 annotations and schema, description covers purpose, usage, and return fields. No output schema exists, but description lists fields. Could mention 'per-caller' scope already implied.

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

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

Schema coverage is 100% with parameter 'include_inactive' well-described. Description does not add further detail about the parameter, so baseline of 3 applies.

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

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

Clearly states it lists the caller's active subscriptions and enumerates return fields (id, type, params, etc.). Distinguishes itself from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to use, though no explicit when-not or alternatives beyond implied differentiation.

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 concrete details about what is returned (columns, types, row count, category, last-updated), which is useful behavioral context beyond the annotations. 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?

Single sentence with clear verb, resource, and example. Every part is informative and no word is wasted. Ideal length for a simple tool.

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

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

For a tool with a single parameter, rich annotations, and no output schema, the description covers all necessary information: it specifies input (resource_id), output (schema + metadata details), and provides an example. Nothing needed 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 description coverage is 100% for the single parameter 'resource_id', which the description repeats. The description does not add new meaning beyond the schema's example and description, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: getting schema and metadata (columns, types, row count, category, last-updated) for a Mesa Open Data dataset by resource_id, with a concrete example. It distinguishes itself from sibling tools by being specific to Mesa Open Data metadata retrieval.

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

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

The description implies use when metadata for a Mesa Open Data dataset is needed, and provides an example. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., the 'datasets' sibling tool might be related). No exclusions or context for choosing this over others is given.

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 only provide all-false hints, so the description carries the transparency burden. It adds useful behavioral context: rate-limited to 5 per identifier per day, free and doesn't count against quota, returns a claim_token for follow-up, and team reads digests daily. It doesn't fully describe the side effect of creating a feedback record, but the main behavior is evident and no contradictions exist.

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 but information-dense. Every sentence earns its place: purpose, usage guidance, exclusions, token flow, rate limits, quota info. It is front-loaded with the core 'send feedback' function and structured to avoid ambiguity.

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 4 parameters, nested context object, no output schema, and many siblings, the description provides comprehensive guidance. It covers what counts as valid feedback, how to follow up via claim_token, what the response contains for that token, and operational details like rate limits. The tool's full workflow is explained without needing an output schema.

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

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

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds extra semantics beyond schema: instructs not to paste end-user prompts, to describe issues in terms of Pipeworx tools/packs, and clarifies how claim_token is used for reading prior reports. This exceeds the schema's basic parameter 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the tool's purpose with specific verb and resource. It distinguishes itself from sibling ask/research tools by focusing on feedback about Pipeworx's own tools, not general queries.

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

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

Provides explicit when-to-use criteria: bug reports for wrong/stale data, feature/data_gap for missing capabilities, praise for good work. Includes explicit exclusion: feedback about tools from other MCP servers should be filed there, not here. This gives clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds context: data derived from CF analytics-engine, no PII, cached 5min-1h, and self-aggregating signal. 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?

Description is concise and well-structured: opening sentence states main output, then bullet-point use cases, then technical details. No redundant information.

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

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

Despite no output schema, the description explains return shape (top tools, top packs, total call volume). Caching and data source are mentioned. With one optional parameter, the description 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 has 100% description coverage for the sole parameter 'window'. The description adds meaning by explaining the effect of different window lengths on results (hot vs. steady-state), beyond the enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window'. The verb 'returns' and resource 'trending data' are specific. It distinguishes from siblings by focusing on aggregated call volume, unlike ask_pipeworx or discover_tools.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, seeing alignment). However, no explicit 'when not to use' or alternatives are mentioned.

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 provides extensive behavioral details beyond annotations: partition check logic (sum YES prices ≈1, deviations >3pp trigger signal), semantic anchor (Jaccard similarity ≥0.30), partition filter (drops placeholder slugs, >20% placeholder yields null), and fill check against live CLOB depth. Annotations confirm readOnly, openWorld, idempotent, non-destructive, and description adds context without contradiction.

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

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

The description is fairly long but well-organized with clear sections for each mode, filters, response structure, and fill check. It is front-loaded with the core purpose. Minor redundancy (e.g., explaining partition_check twice) prevents a perfect score, but overall efficient for the complexity.

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

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

Given the complexity (multiple modes, filters, fill check) and the absence of output schema, the description thoroughly covers what the tool returns: opportunities array with gap_pp, suggested_trade, reasoning, monotonicity violation context; partition_check object; fill check results. It also explains edge cases like placeholder filtering and realizable edge ≤0.

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 descriptions cover both parameters, the tool description adds significant semantic value: it explains the default behavior (no args), the recommended use of 'event' for specific markets, the cross-event scanning for 'topic', and details like walking child markets, date-axis/threshold-axis ordering, and the partition_check. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending scan), event (specific market), and topic (cross-event scan), providing a specific verb and resource.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also explains when not to use the tool, e.g., 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it', and mentions alternatives like 'polymarket_fill_risk' for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds beyond with caching details, model families, diagnostics, and treatment of edge_pp_net after slippage.

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

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

Description is lengthy but every sentence adds value. Structured with general purpose, model families, response details, and knob explanations. Front-loaded with core purpose, though could be slightly more concise.

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

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

Given 9 parameters and no output schema, description explains output structure (segments, diagnostics, caching), anticipates user needs (reason for empty segments), and covers all aspects 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?

100% schema coverage means baseline 3. Description adds context for certain parameters (e.g., slippage_pp discusses Polymarket fees, min_partition_leg_kelly explains per-leg application), providing extra value.

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

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

Clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' Distinguishes from siblings by detailing specific model families and edge detection approach.

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 built for 'what should I bet on today' and describes tradeable-edge knobs to filter opportunities. Does not specify when not to use or alternative tools, but implicitly defines niche.

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 provides extensive behavioral details beyond the annotations (readOnlyHint, idempotentHint). It explains the response structure (tracked, expired, snapshot_dates), limits (60-day TTL), how gaps occur, and how decay is computed. 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 front-loaded with the core purpose and then provides detailed context. It is somewhat verbose but every sentence adds useful information. The structure is logical, moving from purpose to arguments to response to limits.

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

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

Despite having no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and their meanings. It covers all relevant context such as limits, gaps, and computation details, making it self-sufficient for an AI agent.

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

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

The input schema already covers both parameters with descriptions. The description adds value by specifying default values, clamping for days, and clarifying the meaning of the window parameter (24hr, 1wk, 1mo) beyond its schema description.

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

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

The description clearly states the tool's purpose: providing 'edge persistence and decay telemetry' from daily snapshots. It answers a specific question about edge duration and trend, and distinguishes itself from sibling tools like polymarket_edges by focusing on persistence rather than raw edge data.

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

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

The description gives good context on when to use the tool—checking edge age and trend—and contrasts a fresh wide edge with an old one. However, it does not explicitly state when not to use it or mention alternatives like polymarket_edges for snapshot data.

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 that it walks the order book ladder, returns verdict (clean/degraded/cannot_fill), and warns about forced directional risk. No contradiction with annotations (readOnlyHint=true, etc.). Adds significant 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?

Well-structured with mode sections and front-loaded purpose, but slightly verbose. Every sentence adds value, though could be trimmed slightly 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?

Thorough coverage of both modes, return fields, and risk warnings. Despite no output schema, the description provides sufficient context for an agent to understand what the tool returns and when to use it.

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

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

Schema description coverage is 100%. Description further explains defaults (e.g., side auto for basket), interpretation of size_usd for buys vs sells, and that one of market or event is required.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth, with two modes (single-market and basket) and specific return fields. Distinguishes from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains risks of partial fills and directional exposure.

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?

Goes far beyond the readOnly/idempotent annotations: it discloses gross vs net spreads, unmodeled Kalshi fees, compatibility warning semantics, flag lists, null temporal_alignment meaning, and skipped-pair counters. The description also explicitly warns that matched_pairs>0 does not imply safety and that pre-mapped ≠ tradeable — exactly the kind of behavioral nuance a caller needs.

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 but structured with labeled sections (modes, response, safety fields, codes, fees, counters), and the most decision-relevant caveats are front-loaded. Every sentence carries information, though the density and length make it heavier than the ideal; a modest trim would make it 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?

Given there is no output schema, the description fully compensates: it enumerates response fields, spread semantics, compatibility codes, per-entry flags, skipped/unclassified handling, and fee limitations. An agent has enough to call the tool, interpret results, and avoid false-confidence conclusions.

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?

While schema coverage is 100%, the description adds substantial meaning: the topic list's auto-fetch behavior, the override semantics of kalshi_event_ticker and polymarket_event_slug, and the identical matcher across both modes. It also clarifies that both modes share the same disclosures, removing ambiguity about parameter interactions.

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

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

The description opens with a specific resource ('cross-venue spread between Kalshi and Polymarket') and an explicit outcome concept ('same resolving question'). It further explains two modes and the matching logic, so an agent can distinguish this from related market tools like polymarket_arbitrage or polymarket_edges without inspecting schema.

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?

Clearly states two mutually exclusive invocation modes (topic shortcuts vs explicit ticker/slug) and gives strong context on when the signal is usable ('when bet shapes are equivalent') and that most pre-mapped topics are not currently tradeable. It does not name sibling tools as alternatives or provide an explicit 'use X instead when...' wording, but the context is otherwise explicit and decision-relevant.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds that it returns JSON and that SoQL clauses are used without the leading $, which are important behavioral details. No contradictions.

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

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

Two sentences: first states the core action, second lists the filtering capabilities. No redundancy or unnecessary words. Information is front-loaded and easy to parse.

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

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

Given the schema covers all parameters and annotations provide safety guarantees, the description is complete. It mentions return format (JSON), the query language, and key parameters. No obvious 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 has 100% coverage, so baseline is 3. The description adds value by explaining the SoQL syntax convention (omit leading $), which clarifies how to use the string parameters effectively.

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 runs a Socrata SoQL query against a specific dataset by resource_id, with a concrete example. It distinguishes from siblings like 'datasets' which only retrieve dataset metadata.

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 instructions on how to use SoQL clauses without leading $ and mentions limit/offset. There are no alternative query tools among siblings, but the description does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. Description adds scoping detail (by identifier) and pairing context, but no additional behavioral traits beyond what annotations imply.

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

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

Three sentences, each earns its place: core action, usage example with context, scope/pairing. No waste, front-loaded with main purpose.

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

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

Given one simple parameter, no output schema, and robust annotations, the description covers all needed context: what it does, when to use, scope, and partner tools. Complete for a read-only retrieval tool.

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

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

Schema coverage is 100% with one optional key parameter. Description adds usage guidance: omitting key lists all keys, which goes beyond schema description and helps agent decide when to omit.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. Distinguishes from sibling tools remember and forget.

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

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

Explicitly says when to use: to look up stored context without re-deriving. Provides examples (ticker, address, notes). Mentions scope and pairing with remember/forget. Lacks explicit when-not or alternatives, 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?

Description contradicts annotations: readOnlyHint=true in annotations suggests no state change, but description says mark_read:true flags events as read, modifying state. Also, idempotentHint is violated since subsequent calls may differ. This is an annotation contradiction.

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

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

The description is a single, well-structured paragraph that front-loads the purpose and efficiently covers return fields, filtering, side effects, and alternatives. Slightly dense 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?

Provides return field info, filtering, mark_read behavior, and alternative access. However, the contradiction between description and annotations undercuts completeness, and some details like format of source are omitted. Adequate but not fully complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minor extra context (e.g., example type 'sec_8k', effect of mark_read) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts with specific fields. It is highly specific with verb 'Pull' and resource, and does not need to distinguish from siblings given the clear 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?

Provides explicit filtering options (type, since) and explains the mark_read flag behavior. Mentions polling and an alternative HTTP endpoint. Lacks explicit when-not-to-use or comparisons to sibling tools, but offers solid 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details fan-out to multiple sources, GDELT/GNews fallback logic, USPTO soft-fail after May 2025, and relative date support—adding significant behavioral context.

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

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

The description is fairly long but front-loaded with example queries. Every sentence adds value, though it could be slightly more concise without losing key details.

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

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

Given no output schema, the description adequately describes the return structure (changes grouped by source, total_changes count, citation URIs). For a tool combining multiple sources, this provides sufficient completeness.

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

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

Schema coverage is 100%, but the description adds value by explaining 'since' accepts ISO dates and relative shorthand (e.g., '30d'), and 'value' accepts ticker or CIK. It also clarifies 'type' is limited to 'company'.

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

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

The description clearly states the tool provides a change feed for companies (SEC filings, news, patents) in a recent time window. It distinguishes from the sibling entity_profile by stating when to use the latter instead.

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 examples (e.g., 'what's new with X', 'latest on Y') and contrasts with entity_profile for static profiles. However, it does not explicitly list when not to use this tool beyond that comparison.

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 value beyond annotations: persistence details (24-hour for anonymous, persistent for authenticated), scoping by identifier. Idempotent hint is consistent. No contradiction.

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

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

Four sentences, front-loaded with purpose, then usage and behavioral details. 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?

Fully covers usage, behavioral traits, and pairing with siblings for a simple key-value tool with no output schema.

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

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

Schema coverage 100%, schema descriptions are clear. Description does not add new parameter meaning but is adequate given schema. Baseline 3.

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

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

The description clearly states the tool saves data for reuse, with specific examples (resolved ticker, target address) and distinguishes from siblings 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?

Explicit when-to-use guidance: 'when you discover something worth carrying forward'. Mentions pairing with recall/forget. Lacks explicit when-not conditions, 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?

Despite rich annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavior beyond them: ambiguous names produce `figi_candidates` rather than asserting, unresolved identifiers are explicitly listed under `unresolved`, GLEIF/OpenFIGI enrichment "degrades gracefully," and ISINs map to legal entities. These traits directly change how an agent interprets results and are invisible in the annotations.

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

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

The purpose and trigger phrases are front-loaded, and there is no filler, but the body is one enormous run-on paragraph with deep parenthetical nesting (e.g., the multi-clause FIGI/OpenFIGI aside) that is genuinely hard to scan. The content earns its place, but the structure is not appropriately sized for an agent to parse efficiently.

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 carries return-value semantics: per-type return fields (CIK/ticker/company_name from EDGAR, LEI plus ownership from GLEIF, FIGI from OpenFIGI; RxCUI/ingredient/brand from RxNorm), ambiguity behavior, unresolved-field handling, and failure modes like GLEIF/OpenFIGI unavailability. Nothing an agent needs to call or interpret the tool 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% and the schema's `value` description is already detailed, so the baseline is 3. The description adds meaning beyond the schema by introducing ISIN as an accepted company input (schema lists only ticker/CIK/name) and by explaining the FIGI name-matching caveat that trailing security-class words resolve to nothing — both essential for constructing valid values.

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

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

The description opens with concrete user phrasings ("What's the ticker for…", "find the CIK for…") and states the exact job: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It enumerates precise outputs (ticker, CIK, LEI, FIGI, RxCUI) and the two supported types, so an agent can distinguish it from sibling tools like entity_profile or compare_entities.

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

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

It gives explicit when-to-use guidance: "Use FIRST whenever you have a name but need an ID," and frames its value as replacing "2-3 manual lookups." However, it never names a sibling tool as the alternative or states exclusion conditions, so an agent must infer when NOT to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description correctly avoids repeating these. It adds value by explaining the internal behavior ('Probes each entity with ai_visibility_check') and the treatment of the first entity as subject. There is 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 consists of two concise sentences with no redundant or filler content. It front-loads the core purpose and then gives a practical use case, making every word count.

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

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

Despite lacking an output schema, the description explicitly states the return format ('ranked list with score, confidence, signal density per entity'). It also explains the process and inputs sufficiently. For a tool that composes multiple calls, this is complete and informative.

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 schema already describes all parameters adequately. The tool description does not add parameter-specific meaning beyond what the schema provides; it only summarizes the tool's overall behavior. 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 uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes itself from sibling tool 'ai_visibility_check' by stating it aggregates multiple probes and ranks them, making the purpose unmistakable.

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

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

The description provides clear context with the example question and identifies the use case ('competitive AI-marketing audits'). However, it does not explicitly state when not to use this tool or mention alternatives (e.g., using ai_visibility_check for a single entity). The context is clear but lacks exclusions.

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

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

Annotations indicate read-only, open world, idempotent, non-destructive. The description adds rich behavioral context: it fans out to two services, returns specific fields, includes per-advisory details, links, and alternative versions. It also discloses that bundlephobia's first measurement may take 5-30 seconds and that sources_failed will list timeouts, which goes well 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 detailed but well-structured, front-loading the core purpose and then providing necessary specifics. Each sentence adds value, though it is slightly long; however, given the complexity (two external services, partial failures), the length is justified.

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

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

Despite having no output schema, the description thoroughly lists return fields and handles partial failures. It covers all necessary context for the tool's moderate complexity (2 params, external services, version handling). The description is complete and leaves no major gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description restates the schema descriptions for 'package' and 'version' (e.g., scoped packages accepted, defaults to latest) without adding significant new meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, combining deps.dev and bundlephobia. It specifies the resource (npm package) and action (scan), and distinguishes itself from siblings by its unique composite nature.

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

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

The description explicitly tells when to use ('is X safe/popular/small' or 'what does adding lodash cost me') and provides limitations ('NPM ecosystem only in v1') with alternatives for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). It also discusses partial failures gracefully.

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, idempotent, and non-destructive hints. The description adds technical details (BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation) and return structure (passages with offsets and scores), exceeding annotation coverage.

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

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

Concise at four sentences with front-loaded purpose, then usage context, then technical details. No redundant information; each sentence adds value.

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

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

Despite no output schema, the description explains return values (top-N passages with offsets and similarity scores). Covers behavior, cap, truncation flag, and pairing with sibling tool. Sufficient for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for 'text' (document text, max chars), 'query' (examples like 'supply-chain risk'), and 'limit' (default 5, range 1-20), providing value beyond schema.

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

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

The description clearly states the action ('semantic search INSIDE a fetched record') and provides specific examples (SEC 10-K, article). It differentiates from siblings by focusing on already-fetched content rather than fetching or external searches.

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

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

Explicitly advises use when 'the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Could benefit from explicit when-not-to-use or listing 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?

Discloses OAuth requirement, delivery limits (10/day SMS cap), and always-on feed behavior. Annotations already indicate non-read-only and idempotent; description adds context without contradiction.

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

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

Efficiently organized: main action, return value, prerequisites, supported types with inline examples, delivery channels. 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?

Covers all aspects for a complex tool with nested params and no output schema: what it does, requirements, parameter details, delivery, and return. Agent has sufficient info to use correctly.

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

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

Schema coverage is 100%, but description adds rich examples for each type parameter and explains nested delivery options with constraints (phone verification, webhook signing). Significantly enhances 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. Distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

Provides prerequisites (OAuth account), lists supported types with examples, and delivery options. Does not explicitly state when not to use or name alternatives, 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns 'category-bucketed example questions' and is drawn from a live catalog, consistent with annotations. No behavioral gaps.

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

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

The description is a single paragraph but packs useful information without redundancy. Slightly structured with examples and categories, though bullet points could improve scannability.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains purpose, usage scenario, parameter behavior, and return type. No missing context.

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

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

Schema description coverage is 100% for the single 'topic' parameter, which is already fully described in the schema. The description does not add new parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on 'what can I ask' rather than executing queries or tool discovery.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides examples of queries. It explains calling with/without topic argument but does not explicitly state when not to use or list alternatives.

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

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

Annotations already indicate non-destructive and idempotent. Description adds value by explaining soft-delete behavior (row deactivated, historical events preserved) and ownership enforcement.

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

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

Two sentences, front-loaded with action, followed by constraints. No wasted words.

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

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

For a simple tool with one param and no output schema, description adequately covers purpose, ownership, and data model implications. Minor gap: what happens if already unsubscribed.

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

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

Schema has 100% coverage with description for 'id' parameter. Description does not add additional semantic detail beyond restating subscription id from 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 'Cancel a subscription by id' with specific verb and resource. Differentiates from sibling tools like 'subscribe' (opposite) and 'list_subscriptions' (listing).

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?

Describes ownership enforcement ('only your own subscriptions') and behavioral nuance (deactivated, not deleted). Implicitly clarifies when to use, though does not explicitly state when not to use or mention alternatives.

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

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

The description discloses critical behavioral semantics beyond the annotations: the distinction between could_not_verify (not evidence, carries verification_error) and unsupported (no source found), which is vital for correct interpretation. It also reveals the two backend paths (SEC EDGAR + XBRL vs. grounded pipeline), adding transparency not captured by readOnly/openWorld hints. 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 long but front-loaded with examples and a clear purpose statement. Every sentence contributes context—scope, routing, outputs, and caller warnings. It could be slightly trimmed without losing value, but it is well-structured and avoids fluff, earning a 4.

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

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

With no output schema, the description compensates by explaining return values (verdict list, actual value with citation, reasoning) and the meaning of each verdict. It covers edge cases (could_not_verify, unsupported), caller warnings, and the tool's advantage over sequential calls, making it a complete guide for invocation and interpretation.

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

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

Schema coverage is 100%, so the baseline of 3 applies. Both claim and tolerance_pct are already well-described in the schema (including default cap and use cases). The description does not add new parameter-level semantics; it only reiterates the tolerance concept in passing ('exact percent-delta math'), which does not elevate the score above baseline.

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

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

The description uses a specific verb ('validate'/'verify') and resource (natural-language claims), backed by concrete example phrasings. It distinguishes from sibling tools by detailing the two-path pipeline and stating it 'replaces 4–6 sequential calls,' making its unique role explicit.

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

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

The description gives an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the automatic routing for company-financial vs. other claims. However, it does not explicitly name when-not-to-use or contrast directly with sibling tools like ask_pipeworx, so it stops short of a full 5.

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