Bookbrainz

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

Annotations already show readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: default free model, BYO key for Anthropic with direct payment, and return structure.

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 4 sentences, front-loaded with the main action. Every sentence adds value 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 4-param tool with full schema coverage and annotations, the description explains the return structure and use cases completely, 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?

All 4 parameters are described in the schema (100% coverage). The description adds meaning by specifying the default model and explaining the _apiKey's cost implication, going beyond the schema.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs for AI visibility', scoring 0-100 per model. It distinguishes itself from sibling tools like compare_entities or scan_competitor_ai_presence by focusing on a specific visibility metric.

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 context for usage: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. However, it does not explicitly state when not to use or suggest alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds genuine context by revealing the router behavior and, crucially, that the tool 'fills arguments' itself — telling the agent to pass a natural-language question rather than parameterize. It also discloses the citation-URI return trait; 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 roughly 250-word description is long but unusually information-dense: it front-loads the critical routing decision ('PREFER OVER WEB SEARCH'), then proceeds What → When → Examples → When-not. There is minor redundancy between the 'Use whenever...' trigger list and the closing 'START HERE... unless...' exclusion, so it isn't perfectly lean.

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 router (5,798 tools, no output schema) with a single required param and strong safety annotations, the description is nearly complete: purpose, usage, exclusions, alternatives, examples, and the return shape (structured answer with pipeworx:// URIs). The remaining gaps are minor — the exact answer structure and behavior when no source matches are left unspecified.

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 six params are documented as aliases of 'question'. The description adds example queries and implies only the free-text question matters ('fills arguments'), but it doesn't specify format or constraints beyond what the schema provides. Baseline 3 is appropriate since the schema fully carries the parameter documentation burden.

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

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

The description states a specific verb and resource: it 'routes the question to the right one of 5,798 tools across 1517 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This is no tautology and clearly differentiates it from siblings like search, lookup, and deep_research by establishing it as a meta-router over authoritative data sources.

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

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

Explicitly opens with 'PREFER OVER WEB SEARCH', enumerates trigger phrases ('what is', 'look up', 'get the latest', 'current'), gives six concrete examples, and states exclusions: 'unless you already know the specific source/tool to use, or the question requires live, unverified, or real-time data' — then names alternatives ('web search... or other tools'). This is textbook when/when-not/alternatives guidance.

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

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

The description reveals important behavioral traits beyond the annotations: live candidate routing improvements, the current inactive-candidate state, no fallback, and the assurance that this is a full working router. This gives an agent a realistic picture of possible behavior changes without contradicting the read-only/idempotent hints.

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

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

Every sentence carries distinct information: identity, current state, usage instruction, comparison purpose, and no-fallback guarantee. The description is dense but not redundant, and it front-loads the most important identity and behavior 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?

The description covers identity, current state, usage, and behavioral caveats well. It does not independently describe the response format, though it points to 'same response shape' as ask_pipeworx, which is sufficient if the agent can reference that sibling tool.

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

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

The input schema has 100% coverage, documenting the question parameter and all aliases. The description only says 'same arguments' as ask_pipeworx, which adds no parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies ask_pipeworx_beta as a beta universal router with the same toolset, arguments, and response shape as ask_pipeworx. This conveys the core ask-and-route function and distinguishes it from the stable sibling by its experimental status and current matching behavior.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired and notes that results are compared against the stable router to decide merges. This provides an actionable selection rule and names the alternative without leaving the choice to inference.

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

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

Annotations already provide read-only, non-destructive, idempotent signals, and the description adds rich behavioral detail: exact success payload shape, explicit refusal reasons, verbatim evidence extraction, and the extra LLM call cost. It does not contradict 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?

Every sentence earns its place: purpose, mechanism, return contract, usage context, and cost/alternative. The structure front-loads the core identity and avoids filler or redundancy.

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

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

Given there is no output schema, the description appropriately documents the complete success and refusal response shapes, including the refusal_reason enum values. Combined with the fully covered parameter schema and explicit sibling comparison, nothing needed for correct invocation 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%, and the schema fully documents the single required question parameter and its aliases. The description adds no parameter-level detail, but the schema already carries that burden adequately.

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 'Hallucination-resistant answer mode for high-stakes reads,' clearly defining the tool as a specific grounded answer mode. It also distinguishes itself from ask_pipeworx by explaining that it 'EXTRACTS the answer using ONLY what the tool result contains,' making sibling differentiation 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 provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and gives a clear preference rule: 'prefer ask_pipeworx for casual lookups.'

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

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

The description extensively details behavioral traits: market resolution, classification, fan-out to data sources, response shapes, error handling (429s, low-confidence, closed markets), and resolution-rule risk. Annotations already mark it as read-only and idempotent; the description adds rich context without contradiction.

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

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

The description is long but well-structured with sections for classifiers, fan-out examples, response shapes, resolver contract, and safety. Every sentence adds value, though some details could be condensed. Front-loaded with a one-sentence summary.

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 (3 params, no output schema, rich behavior), the description is exceptionally complete. It covers inputs, processing steps, all output fields (market, analysis, evidence, resolver contract, parent event, news fields, safety mechanisms). 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 three parameters. The description adds significant meaning: market can be slug, URL, or question text; depth explains quick vs thorough fan-out; include_raw explains summary vs full payload and use cases.

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 researches a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-model comparison). It explicitly says 'Use for "should I bet on X"' which distinguishes its purpose.

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

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

The description provides explicit when-to-use examples ('should I bet on X') and covers safety constraints (low-confidence matches, closed markets, wide spreads). It also advises inspecting fields like market_match_confidence and cancellation_rule before relying on analysis.

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 read-only, open-world, idempotent, non-destructive hints. Description adds the filtering-by-related-entity behavior, which is consistent with annotations but not revealing further behavioral traits beyond what annotations convey.

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

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

Two sentences with immediate purpose statement and illustrative examples, 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?

The description and schema together cover the tool's inputs and behavior. An output schema exists (not shown), so return values are presumably documented elsewhere. Pagination via offset/limit is in schema but not elaborated in description, slightly reducing 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?

With 100% schema coverage, the schema already documents all parameters. The description adds value through examples showing how parameters combine (e.g., work, author with limit), which clarifies the filtering semantics.

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

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

The description clearly states the verb 'browse' and resource 'entities of a type filtered by a related entity', with concrete examples differentiating it from sibling tools like 'search' or 'lookup'.

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

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

Clear context for use: browse by type with related-entity filtering. No explicit when-not-to-use or alternatives mentioned, but the purpose is distinct enough for an agent to infer appropriate usage.

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

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

Annotations already indicate safety (readOnly, idempotent). The description adds valuable behavioral details: handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and specifies data sources (SEC EDGAR/XBRL, FAERS, etc.) – all 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 front-loaded with example queries and well-structured. While somewhat lengthy, each sentence adds value; a slight trim could improve conciseness 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?

The description fully covers the tool's return value (paired data + citation URIs), data sources, and handling logic. Given the absence of an output schema, this provides sufficient context for correct selection and use.

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

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

Schema coverage is 100% and includes descriptions. The description adds examples (tickers/CIKs, drug names) and clarifies max/min bounds, providing extra context that aids correct invocation.

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

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

The description clearly states the verb and resource: 'side-by-side comparison of 2–5 companies or drugs'. It distinguishes from siblings by emphasizing efficiency over sequential lookups, and provides example queries that map to the tool's function.

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 to prefer this tool over sequential single-pack lookups for comparisons, and includes example user queries. However, it does not explicitly state when not to use it (e.g., for single entities), so guidance could be slightly more complete.

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

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

The annotations already cover safety (read-only, idempotent, non-destructive), and the description adds substantial behavior: auth/plan requirements, parallel decomposition across 5,798 tools, gap reporting with never-invented findings, contradictions[], semantic excerpting, citation resolvability, and latency expectations. No behavior contradicts 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 long but densely informative, and critical constraints (account required, fallback tool) are front-loaded. It loses a point for being a single sprawling paragraph with some repetition around citations/gaps/contradictions, but every sentence contributes operational value.

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

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

With no output schema, the description thoroughly explains what the agent will receive: evidence, confidence, source, fetched_at, citation URI, gaps[], contradictions[], and hop metadata. It also covers latency, auth, and depth differences, making it complete for a complex parallel research tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by tying depth:'thorough' to a paid plan and clarifying the operational implications of each depth mode. The description also reinforces that broad/multi-part questions are valid for the question parameter, though the schema already covers the core semantics.

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

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

The description names a specific verb-resource ('Grounded multi-source research across Pipeworx's structured data sources') and explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups. It gives enough detail about decomposition and the findings packet that an agent can tell it apart from every sibling tool.

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 when to use this tool ('broad/multi-part questions over structured data'), when not to ('For a single lookup use ask_pipeworx'), and even the signed-in prerequisite with a fallback tool. This is explicit routing guidance rather than implied context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds beyond by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas... each result is ready to call directly, no second schema lookup needed'. No contradiction.

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

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

The description is a single paragraph but front-loaded with purpose and context. It is detailed yet concise, with no wasted sentences. Could be slightly more structured but effectively communicates key information.

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

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

Given the tool's complexity (6 params, no output schema) but with strong annotations, the description covers return format, readiness for direct use, and provides examples. Lacks explanation of how to use returned results in subsequent calls but is otherwise complete.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description emphasizes natural language input and lists aliases but does not add substantial 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 clearly states the tool finds tools by describing data or task, provides extensive domain examples, and explicitly distinguishes itself from siblings like search, browse, and lookup by saying 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools'.

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

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

The description gives explicit guidance on when to use ('Call this FIRST when you have many tools available and want to see the option set') and lists specific domains. It implies an alternative (not for one answer) but does not explicitly state when not to use or name sibling 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 goes far beyond the annotations. It discloses that the USPTO patents source will soft-fail due to a May 2025 API sunset, that empty sections are real 'no data' (not bugs), and that a private company returns a structured resolved:false instead of failing. It also details the return structure for each data segment. This is exemplary transparency that no annotation alone could provide.

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

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

The description is long, but every sentence carries dense, useful information. The front-loading of example queries and the core value proposition immediately tells the agent what this tool is for. The structure uses semicolons and lists to pack many sources and behaviors into a compact block. While some redundancy exists (e.g., repeating the input types), the overall density justifies the length.

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

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

Given the tool's complexity (eight data sources, no output schema), the description is remarkably thorough. It explains each source, the exact return fields, fallback behavior (GDELT→GNews), and edge cases (no biologics, private companies, empty sections). An agent has everything needed to decide when to call it and what to expect in response, without needing to inspect any other 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% (both parameters fully documented in the schema), so baseline is 3. The description adds extra clarity: it emphasizes that type and value are interchangeable, elaborates on the value variants (ticker, CIK, name), and notes that name resolution happens via SEC EDGAR company-name match. It also explains the resolved:false outcome for private companies, which enriches the semantics 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 opens with concrete example queries and immediately states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It names the specific sources (SEC EDGAR, XBRL, USPTO, etc.) and the key output fields. It also differentiates itself from chained single-pack lookups by explicitly instructing to prefer it for holistic views, which clearly distinguishes it from sibling search/lookup tools.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear when-to-use condition. It also explains the expected input types and the behavior for private companies (resolved:false with notes), which helps the agent avoid misusing it. While it doesn't list all sibling alternatives, the targeted guidance is specific and actionable.

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

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

Description confirms destructive behavior (delete) aligning with annotations (destructiveHint=true). Adds context about clearing sensitive data and purpose, which adds value beyond annotations.

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

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

Description is extremely concise: one sentence for purpose, one for usage. No wasted words, highly efficient.

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

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

For a simple tool with one parameter and no output schema, the description fully covers what it does, when to use it, and relationships with siblings. 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 a clear description for 'key'. Description does not add additional semantic detail beyond the schema; baseline score 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?

Description clearly states 'Delete a previously stored memory by key,' specifying both verb and resource. It distinguishes the tool from siblings 'remember' and 'recall' by mentioning them.

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

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

Explicit usage cases are provided: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with remember and recall, indicating alternatives.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds that the tool fetches the page, extracts title/description/key links, and emits standard format—valuable behavioral context beyond the annotations.

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

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

The description is well-structured and front-loaded with the core purpose. It could be slightly trimmed, but every sentence adds value.

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

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

For a simple tool with 2 parameters and no output schema, the description fully explains what the tool does, the output format, and deployment context. Nothing essential 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% with both parameters documented. The description mentions default and max for max_links, but this repeats schema info. No additional semantic value added 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 generates a production-ready llms.txt file for any URL, specifying the output format (markdown) and deployment location (site-root/llms.txt). This distinguishes it from sibling tools like browse or search.

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

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

Concrete use cases are listed (indexing client sites, personal projects, competitor auditing), providing clear guidance. However, it does not explicitly state when not to use the tool 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the returned fields and the optional parameter, but the core behavioral traits are already covered by annotations.

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

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

The description is concise: two sentences. The first sentence states the purpose and output fields; the second provides usage guidance. Every sentence is informative and necessary, and the structure is front-loaded with the core purpose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It lists the return fields, explains the parameter, and provides usage context. Annotations cover safety. No gaps remain.

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 'include_inactive', whose description clearly explains its effect. The description does not add additional meaning beyond the schema, so a baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' This is a specific verb ('list') and resource ('subscriptions'), and it distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by indicating it is the listing counterpart. It also enumerates the fields returned.

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

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

The description explicitly states when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for usage and differentiates from 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 readOnlyHint=true and destructiveHint=false; the description aligns and adds behavioral detail (entity types, optional includes). 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?

Single, clear sentence with no redundant words. Front-loaded with the core action and entity types.

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

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

Given the presence of output schema, rich annotations, and full parameter coverage, the description is complete enough for an agent to use the tool correctly.

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

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

Schema coverage is 100% and includes parameter descriptions. The description adds context about optional sub-resources and the includes format, but does not significantly extend beyond schema info.

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

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

The description specifies the action ('Fetch'), the resource ('BookBrainz entity'), the identifier ('UUID'), and the allowed entity types, explicitly distinguishing it from sibling tools like 'search' 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?

Description clearly states the tool is for fetching a single entity by UUID, implying usage. It does not explicitly mention when not to use or alternatives, 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?

All annotations are false, so the description carries the burden of behavioral disclosure. It discloses rate limiting (5 per identifier per day), that it is free and does not count against quota, and the claim_token workflow for tracking feedback. This goes beyond annotations, though it could mention any write side effects more explicitly; still, it provides strong operational 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 longer than average but every clause contributes actionable guidance: usage triggers, exclusion criteria, token mechanics, and limits. It is front-loaded with the core purpose and then logically flows into usage details, making it efficient despite its length.

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

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

For a tool with zero required parameters, a nested context object, and no output schema, the description covers everything an agent needs: when to file, what to include, how to follow up with a token, and behavioral constraints. It even explains the return behavior of claim_token in the absence of an output schema, making it fully contextual.

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

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

Schema covers 100% of parameters, so the baseline is 3. The description adds meaning beyond the schema: it instructs users to describe issues in terms of Pipeworx tools/packs, warns against pasting end-user prompts, and explains how claim_token is used as a standalone argument to check status—details that enrich parameter understanding.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly establishing a specific action (sending feedback) and target resource (the Pipeworx team). It enumerates concrete feedback categories (bug, feature/data_gap, praise), which differentiates it from sibling tools like 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?

It explicitly states when to use the tool: for bugs, feature requests, data gaps, or praise. It also clarifies when NOT to use it—if the tool came from a different MCP server, the user should file with that server instead—and provides a method to disambiguate ('Not sure? Pipeworx tool names are the ones this connection lists').

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 value by explaining data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h), which are not covered by annotations.

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

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

The description is concise, front-loaded with core functionality, and lists use cases efficiently. Every sentence adds value with no redundancy.

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

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

For a simple tool with 1 parameter and no output schema, the description fully explains what is returned (top tools, top packs, call volume), the data source, privacy, caching, and use cases. Nothing is missing for an agent to select and invoke correctly.

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

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

The only parameter (window) has 100% schema description coverage. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which helps the agent choose appropriately 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 uses a specific verb ('Returns') and clearly states the resource: top tools, top packs, and total call volume over a recent window. It lists three explicit use cases, distinguishing it from siblings like discover_tools by focusing on trending usage.

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 concrete use cases are provided (discovering hot data sources, confirming canonical tool, seeing alignment). While not stating when not to use, the context is clear enough for an AI agent to decide. No explicit alternative is named, but the intention is well-understood.

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 important behavioral traits beyond annotations, including the fill check (theoretical vs realizable edge), partition filter (placeholder slugs), and semantic anchor (Jaccard similarity). It warns about not trading when overround exists only at last-trade. Consistent with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is well-structured with clear sections (default mode, event mode, topic mode, semantic anchor, partition filter, response, fill check). Every sentence adds value, and the length is justified by the tool's complexity. It is front-loaded with the main purpose.

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

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

Given the tool's complexity, the description covers all necessary aspects: parameter modes, edge cases (placeholder slugs, low similarity), response format, fill check logic, and references to related tools. No gaps for an agent to misuse the tool.

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

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

The description adds substantial meaning beyond the input schema, explaining default mode (no args = trending_scan), accepted input formats (full Polymarket URLs), and detailed behavior for each parameter (event: walks child markets, date-axis ordering; topic: cross-event scanning with similarity filter).

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket arbitrage opportunities) and methodology, distinguishing itself from sibling tools like 'polymarket_fill_risk' 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?

The description provides explicit guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It also explains when not to trade (if realizable_edge_pp <= 0) and directs to 'polymarket_fill_risk' for custom sizing.

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

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

The description discloses extensive behavioral traits beyond annotations: it is a read-only scan (consistent with readOnlyHint=true), includes model families, response structure (by_segment, diagnostics), caching (1h KV keyed on knobs), and edge calculation details (slippage, kelly). No contradictions with annotations.

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

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

The description is very long and detailed, which is necessary given the tool's complexity, but some sections (e.g., detailed model family explanations) could be condensed. It is front-loaded with the main purpose, but the overall length may reduce readability for agents. A more structured format (e.g., bulleted list) would improve 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?

Despite no output schema, the description covers return values (fields like edge_pp_net, kelly_fraction, market statistics, diagnostics) and explains edge-case handling (empty segments, Fed bets). It also addresses caching and filter behaviors. However, it lacks a concrete example of the response format, which would aid 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?

All 9 parameters have 100% schema description coverage, so baseline is 3. The description adds value by explaining tradeable-edge knobs (e.g., 'Set to 2 to require tight books'), providing defaults and usage guidance (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). This goes beyond schema basics.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs (scan, return) and a specific resource (Polymarket markets), distinguishing it from sibling tools like polymarket_arbitrage. The phrase 'Built for what should I bet on today' further clarifies its use case.

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

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

The description explicitly states the tool is for discovering opportunities to bet on, avoiding manual paging through markets. It provides context on when to use it (e.g., discovering edges) and what parameters adjust behavior (min_liquidity, max_spread_pp, etc.). However, it does not explicitly differentiate from siblings like polymarket_edge_tracker, but the specialized edge-calculation focus is implied.

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

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

Adds significant behavioral context beyond annotations: explains data source (daily snapshots), constraints (60-day TTL, snapshot start), and how decay is computed (daily closes, not intraday). Fully consistent with readOnlyHint=true and destructiveHint=false.

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

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

Information-dense single paragraph; purpose is front-loaded. Could be improved with bullet points for clarity, but no wasted words.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and data limitations. Covers all necessary context for an agent to understand what is returned.

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 context: defaults (14 days, '1wk'), max range (30 days), and explains the effect of 'window' on snapshot family. The response description further clarifies parameter impact.

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 'edge persistence and decay telemetry' and concretely answers 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling 'polymarket_edges' by focusing on historical trends versus current snapshots.

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

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

Provides a clear use case (understanding edge age and decay) and implies that for fresh edges one should use polymarket_edges. Does not explicitly list alternatives or 'when not to use', but the context is clear.

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

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

Annotations indicate read-only, idempotent, non-destructive, and open-world. The description adds significant behavioral detail: walks the ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and for baskets includes theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk. No 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 dense and front-loaded with the core purpose. It uses capitalization for emphasis and sections for modes. While it could be slightly more concise, every sentence adds value and the structure helps readability. A minor deduction for length, but well-organized.

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 all return fields for both single-market and basket modes, including edge cases like thin legs and forced directional risk. It also provides practical usage context, making the tool's behavior fully transparent 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?

Schema description coverage is 100%, yet the description adds meaningful context beyond the schema. For size_usd, it explains 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional' for basket. It also clarifies default side logic for basket mode. This enhances understanding beyond the basic schema descriptions.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live order book depth. It explicitly differentiates from sibling tools (polymarket_arbitrage, polymarket_edges) by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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

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

Provides explicit when-to-use guidance: before arbitrage signals or edges above $500. Also warns against partial basket fills converting an arb into an unhedged directional position, giving context on when not to rely on the tool alone. Siblings are listed, and the description positions this tool as a prerequisite step.

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?

This is unusually transparent. It discloses that matching is keyword and word-overlap based, not source-verified, and lists compatibility codes, per-leg flags, skipped comparisons, fee treatment, and gross-vs-net spread limitations. It also clarifies the false-alarm condition where temporal_alignment is null. These details go far beyond the readOnly/idempotent annotations and give the agent accurate expectations about reliability.

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

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

The description is well-structured and front-loaded with the core purpose, but it is very long and somewhat repetitive — for example, 'both modes run the identical token-overlap matcher' and the EITHER mode emphasis appear multiple times. It earns most of its sentences, but a more condensed version would improve scannability for an agent.

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

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

With no output schema, the description carries full responsibility for explaining the response shape, and it does so thoroughly: it covers top_spreads_pp, compatibility_warning and codes, flags, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, fees_note, and skipped counters. It also addresses null interpretations and edge cases, so an agent has enough context to 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?

The schema already gives 100% parameter coverage, so the baseline is 3. The description adds meaningful semantic value by explaining how the parameters interact: topic auto-fetches mapped events, while kalshi_event_ticker and polymarket_event_slug override the mapped sides. It also clarifies that both modes run the same matching logic, which removes a common misconception about mode-specific behavior.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the operation, the two data sources, and the core output (spread in percentage points). It also differentiates itself from single-venue tools like polymarket_edges by emphasizing cross-venue matching and compatibility checks.

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 clearly explains two usage modes — topic shortcuts vs explicit ticker/slug pairings — and tells the agent when each is appropriate. It also warns that pre-mapped topics are not necessarily tradeable and that returned pairs still need compatibility checks. It does not explicitly name alternative sibling tools or give when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping detail (anonymous IP, BYO key hash, account ID) beyond annotations.

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

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

Three concise sentences, front-loaded with primary function. Every sentence adds value with no redundancy.

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

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

Complete for a simple retrieval tool with thorough annotations and schema. Describes scope, pairing, and scoping. No output schema, but return values are 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?

Only one optional parameter with schema covering its behavior (omit to list). Description echoes the schema but adds no new semantic value beyond pairing context.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys if omitted. It explicitly distinguishes from sibling tools 'remember' and 'forget' by naming them and describing the pairing.

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

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

Provides clear usage context: retrieving stored data like tickers or research notes without re-deriving. Mentions pairing with 'remember' and 'forget'. However, no explicit when-not-to-use guidance.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds behavioral details: mark_read flags events as read, iso timestamp format, returned fields (source, citation_uri, raw payload). 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?

Five focused sentences, front-loaded with main action. Every sentence adds value. 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?

Covers return fields, filter options, mark_read behavior, polling suitability, and alternative access. All essential info for a 5-param read-only 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% with param descriptions. Description adds meaning: example type 'sec_8k', effect of mark_read, and that since expects ISO timestamp. Exceeds 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?

Clearly states 'Pull fired events from your subscription feed. Returns the most recent alerts...' Verb 'pull' and resource 'fired events' are specific. No sibling tool directly overlaps, making differentiation natural.

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 context for usage: 'Polls work fine' and mentions alternative access via HTTP endpoint. However, lacks explicit when-to-use vs siblings like list_subscriptions or subscribe.

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 valuable behavioral details: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), describes rate-limit handling, and notes the USPTO API sunset. No contradiction with annotations.

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

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

Single, well-structured paragraph front-loaded with example queries. Every sentence adds meaningful information, no wasted words.

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

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

Given the complexity (multiple data sources, error handling, output structure), the description covers all key aspects. Though no output schema exists, it explains the return format (changes[] grouped by source, total_changes count, citation URIs).

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

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

Schema covers all parameters with descriptions (100% coverage). Description adds extra examples and guidance, such as 'Use "30d" or "1m" for typical monitoring' and explains relative shorthand formats ('7d', '30d').

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 provides a change feed for a company, with specific examples like 'What's new with X' and 'latest on Y'. It distinguishes itself from sibling tool 'entity_profile' by noting that entity_profile is for static profiles regardless of window.

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

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

Explicitly states when to use this tool vs the sibling 'entity_profile' ('Use entity_profile instead when you want the static profile...'). Provides example inputs and context for when to use recent_changes (e.g., 'updates on Acme').

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 idempotence and non-destructiveness; the description adds behavioral context about persistence across sessions, authentication scoping, and expiration (24 hours for anonymous), going beyond what annotations provide.

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

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

Four sentences, each carrying critical information, front-loaded with core purpose, and no unnecessary words. Efficient and well-structured.

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

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

For a simple two-parameter tool with no output schema, the description adequately covers purpose, usage, pairing, and persistence behavior, leaving no significant 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 covers both parameters with descriptions; the description reinforces meaning with examples like 'subject_property' and 'any text', adding value beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose with a specific verb ('save data') and resource ('data to reuse later'), and distinguishes it from sibling tools like 'recall' and 'forget' by mentioning them explicitly.

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 on when to use ('when you discover something worth carrying forward') and how it pairs with other tools ('pair with recall to retrieve later, forget to delete'), with context about authentication and retention.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, but the description adds rich behavioral detail: cascading through multiple endpoints, returning unresolved identifiers explicitly, using figi_candidates on ambiguity, and degrading gracefully if GLEIF/OpenFIGI are unavailable. 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 examples and the 'Use FIRST' directive, but the company type section is a dense wall of nested parentheticals that is hard to scan. Every piece of information is useful, yet the structure hurts readability enough to keep this below 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?

For a tool with only two parameters and no output schema, the description covers input constraints, failure modes, ambiguous-result behavior, fallback degradation, and what fields the output contains. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes well beyond the schema by explaining the value parameter: pass the entity name only, for bonds pass the issuer exactly as printed, and never include trailing security-class words. It also details the type enum behaviors for company and drug in depth.

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

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

The description explicitly states the tool resolves a user-spoken name to canonical/official identifiers, with concrete examples like ticker, CIK, LEI, and RxCUI. It clearly distinguishes itself from siblings by emphasizing that it returns the identifiers other tools require as input.

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 strong guidance: 'Use FIRST whenever you have a name but need an ID' and clarifies supported types and edge cases like non-ticker instruments. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks the full when/when-not/alternatives structure.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral specifics: probes each entity with ai_visibility_check, treats first entry as 'subject' for narrative, and returns ranked list with score, confidence, signal density. No contradictions.

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

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

The description is four sentences, front-loaded with the main action, and every sentence adds unique value: comparison, process/ranking, use case, output specification. No wasted words.

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

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

Given that the tool has 4 parameters, 100% schema coverage, and thorough annotations, the description is complete: it explains the ranking, the narrative for first entity, the output fields. Could mention the ranking order explicitly, but it is implied by 'most/least recognized'. No output schema is needed because return values are described.

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

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

All 4 parameters have schema descriptions (100% coverage). The description adds important context beyond schema: the first entity is treated as the subject, the context parameter disambiguates common names, and the models parameter's relationship to Anthropic key. This enriches meaning.

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

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

The description clearly states the tool compares AI visibility across multiple entities, distinguishes itself from the sibling ai_visibility_check (which is for single entities), and explains the ranking and output. This is specific and differentiates from similar tools.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and explains the context parameter for disambiguation. It implies that for single entities one would use ai_visibility_check, but does not explicitly state when not to use this tool, which prevents a 5.

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

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

Adds significant behavior: partial failures degrade gracefully, bundlephobia measurement can take 5-30s, sources_failed lists timeouts. Annotations already indicate readonly/idempotent, but description enriches with practical details.

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 dense but well-structured: single paragraph starting with core purpose, then details on return value, boundaries, and edge cases. Slightly long but earned.

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 lists all return fields (summary, per-advisory, links, alternative versions) and handles partial failures. Complete for the tool's complexity.

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

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

Schema already covers both parameters with descriptions (100% coverage). Description adds minor clarification about scoped packages, but adds little beyond schema.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, covering license, advisories, bundle size, etc. It distinguishes itself from siblings by specifying its unique composite nature and ecosystem scope.

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

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

Explicitly tells when to use: when an agent asks about safety, popularity, or cost of an npm package. Also states alternatives for other ecosystems (PyPI, Maven, etc.) under 'deps.dev:version directly'.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive traits. The description adds domain-specific context (BookBrainz database, returns BBIDs) and the tool's purpose, which complements annotations without contradiction.

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

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

Two sentences, each serving a distinct purpose: defining the action and resource, then describing the result and its use. No redundant information, highly efficient.

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

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

Given the presence of an output schema and comprehensive annotations, the description sufficiently covers what the tool does and the nature of its return. The addition of 'BBIDs for use with lookup' provides useful 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 coverage is 100% with each parameter already described (type, limit, query, offset). The description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches BookBrainz for specific entity types (works, editions, etc.) using free-text queries and returns matching records with BBIDs for lookup. It uses a specific verb and resource, and distinguishes from sibling tools like lookup and search_within.

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 the result is for use with lookup but does not explicitly state when to use search versus siblings like 'search_within' or 'resolve_entity'. No when-not or alternative guidance is provided.

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

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

The description adds significant behavioral details beyond annotations: truncation at 200K chars with flagging, embedding model BGE-base-en, 500-char overlapping windows, cosine similarity, and output includes character offsets and similarity scores. This is comprehensive and goes well beyond the annotations.

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

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

Approximately 100 words, front-loaded with core purpose. Every sentence adds value, from usage guidance to technical details. 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?

Even without an output schema, the description explains return values (passages with offsets and similarity scores) and constraints (truncation, chunking). This covers all necessary context for an agent to use the tool appropriately.

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 examples for 'query' and emphasizes the max length for 'text', but does not significantly enhance meaning beyond the schema. The added behavioral context indirectly helps but is not directly parameter semantic.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and explains the use case of searching within large documents. It distinguishes the tool from siblings like ask_pipeworx_grounded by specifying the verb 'search' and the resource 'a fetched record', making the purpose specific and unambiguous.

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

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

The description explicitly tells when to use: 'Use when the record is too big to cram into the prompt' and contrasts with ask_pipeworx_grounded, explaining how they pair. This provides clear context and alternatives for the agent.

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

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

The description discloses numerous behavioral traits beyond the annotations, including: Requires OAuth account; subscription id returned; always-on feed with pull method; optional email/sms with verification and rate limits (10/day); webhook with HMAC signing and auto-disable after 10 failures. This fully informs the agent of side effects and constraints.

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

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

The description is well-structured with clear sections for purpose, requirements, supported types, and delivery options. It is slightly verbose (around 15 sentences) but each sentence adds necessary detail, and the core action is front-loaded. Minor redundancy could be trimmed.

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

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

Given the complexity (3 parameters including nested objects, no output schema), the description covers prerequisites, type-specific parameters, return value (subscription id), and delivery limitations. It also notes session keys for webhook and auto-disable behavior. All critical aspects are addressed.

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

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

The description adds significant detail to each schema parameter: it explains each subscription type's required and optional fields with concrete examples (e.g., sec_8k: {ticker, items}, polymarket_edge: {topic, min_spread_bps}). For the delivery parameter, it explains the behavior of each channel, status requirements, and rate limits. The schema coverage is 100% but the description provides actionable context.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id', clearly identifying the tool's action and output. It distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation and detailing supported event types.

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

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

The description specifies that a Pipeworx OAuth account is required, and that anonymous or BYO accounts cannot persist subscriptions, providing clear when-not guidance. It does not explicitly compare with alternatives like 'recent_alerts' but the context of creating ongoing monitoring versus fetching current data is implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: returns category-bucketed example questions with exact tool and argument shapes, drawn from a live catalog, indicating dynamic content. No contradictions.

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

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

The description is front-loaded with the most important usage instruction. It is somewhat long due to listing many aliases, but every sentence adds value. Minor wordiness doesn't significantly detract.

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 only one parameter, no output schema, and rich annotations, the description fully covers the tool's purpose, behavior, return structure, and usage context. No gaps remain.

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 one optional parameter described. The description enhances meaning by explaining that omitting topic gives full spread, passing a topic focuses results, and lists example topic 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 is the onboarding entry point for a new agent, returning categorized example questions. It explicitly distinguishes from siblings like ask_pipeworx by being the first step to understand the agent's capabilities.

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', providing clear context for initial use. It also explains when to omit or pass a topic, though does not explicitly state when not to use it 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?

Discloses soft-delete behavior ('deactivated, not deleted') and ownership check, adding context beyond annotations (e.g., destructiveHint=false, idempotentHint=true align with description).

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

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

Two concise sentences, front-loaded with action and key constraints. No extraneous content.

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

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

Given one well-documented parameter, annotations covering safety, and no output schema, the description fully equips the 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 covers 100% of parameter with description. Description merely repeats 'by id' and notes it's returned from subscribe, adding no semantic depth 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?

Clear verb ('Cancel') and resource ('subscription by id'). Distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement and that cancellation is a deactivation, implying use when you need to cancel your own subscription. No explicit when-not-to-use or alternative tools 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?

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds substantial value: it discloses the source routing logic (SEC EDGAR+XBRL vs grounded pipeline), the expected return format (verdict, actual value with citation, reasoning), and critically clarifies the distinction between 'could_not_verify' (a failure, not evidence) and 'unsupported' (no source found). This is far beyond the annotation surface.

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

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

The description is long and detailed, but every section earns its place: invocation phrases, routing logic, return semantics, and special verdict meanings. It is front-loaded with the natural-language patterns. Minor redundancy exists (e.g., the 'grounded or structured' phrasing repeats earlier pathway details), but overall it is efficiently structured.

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

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

For a tool with two parameters and no output schema, the description fully compensates: it explains the verdict vocabulary, the difference between failure and unsupported, the two processing modes, and the citation format. It even warns callers not to treat 'could_not_verify' as evidence. This is complete enough for an agent to decide when to use it and to correctly interpret results.

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

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

The input schema already documents both parameters (claim and tolerance_pct) with high coverage. The description adds meaningful guidance on tolerance_pct, explaining its default behavior (capped at 5% implied by wording) and recommending 1–2% for hallucination detection. It also provides concrete example claim formats, which helps the agent construct valid input.

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

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

The description clearly states this is a natural-language claim verification tool ('fact check', 'verify the claim that…') and specifies the two distinct processing paths (SEC EDGAR/XBRL fast path for company-financial claims, grounded pipeline for others). This distinguishes it from sibling tools like ask_pipeworx or search, which are general-purpose lookup/answer tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition. It also explains the internal branching based on claim type. However, it does not explicitly name alternatives or state when NOT to use this tool, so it falls 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.