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, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it routes to 5,529 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and is one fast call. 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 long but every sentence earns its place. It opens with a clear directive ('PREFER OVER WEB SEARCH'), covers domain scope, routing mechanics, trigger phrases, examples, and explicit escalation paths. The structure is well-organized and front-loaded with the most critical usage guidance.

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 (routing across 5,529 sources), the description is remarkably complete: it explains what data domains are covered, when to use the tool, how it behaves (fills args, returns citations), performance characteristics, and when to step up to grounded research or deep_research. No output schema exists, but the description adequately describes the return format.

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

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

Schema coverage is 100%: both the 'question' parameter and its aliases (q, text, input, query, prompt) are described, with examples in the schema. The description repeats the notion of a 'question' but does not add meaning beyond the schema. Baseline 3 is appropriate since the schema carries the parameter-semantics 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 clearly states the tool's purpose: answering factual questions about real-world data by routing to thousands of verified sources and returning structured answers with citation URIs. It uses specific verbs ('ask', 'routes', 'returns') and distinguishes from siblings by naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Explicit guidance is given: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and detailed conditions for when to use alternatives ('for a hallucination-resistant single answer use ask_pipeworx_grounded; for a broad/multi-part question use deep_research'). Trigger phrases like 'what is', 'look up', and examples further clarify 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context beyond this: it's a beta with no active candidate, matches ask_pipeworx exactly right now, and results are compared to the stable router for merging decisions. This tells the agent the tool is safe to use experimentally and won't fall back to another service.

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

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

The description is moderately long but well-structured, starting with the beta designation and then detailing equivalence, current state, and usage guidance. Some redundancy exists (e.g., 'identical' and 'matches ask_pipeworx exactly' overlap), but each clause contributes important context. It's not overly verbose for the complexity.

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

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

Given the lack of an output schema, the description mentions 'same response shape' but does not detail what that shape is, relying on the user's familiarity with ask_pipeworx. It covers the tool's relationship to the stable router, its experimental nature, and safety profile. For a beta tool, this is reasonably complete, though a brief note about return format would improve it.

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

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

The input schema fully documents all six parameters, all aliases for 'question' with descriptions. The description does not add any parameter-specific semantics beyond what the schema provides. Since schema coverage is 100%, a 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 identifies this as a beta version of the ask_pipeworx universal router, with the same 5,529 tools and response shape. It distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded by emphasizing its experimental routing and live comparison against the stable router. The verb 'ask' and context of a router make its purpose unmistakable.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing,' giving clear usage context. However, it does not provide explicit exclusions or mention ask_pipeworx_grounded as an alternative, so it's not a full 5. It also clarifies that it currently behaves exactly like ask_pipeworx, which helps the agent 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?

The description goes well beyond annotations by detailing the refusal mechanism with all possible refusal_reason values, the exact return shape, and the constraint that answers are extracted 'using ONLY what the tool result contains.' It also discloses the extra LLM call cost, which annotations do not cover.

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

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

The description is dense but each sentence earns its place, starting with a clear one-liner summary. The return format and refusal reasons are verbose but necessary for a tool meant for high-stakes uses. Slightly over-specified, but justified by the tool's complexity.

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

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

With no output schema, the description fully specifies the return object on success and the refusal object with all exit reasons. It also provides routing context, cost trade-offs, and a comparison to the sibling ask_pipeworx, making it complete for an agent to decide 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 input schema already covers all six parameters (question plus five aliases) with 100% description coverage. The tool description adds no parameter-specific meaning beyond saying it 'fills arguments' internally, but the schema fully handles semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains its process: same routing as ask_pipeworx, fetch data, then extract answer only from the tool result. It distinguishes itself from the sibling ask_pipeworx by explicitly naming it and noting the grounding and refusal 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 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides examples like financial verdicts and legal claims. It also tells the agent to 'prefer ask_pipeworx for casual lookups,' clearly defining when not to use this tool.

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

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

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?

Despite already having annotations for readOnly and idempotent, the description adds substantial behavioral context: it reveals account/permission requirements (free sign-in, paid plan for 'thorough'), performance expectations (15-60s, up to ~90s), the decomposition and parallel-routing architecture, the guarantee not to invent answers (gaps[]), and the semantic excerpting of large records. It also explains the hop/iteration behavior and the stability of pipeworx:// citations. This goes well beyond what annotations provide, with 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 long but every sentence carries essential operational information: account requirements, alternatives, comparison to sibling tools, output format, latency, citation guarantees, and parameter nuances. It is front-loaded with the most critical constraint (account required) and the primary alternative (ask_pipeworx), then flows logically through behavior and edge cases. There is no filler or repetition of schema annotations.

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 present, the description fully takes over the job of describing return values: it lists 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding', plus 'gaps[]' and 'contradictions[]' arrays, and explains the 'hop' field and citation_uri fetchability. It also covers limitations (missing structured coverage, load times) and use cases. The tool is complex, but the description leaves no major operational or behavioral gap unaddressed.

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 provides 100% parameter coverage, so the baseline is 3. The description adds meaningful semantics by explaining the effect of the 'depth' parameter on facet count and iteration ('quick=3 (single hop)', 'standard=5...', 'thorough=8 (paid)') and by noting that 'thorough' requires a paid plan. It also clarifies that the 'question' parameter supports natural language and broad/multi-part phrasing, which is not fully obvious from the schema. This extra context justifies a score above baseline.

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

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

The description opens with a precise verb-resource pair: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call, making it clear the tool performs aggregated research rather than a simple lookup. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, stating 'this is NOT open-web search' and positioning itself for 'broad/multi-part questions over structured data.' This far exceeds a vague or tautological statement.

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?

Guidance is explicit and actionable: 'If you are not signed in, use ask_pipeworx instead,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx' are direct when-to-use/when-not-to-use statements. The description also names concrete alternative tools (ask_pipeworx) and the conditions under which deep_research is appropriate, fulfilling the highest bar for usage guidance.

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

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

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: fans out across multiple sources, returns specific fields, and notes patent limitations. 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 long but packed with essential information. It front-loads example prompts and priority instruction. Could be slightly more concise, but effective given the tool's complexity.

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

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

Despite no output schema, the description thoroughly lists all return components (cik, company_name, filings with URIs, fundamentals, patents, news, LEI) and explains the patent sunset. Highly 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%, but the description adds meaning: explains enum constraint (only 'company'), value formats (ticker or zero-padded CIK), and that names are not supported. This adds value beyond the schema.

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

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

The description explicitly states 'full cross-source profile of a US public company in ONE parallel call' and provides example user prompts. It clearly distinguishes itself from siblings by recommending preference over chaining single-source lookups.

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

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

Provides clear when-to-use guidance (holistic view requests) and when-not-to (names not supported, refers to resolve_entity). Also notes patent sunset and soft-fail behavior.

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?

Annotations indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral context: explains two modes, response structure (leg-by-leg prices, top spreads), safety fields (compatibility_warning with two cases), temporal_alignment, and skipped counters. It also notes that real spreads are rarer than the list suggests. No contradiction with annotations.

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

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

The description is well-structured into sections: purpose, modes, response, safety fields. It is front-loaded with the core idea. While somewhat lengthy, every sentence adds value and no information is redundant. It is efficient for the complexity it covers.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is thorough. It explains the return structure (leg-by-leg prices, top spreads, safety fields), covers edge cases (compatibility_warning scenarios, temporal misalignment), and provides guidance on interpreting results. Without an output schema, the description fully carries the burden of explaining what the tool returns.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaning beyond the schema: lists the 10 topic shortcuts with their auto-fetching behavior, explains that explicit parameters override topic mapping, and provides examples. This adds significant value for a tool with high schema coverage.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies two modes (topic and explicit) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue spreads. The description provides a specific verb and resource, making the purpose 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 gives explicit guidance on when to use each mode (topic for pre-mapped shortcuts, explicit for custom pairings) and warns that most pre-mapped topics return compatibility warnings. It explains safety fields and temporal alignment conditions. While it doesn't explicitly mention alternatives among siblings, it provides enough context for 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 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 establish safety (read-only, idempotent, open-world, non-destructive), and the description adds significant behavioral detail: identifiers are labeled with their source, unresolved identifiers are stated explicitly under `unresolved`, LEI/FIGI enrichment degrades gracefully when external services are unavailable, and the tool cascades through multiple lookup endpoints internally. These details go well beyond what annotations provide and set clear expectations for failure modes.

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

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

The description is comprehensive but slightly dense, with a long opening example list and parenthetical nested details. It is well front-loaded with the core purpose and usage directive, and every sentence provides useful context. A small reduction in parenthetical detail could improve readability without losing essential information.

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

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

Given the tool's complexity (multiple entity types, multiple identifier sources, no output schema), the description is remarkably complete. It covers what outputs to expect, how unresolved identifiers are handled, graceful degradation of optional enrichments, and internal cascading calls. The absence of an output schema is compensated by a thorough conceptual explanation of return behavior.

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

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

The schema already documents both parameters fully (enum for type, descriptions for value), so the baseline is 3. The description adds extra value by giving concrete examples for `value` per type (e.g., 'AAPL', '0000320193', 'ozempic') and clarifying what each type returns (company leads to CIK/ticker/LEI/FIGI, drug leads to RxCUI). It enriches rather than merely restates the schema.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides a specific verb ('resolve') and resource (entity names to identifiers), distinguishes from siblings by listing supported ID types (CIK, LEI, FIGI, RxCUI), and explicitly directs 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit usage guidance with the sentence 'Use FIRST whenever you have a name but need an ID,' which defines the primary use case. It also notes that it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly name alternative tools (e.g., 'lookup' or 'entity_profile') or state when NOT to use this tool, such as when an ID is already known.

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.