Arxiv

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

The description adds significant behavioral context beyond annotations: it explains the return format (per-model {score, confidence, signals, raw_response} + combined view), cost implications (free default vs BYO for Anthropic), and the fact that it makes API calls to Anthropic if key is provided. Annotations already indicate readOnly and idempotent, but the description enriches agent understanding.

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 (3 sentences) and front-loaded with the core action. Every sentence serves a purpose: main function, default vs extended usage, and example use cases. No wasted words.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (per-model object with score/confidence/signals/raw_response plus combined view). It covers input parameters, optional auth, and usage contexts. For a probing tool with rich annotations, this is complete.

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

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

All 4 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra meaning: it specifies the default model (Workers AI Llama-3.3-70b), explains that `_apiKey` is passed straight through to Anthropic, and that `context` disambiguates. This justifies a 4.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' The verb 'probe' and resource 'LLMs knowledge' are specific, and the scoring quantifies the result. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' which likely have different scopes.

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

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

The description provides clear usage guidance: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use optional parameters like `_apiKey` for Anthropic. However, it does not explicitly exclude cases or compare to very similar siblings, which would earn a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context: it routes among 5,564 tools, fills in arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. 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 longer but efficient: front-loaded with the most critical directive, followed by operational details, examples, and tiered alternatives. Every sentence earns its place, though some minor condensation could improve scannability.

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

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

Given the tool's 6 parameters and no output schema, the description covers purpose, usage boundaries, behavioral traits, and alternatives well. It lacks explicit information about the structure of the returned answer beyond mentioning 'structured answer with citations' but compensates with rich examples and domain scope.

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

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

Schema coverage is 100% and the schema already documents aliases and the purpose of 'question'. The description mentions that the tool 'fills arguments' but does not add detailed semantics beyond what the schema provides. Baseline 3 is appropriate here.

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 ('ask') and noun ('Pipeworx'), then immediately clarifies the tool's domain: factual questions about real-world structured data. It explicitly distinguishes itself from siblings like 'ask_pipeworx_grounded' and 'deep_research', making its unique role unmistakable.

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

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

The description provides very clear when-to-use logic: 'PREFER OVER WEB SEARCH', lists trigger phrases ('what is', 'look up', etc.), and gives explicit step-up alternatives for more specialized needs. It also covers edge cases like breaking news and accounts that lack access to deeper tools.

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

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

The description goes far beyond the annotations, which only declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. It explains the experimental nature, that no candidate is currently active (last retired 2026-07-26), that it falls back to nothing (it is a full working router), and how results are compared against the stable router for merging decisions. This provides excellent behavioral context not available in annotations.

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

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

The description is well-structured and front-loaded with the key purpose and distinction. It is slightly verbose in the explanation of the experimental status, but every sentence adds value through behavioral context or usage guidance. Minor redundancy about 'same 5,564 tools' could be trimmed, but overall efficient.

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

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

Given the complexity of a universal router with 5,564 tools, the description adequately explains the experimental nature, current state, and how to use it. The schema is simple (single parameter with aliases) and there is no output schema. The description covers behavioral context well. A slight gap is not explaining what kind of outputs to expect, but the no-output-schema and open-world hint reduce the need.

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

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

Schema description coverage is 100%, with the schema already documenting the 'question' parameter and its five aliases. The description does not add any additional meaning about parameters beyond what the schema provides, so a 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 it is a 'universal router' that takes natural language questions and dispatches to one of 5,564 tools. It explicitly distinguishes itself from ask_pipeworx by explaining it is the beta version with candidate routing improvements, and from ask_pipeworx_grounded whose name suggests a different behavior. The verb and resource are specific and well-defined.

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 tells exactly when to use this tool: 'when you want the newest routing' and explains it currently matches ask_pipeworx exactly. It does not explicitly state when not to use it compared to ask_pipeworx_grounded or other siblings, but the context of being experimental and for testing routing improvements 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?

The description fully explains the behavioral guarantee: it returns an answer only if the tool result directly contains it, otherwise returns an explicit refusal with a specific reason. This adds significant value beyond the annotations, which already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description describes refusal reasons and success response structure, providing transparency about failure modes and the non-hallucination promise.

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 with useful information but a bit long. It front-loads the core purpose and mechanism, then adds guidelines and cost tradeoff. Every sentence adds value, though the details on refusal reasons and the exact response shape could be slightly more compact. Still, it strikes a good balance between completeness and brevity.

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 (5,564 tools across 1,462 sources, with a multi-step routing and extraction process) and the presence of rich annotations and no output schema, the description is thorough. It explains what the tool does, when to use it, what it returns on success and failure, and how it differs from its sibling. No output schema is needed because the description explicitly states the response shape.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no additional parameter meaning beyond the schema's aliases. The parameter 'question' is adequately described in the schema with multiple aliases; the description does not add constraints or formatting guidance.

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

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

The description clearly states the tool provides a hallucination-resistant answer mode for high-stakes reads. It explains the mechanism (uses ask_pipeworx routing, then extracts answer only from tool result) and gives concrete use cases (financial verdicts, legal claims, medical lookups, public statements). This definitively distinguishes it from its sibling ask_pipeworx.

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

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

The description explicitly tells when to use this tool (when answer will be quoted, cited, or acted on) and when not to (prefer ask_pipeworx for casual lookups). It also mentions the cost tradeoff (one extra LLM call), giving the agent clear decision criteria.

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

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

The description adds extensive behavioral context beyond annotations: details on response shapes, resolver contracts, parent_event extraction, news fallback mechanisms, safety short-circuits (low confidence, closed markets, wide spreads), and resolution-rule risk. Annotations already mark it as read-only, idempotent, and non-destructive, and the description aligns and enriches these traits.

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

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

The description is long but well-structured with UPPERCASE section headings and front-loaded purpose. Every section adds necessary detail for a complex tool. Could be slightly more concise, but the thoroughness justifies the length.

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

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

Given the tool's complexity (multiple data sources, classifiers, output fields, edge cases) and the absence of an output schema, the description is comprehensive. It covers input options, behavior under various conditions (low confidence, closed markets, wide spreads), and result fields, leaving no obvious gaps for an AI agent to misuse.

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 meaning beyond the input schema: for 'market' it explains acceptable formats (slug, URL, question text); for 'depth' it clarifies 'quick=2-3 sources, thorough=full fan-out'; for 'include_raw' it explains the default and sizing implications. Schema descriptions are minimal, so the main description provides essential 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 that the tool 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', clearly identifying the verb, resource, and action. It distinguishes itself from sibling tools like ask_pipeworx and polymarket_edges by focusing on single-bet research for Polymarket.

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

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

The description provides explicit usage examples ('Use for "should I bet on X"...') and classifier examples, giving clear context. It does not explicitly state when not to use or list alternatives, though the sibling context and specificity imply appropriate use cases.

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

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

Annotations declare read-only, idempotent, open-world. The description adds significant behavioral context: how off-calendar fiscal years are handled correctly for companies, sorting by primary metric, return of paired data and citation URIs, and efficiency (replaces 8-15 lookups). 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 example queries, then clearly states the core action, then details per type, sorting, return format, and efficiency. Every sentence is informative and earns its place. No fluff or repetition.

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

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

Given no output schema, the description adequately covers return format (paired data + citation URIs) and behavior. It could be more explicit about the exact fields returned for each type, but the efficiency claim and data source detail make it sufficiently complete for an agent to understand the tool's value.

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 value by explaining exactly what data each type pulls: for company, latest 10-K revenue/net income/cash/debt; for drug, FAERS counts/FDA approvals/trial counts. This enriches parameter meaning beyond the schema's basic description.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call, with specific examples of use cases like 'compare X and Y' and 'rank these companies'. It distinguishes from siblings like entity_profile by emphasizing comparison over sequential 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong guidance on when to use. It gives examples of queries that trigger this tool, but does not explicitly state when not to use, e.g., for a single entity profile. Still highly useful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (false), but the description goes well beyond them by detailing key behaviors: the tool returns verbatim evidence with confidence and citations, never invents findings (explicit in gaps[]), performs parallel decomposition, supports iterative gap recovery, and adds contradiction detection for standard/thorough. The description also explains time expectations and citation resolvability.

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

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

The description is detailed but overly long with compacted information, making it harder to parse quickly. While every sentence adds value, the density of acronyms (FRED, FDA, USPTO), nested details (citation URIs, hop fields), and multiple usage notes could be better structured for readability.

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 (2 parameters, no output schema, but rich annotations), the description comprehensively covers input semantics, behavioral expectations, limitations, timeouts, and integration with other tools. All facets of using this tool effectively are addressed.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the depth parameter's facets count and behavior (e.g., gap-recovery, contradictions), and clarifies that the question parameter supports broad/multi-part queries. However, it doesn't provide concrete examples or formatting hints.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources in one call, distinguishing it from open-web search and sibling tools like ask_pipeworx. It uses specific verbs ('routes', 'decomposes', 'returns') and defines the resource as a structured data catalog, 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 explicitly states when to use this tool (broad/multi-part questions over structured data) and when not to (for single lookups use ask_pipeworx, for breaking/current news use ask_pipeworx). It also provides alternatives and context about required accounts and paid plans, giving clear 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 indicate read-only, non-destructive, idempotent behavior. The description adds that results include full input schemas with curated examples and are ready to call directly, which is valuable context. It does not mention rate limits or authorization, but for a read-only discovery tool, this is acceptable.

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

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

The description is compact yet comprehensive: purpose, domains, return value, and usage guidance are all present. Every sentence adds value, and the information is front-loaded. No redundancy.

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

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

Given the absence of an output schema, the description adequately explains what is returned (top-N tools with names, descriptions, and full input schemas). Combined with annotations (read-only, safe), the description provides sufficient context 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%, so baseline is 3. The description adds examples of natural language queries and explains that the query parameter accepts several aliases, enhancing understanding beyond the schema. It also specifies default and max for limit.

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

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

The description starts with 'Find tools by describing the data or task,' clearly stating the verb (find) and resource (tools). It lists numerous specific domains (SEC filings, FDA drugs, etc.), making the scope precise. It distinguishes from siblings like search_papers or entity_profile since this tool is a meta-tool for discovery, not data retrieval.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use. It could improve by explicitly stating when not to use it (e.g., when you already know the tool), but the context implies that.

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

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

Description details the fan-out behavior across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and specific return fields. It also discloses the USPTO PatentsView API sunset (May 2025) with soft-fail behavior. This adds significant context beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), which only hint at safety and idempotency.

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 the core purpose, making it scannable. While it contains multiple sentences, each adds necessary detail. A slight deduction for verbosity; it could be trimmed slightly without losing 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 (aggregating from multiple sources) and no output schema, the description thoroughly covers all return elements (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and limitations (patents sunset, name resolution dependency). This ensures an agent understands the full scope.

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 baseline is 3. The description adds meaningful guidance: value parameter accepts ticker or zero-padded CIK, and names are not supported, which reinforces and extends schema descriptions. The type parameter is limited to 'company', also mentioned. This extra context justifies a 4.

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

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

The description uses specific verbs ('full cross-source profile of a US public company') and provides numerous example queries ('Tell me about X', 'research Acme'), clearly distinguishing this tool from siblings like 'resolve_entity' (which only resolves names to identifiers) and 'compare_entities' (comparison across entities).

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and includes a clear exclusion: 'Names not supported — use resolve_entity first if you only have a name.' This provides strong when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true, so description adds context about why to delete (stale context, sensitive data) beyond what annotations offer. No contradictions.

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

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

Two front-loaded sentences, no wasted words, every sentence adds value.

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

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

Given low complexity (1 param, no output schema, annotations present), description fully covers purpose, usage, and tool relationships. 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 has 100% coverage, so baseline is 3. Description only restates 'by key' without adding new detail about the parameter format or constraints.

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

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

Description clearly states 'Delete a previously stored memory by key' using a specific verb and resource. It distinguishes from siblings by mentioning 'Pair with remember and recall'.

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

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

Explicitly says when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also suggests pairing with siblings.

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

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

Annotations already provide safety signals (readOnly, idempotent, non-destructive). The description adds behavioral details: fetching the page, extracting title/description/links, and emitting standard markdown. It does not contradict annotations and adds context beyond them. However, it omits potential limitations like rate limits or page size 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 a single paragraph with a bullet-like use case list. It is fairly concise and front-loaded with the main action. Some redundancy exists, but it remains efficient overall.

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 adequately explains the return value (a text blob) and process. It covers the two parameters and use cases, but lacks details on error handling or edge cases. For a simple utility tool, this is sufficient.

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

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

Schema coverage is 100% with clear parameter descriptions. The description does not add new information about parameters beyond what the schema provides, meeting the baseline expectation.

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 primary action: generating a production-ready llms.txt file for any URL. It specifies the output format and includes concrete use cases, distinguishing it from sibling tools which do not mention llms.txt generation.

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

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

The description lists explicit use cases (e.g., getting a client's site indexed, drafting your own, auditing competitors) but does not provide when-not-to-use scenarios or alternative tools. This is a minor gap given the tool's unique function.

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 and idempotentHint; description adds useful detail on ID formats (version suffix, legacy) and returned metadata fields, enhancing transparency beyond annotations.

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

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

Two concise sentences front-loading key information (purpose, ID format, return fields) with 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 simplicity of the tool and presence of output schema, the description fully covers input, behavior, and return values with 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 description for arxiv_id; description adds examples and mentions legacy IDs, providing extra context for correct parameter usage.

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

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

The description uses specific verb 'fetch' and resource 'arXiv paper', and clearly distinguishes from sibling tools like search_papers by focusing on a single paper by 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?

Clearly states when to use (fetching a single paper by known ID). Does not explicitly exclude alternatives but context implies it is for cases where the ID is 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 (readOnlyHint, idempotentHint, destructiveHint) declare the tool safe and idempotent. The description adds behavioral details like default filtering to active subscriptions and the list of returned fields, which is valuable 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 three short, front-loaded sentences with no fluff. Each sentence serves a distinct purpose: purpose statement, return format, and usage example.

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 sufficiently covers the tool's behavior and return format given the simple input schema and lack of output schema. It could mention the optional parameter, but the schema already handles that. Overall complete for a list operation.

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 for the single optional parameter 'include_inactive' with a clear description. The tool description does not add extra meaning to this parameter, so it meets the baseline of 3.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies the returned fields, and distinguishes from siblings like subscribe and unsubscribe by mentioning use cases. The verb 'List' and resource 'subscriptions' are 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 directs the agent to use this tool for reviewing subscriptions before adding more (via subscribe) or finding an ID to cancel (via unsubscribe), providing clear when-to-use and 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?

Beyond the annotations (which are all false/neutral), the description discloses key behaviors: the claim_token follow-up mechanism, rate limiting ('Rate-limited to 5 per identifier per day'), cost implications ('Free; doesn't count against your tool-call quota'), and how the team processes feedback ('The team reads digests daily and signal directly affects roadmap'). This fully contextualizes the tool's operation.

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 lengthy but information-dense; every sentence serves a distinct purpose (purpose, usage, exclusions, workflow, rate limits, costs). It's front-loaded with the core action and then expands logically. No redundancy or filler.

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

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

Given a simple 4-parameter tool with no output schema, the description covers the full usage envelope: what to report, what not to report, how to follow up, and what to expect. It also explains the domain boundary (Pipeworx tools only), making it entirely self-contained for agents.

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

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

While the input schema already documents each parameter (100% coverage), the description adds practical semantics: it explains that 'message' should be specific about which tool/error/data, warns 'don't paste the end-user's prompt', and provides a concrete syntax example for using claim_token: 'pipeworx_feedback({claim_token:"pwfb_…"})'. This goes beyond schema descriptions.

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

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

The opening sentence clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the actions (report bugs, features, data gaps, praise), and implicitly distinguishes it from sibling tools by focusing on feedback rather than information retrieval.

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

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

The description explicitly lists when to use the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well'), and provides an explicit exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server in your client, file it with that server instead.' This is textbook 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, and destructiveHint. Description adds transparency about data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). No contradiction.

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

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

Description is concise and well-structured: first sentence defines output, then bullet-list of use cases, then technical details. Every sentence adds value; no wasted words.

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

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

Given one optional parameter with enum, no output schema, and annotations covering safety, the description is complete. It explains output content (top tools, packs, volume), caching, and privacy. No missing information.

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 a schema description and enum values. The description adds semantic meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's basic description.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over recent windows. It distinguishes itself from siblings like 'discover_tools' by focusing on trending AI agent calls. Three specific use cases further clarify 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 explicitly lists three use cases for when to use this tool, such as discovering hot data sources and confirming canonical tools. It does not explicitly state when not to use, but the sibling tool context provides 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral details: scanning top 200 markets, partition_check logic, semantic anchor with Jaccard similarity, partition filter for placeholders, and fill check against live CLOB depth. No contradictions.

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

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

The description is well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and is front-loaded with the core purpose. While verbose, every sentence adds necessary detail; minor trimming could improve conciseness.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities[], partition_check, suggested_trade, fill check details). It covers all modes, edge cases like placeholder slugs, and even references related tools for further actions.

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 basic descriptions. The description adds significant value by explaining the two modes in depth, providing example inputs, and detailing the functionality of each parameter (e.g., event slugs, full URLs, topic as seed question).

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

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

The description clearly states the tool finds arbitrage opportunities via 'monotonicity violations + partition-sum checks' on Polymarket. It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by specifying its unique approach and output.

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 event mode vs topic mode, including examples and recommendations. It also mentions when not to trade via the fill check and points to polymarket_fill_risk for custom sizing, though it does not contrast with all sibling tools.

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

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

The description provides extensive behavioral details beyond annotations: it explains caching (1h KV-level, keyed on knobs), response structure (by_segment, diagnostics), edge calculation with slippage and Kelly fractions, and the Fed note about unreliable signals. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and enriched.

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 detailed and informative, but it is quite long and dense, with technical sections that might overwhelm an agent. While well-structured with sections and lists, it could be more concise by front-loading the most critical information and trimming some implementation details.

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

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

Given the complexity (9 parameters, no output schema, but described response), the description thoroughly covers return structure, segments, diagnostics, and tradeable-edge knobs. It is sufficient for an agent to understand input/output and behavior, though the absence of an output schema means the description must carry the full burden.

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 extra meaning for several parameters (e.g., 'Edge is evaluated NET of slippage' for min_edge_pp, 'assumed execution slippage' for slippage_pp, 'applies to per-leg Kelly' for min_partition_leg_kelly), which goes beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is specific with verb 'scan' and resource 'Polymarket markets', and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx-based edge detection.

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 frames the tool for 'what should I bet on today' and notes it avoids paging hundreds of markets, giving clear usage context. It also explains tradeable-edge knobs and filters, but does not explicitly state when not to use it or alternative tools for specific scenarios.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds behavioral details: output structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day, lifespan_days), and limitations (60-day TTL, cache-miss gaps). 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 well-structured with a clear opening purpose, detailed response format, and limitations. It is slightly lengthy but front-loaded and every sentence adds value. Could be trimmed slightly but is effective.

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

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

Given no output schema, the description fully explains the output (tracked, expired, snapshot_dates with all fields) and limitations. Parameters are clarified. Completeness is high for a tool with 2 params and 100% schema coverage.

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. The description restates parameters with slight additions (max 30 for days, window options), but adds minimal new meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers how long has this edge existed and is it shrinking?' It uses specific verbs and resources, and distinguishes from sibling tools like polymarket_edges by focusing on historical persistence.

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 with an example ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying when to use the tool. However, it does not explicitly state when not to use it or mention alternatives. It gives good contextual guidance but lacks explicit exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral traits: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, etc.), and warns about risks (partial basket fills convert arb into directional). 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 well-structured with clear sections (SINGLE-MARKET, BASKET) and uses capitalization for emphasis. While slightly verbose, every sentence adds value. It is dense but not overly concise, earning a 4.

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

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

No output schema is provided, but the description compensates by listing all return fields for both modes and explaining the verdict logic. It covers complex scenarios (basket mode risks) but omits error cases or rate limits. Given the tool's complexity, it is quite 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 all parameters described. The description adds meaning beyond schema: explains default values, interprets size_usd differently for single vs basket, and side default logic for basket. This significantly aids correct tool 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 explicitly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and relates to sibling tools polymarket_arbitrage and polymarket_edges, making it clear and specific.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged directional), offering clear when-to-use and alternatives.

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

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

The description adds substantial behavioral context beyond annotations (readOnlyHint, idempotentHint). It explains safety fields like compatibility_warning (with two specific cases), temporal_alignment, and skipped counters that expose why spreads may be invalid. It also details the two operational modes and the response structure, ensuring the agent understands the tool's behavior 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 front-loaded with the core purpose and structured into clear sections (modes, response, safety fields). While somewhat verbose with details like '2-25pp apart' and extended safety explanations, every sentence adds value. It could be more concise, but the structure aids readability.

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 (cross-venue spread with safety checks) and the absence of an output schema, the description covers modes, response fields (leg-by-leg prices, spread array), and safety warnings. It lacks explicit JSON structure for the response but provides sufficient detail for an agent to interpret results. Completeness is strong but not perfect.

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 meaningful context beyond schema: it explains the two modes (topic vs explicit tickers), provides example values for topic, and clarifies that explicit parameters override topic-mapped sides. This enhances semantics, warranting a 4.

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

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

The description explicitly states the tool's purpose: cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison, and details two modes (topic shortcuts and explicit event tickers) with specific examples.

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

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

The description provides clear guidance on when to use the tool (to compare spreads across venues) and when not to (when compatibility_warning or temporal_alignment:false indicate no arbitrage opportunity). It explicitly warns that pre-mapped topics often yield compatibility_warning and are not always tradeable, offering concrete signals to avoid misuse.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds additional behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' This informs the agent about data isolation 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 serving a purpose: purpose, usage example, scoping, and tool pairing. No fluff, front-loaded with the most important information.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers retrieval behavior, listing mode, scoping, and relationships to sibling tools. It is fully sufficient for an agent to understand and use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining the effect of omitting the key: 'or list all saved keys (omit the key argument).' This clarifies a dual-mode behavior not fully captured by the schema alone.

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

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

Description starts with clear verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes from sibling tools 'remember' and 'forget' by naming them and stating the retrieval 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?

Description explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions pairing with remember and forget, providing clear usage context, though no explicit 'when not to use' is stated.

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 a behavioral trait (mark_read:true modifies state by marking events read) that contradicts the readOnlyHint annotation, which claims no side effects. Per scoring rules, a contradiction results in a score of 1.

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

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

Four sentences with no filler. The purpose is stated first, followed by return fields, usage examples, and alternative access. Each sentence earns its place, and the structure is front-loaded.

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 fields, parameter behaviors, and side effects. It is complete for the tool's complexity, especially given rich annotations and schema descriptions.

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% already, but the description adds context beyond schema descriptions. For example, it explains that mark_read:true causes the next call to show only newer events, and it clarifies the return structure (source, citation_uri, payload). This adds meaningful semantic value.

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

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

Description begins with 'Pull fired events from your subscription feed', a specific verb+resource pair that clearly states the tool's core function. It distinguishes from siblings like ask_pipeworx and search_within by focusing on subscription alerts, and no other sibling tool is dedicated to this feed.

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 provides explicit filtering guidance (by type, since) and explains the mark_read parameter's effect. It also notes that polling works fine and offers an alternative access method (GET alerts.json). However, it does not explicitly state when not to use this tool versus 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: SEC EDGAR filings since `since`, GDELT→GNews fallback, USPTO patents granted with API sunset note, and return structure (changes[] grouped by source + total_changes + pipeworx:// URIs). No contradiction with annotations.

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

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

The description is dense but well-structured. It front-loads example queries, then explains sources, parameter details, and sibling reference. Every sentence adds value, though it's quite long. Could be slightly more concise, but it's clear and informative.

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 of the tool (multiple sources, fallback logic, pending API sunset), the description is remarkably complete. It covers input parameters, source behavior, return structure, and alternatives. No output schema, but the description adequately describes the return format. Annotations complement the description well.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds significant meaning beyond schema: explains that `since` accepts relative shorthand ('7d', '30d', '3m', '1y') and suggests '30d' for typical monitoring; clarifies that `value` accepts ticker or CIK; and reiterates that `type` only supports 'company'.

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

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

The description clearly states the tool provides a change feed for a company over a recent time window, aggregating from multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It gives example queries like 'What's new with X' and distinguishes from the sibling 'entity_profile' by explicitly stating when to use that instead.

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

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

The description provides explicit usage guidance: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior (GDELT→GNews when rate-limited or 5xx) and limitations (USPTO soft-fail until reactivated). This helps the agent decide when to use this tool versus 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 (idempotentHint=true, destructiveHint=false) are well-supported. Description adds key details: scoping by identifier, persistence differences (authenticated vs anonymous), and lifetime (24h). No contradictions.

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

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

Three sentences: purpose, usage, behavior. Front-loaded, zero waste, every sentence earns its place.

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

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

For a 2-param tool with no output schema, the description fully explains what, when, and how. Includes pairing with recall/forget and persistence behavior. 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 key and value. Description adds value by explaining typical usage (pairing, examples) and scope, going beyond bare 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 saves data for reuse across conversations/sessions, gives concrete examples (resolved ticker, target address, user preference), and distinguishes from siblings 'recall' and 'forget'.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and pairs with recall/forget. It lacks explicit when-not-to-use, but the guidance is sufficient for most scenarios.

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

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

The description discloses many behaviors beyond the annotations: it cascades through multiple lookup endpoints, degrades gracefully (EDGAR identifiers still return if GLEIF/OpenFIGI unavailable), and explains the output format (identifiers labelled with source, unresolved listed explicitly). The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and the description adds rich operational context about how lookup failures are handled. 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 (several sentences) and somewhat dense. It starts with multiple example queries, then a purpose statement, then a detailed paragraph about supported types. Some information is repeated (e.g., example queries are functionally redundant with the later explanation). While informative, it could be tightened to reduce cognitive load without losing key points.

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

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

Given the tool's complexity (two entity types, multi-source lookups, cascading, graceful degradation) and the absence of an output schema, the description is remarkably complete. It explains what each entity type returns, how unresolved identifiers are handled, how degradation works, and even how the tool replaces multiple manual steps. The agent can accurately predict behavior and output structure from this description alone.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant meaning beyond the schema: it explains that for company type, input can be ticker, CIK, ISIN, or name, and that ISIN resolves to legal entity via GLEIF. It also gives example values (e.g., 'ozempic', 'metformin'). This extra detail helps the agent understand valid inputs beyond the schema's generic 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 starts with concrete example queries like 'What's the ticker for…' / 'find the CIK for…' that immediately convey the tool's core function. It states explicitly: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This verb+resource pairing is specific and distinguishes the tool from siblings like entity_profile (which needs an ID) or compare_entities. The list of supported entity types (company, drug) further clarifies 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing a clear when-to-use rule. It also mentions that the tool replaces 2-3 manual lookups, giving context on efficiency. However, it does not directly state when not to use this tool (e.g., if you already have an ID, use entity_profile instead). The guidance is strong but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so safety is clear. Description adds that it probes entities, ranks, and returns score/confidence/signal density. It also mentions API key requirement for Anthropic. No contradiction. Could mention rate limiting or failure behavior.

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

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

Two clear, front-loaded sentences that directly state purpose, method, and return. No wasted words.

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

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

Given the tool's complexity (multiple entities, models, context, no output schema), the description covers what it does, how it works, and what it returns (ranked list with metrics). It is complete enough for agents to use effectively.

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

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

Schema coverage is 100%, and the description adds significant meaning: 'entities' first is the subject, 'models' supported, 'context' disambiguates common names. This goes beyond the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It provides a concrete example ('does Claude know about us as well as our competitors?'), which distinguishes it from sibling tools like ai_visibility_check (single probe) and compare_entities (general comparison).

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 it is useful for competitive AI-marketing audits and gives an example. It does not explicitly state when not to use or list alternatives, but the context implies comparison. A more direct comparison with ai_visibility_check would improve clarity.

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

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

Annotations already provide safety hints (readOnlyHint, idempotentHint). Description adds behavioral details: fan-out across two services, bundlephobia first measurement can take 5-30s, degraded partial failure reporting with sources_failed field. No contradictions.

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

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

Description is relatively long but well-structured with front-loaded purpose. Every sentence adds value, though it could be slightly more concise. A single paragraph with clear logical flow.

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

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

Despite no output schema, the description fully explains return structure (summary block, details, links, alternatives) and behavior on partial failure. Comprehensive for a composite tool.

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

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

Schema coverage is 100% with good descriptions. Description adds minor context (scoped packages accepted, default version is latest) but doesn't add significant meaning beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool is a composite check for evaluating npm packages, covering license, advisories, bundle size, etc. It uses strong verbs (fans out, check) and distinguishes from sibling tools like deps.dev:version.

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

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

Explicitly says when to use (e.g., 'is X safe / popular / small') and when not (other ecosystems should use deps.dev:version directly). Also mentions partial failures and timing expectations.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by detailing query syntax, return fields, and boolean operators, going beyond the annotations' safety profile.

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 three sentences with no wasted words. It starts with the overall purpose, then details query syntax, and finally lists return fields, making it efficient and easy to scan.

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

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

Given the output schema exists, the description adequately covers query syntax, return fields, and basic usage. It is missing details on pagination or rate limits, but overall it provides sufficient context for a search tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds practical examples, demonstrates field prefixes, and explains boolean combinations, which enhances usability beyond the schema alone.

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

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

The description clearly states the tool searches arXiv preprints, specifies plain text and field-prefixed query options, and lists return fields. It effectively distinguishes from siblings like get_paper (retrieval by ID) and deep_research (more complex).

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 query syntax and examples but does not explicitly state when to use this tool versus alternatives like get_paper or deep_research. Usage context is implied but not contrasted, so the agent lacks clear guidance on exclusion.

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

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

Discloses embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character cap (200K with truncation flagging), and output details (offsets, scores). Annotations provide idempotent and read-only hints, 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?

Concise yet comprehensive: 5 sentences covering purpose, usage, pairing, technical details, and constraints. No wasted words, 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?

Given no output schema, the description fully explains return format (passages, offsets, scores) and covers all parameter behaviors, technical limits, and integration hints.

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

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

Schema coverage is 100%, but description adds value by giving examples for query and explaining that text is the document to search. It clarifies the limit parameter's default and range.

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 semantic search inside a fetched record, returning top-N passages with character offsets and similarity scores. It distinguishes itself by mentioning pairing with ask_pipeworx_grounded and specifying use cases like SEC 10-K bodies or articles.

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

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

Explicitly advises use when records are too large for prompts, and pairs with ask_pipeworx_grounded. While it doesn't list explicit alternatives, the guidance is clear and context-rich.

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 behavioral traits beyond annotations, such as the need for OAuth, SMS cap, one-time webhook secret, and auto-disable after failures. Annotations indicate creation with idempotency, which aligns with the description.

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

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

The description is well-structured and front-loaded with the main purpose. It is concise but includes necessary details without being verbose.

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

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

The description is complete for a tool with no output schema, covering return value, parameter details, constraints, and delivery options. It addresses complexity effectively.

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

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

Schema coverage is 100%, so the description adds moderate value by providing type-specific examples and additional delivery details. The schema already adequately documents parameters.

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

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

The description clearly states the tool creates a subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like 'unsubscribe' and 'list_subscriptions' by specifying proactive monitoring.

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

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

The description provides clear usage context, including account requirements (Pipeworx OAuth), supported types, and delivery channels. However, it does not explicitly state when not to use this tool compared to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by describing the output format (example questions with tool shapes), but does not reveal additional 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?

The description is relatively long but well-structured with alternative phrasings, usage examples, and a clear purpose. It could be slightly more concise, but every sentence adds value.

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

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

Given the tool's role as an onboarding entry point and the presence of comprehensive annotations, the description provides sufficient detail about return format, categories, and how to use meta-tools, making it complete for its purpose.

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

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

Schema covers the single `topic` parameter with description. The description adds example values ('finance', 'pharma', 'betting') and explains how the parameter changes behavior, adding meaning 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 it is an onboarding entry point that returns category-bucketed example questions with tool call shapes, distinguishing it from siblings like discover_tools by emphasizing first-use context.

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

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

Explicitly says 'Call with no arguments for the full spread, or pass `topic` to focus,' and 'Use this FIRST when you do not yet know what Pipeworx can do,' giving clear when-to-use and how-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?

The description adds behavioral context beyond annotations: it confirms the tool modifies data (cancel), enforces ownership, and deactivates rather than deletes. Annotations already provide readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description aligns with these without contradiction.

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

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

The description is two sentences, concise and front-loaded. First sentence states the primary action, second adds key behavioral details. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership constraint, and effect on data (deactivation). It could mention return values or error conditions, but overall it is complete enough for the tool's complexity.

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

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

Schema coverage is 100% for the single parameter 'id', with a clear description. The tool's description mentions 'by id' but does not add new semantics beyond what the schema provides. Baseline score of 3 is appropriate since the schema already does the job.

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 'Cancel' and the resource 'subscription by id'. It distinguishes from sibling tools like subscribe and list_subscriptions, and mentions that historical events remain via recent_alerts.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which is a clear usage guideline. It also notes that the row is deactivated not deleted, informing about side effects. However, it does not explicitly mention when not to use this tool or list alternatives.

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

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

Annotations declare readOnly/openWorld/idempotent, but the description adds critical semantics: the dual pipeline (SEC EDGAR for financial claims vs grounded fallback), the meaning of could_not_verify (check did NOT happen, carries verification_error, must not be used as evidence) and unsupported (no source found). This is exactly the kind of behavioral context that prevents misuse.

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

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

The description is long but densely informative; every sentence earns its place. It front-loads trigger phrases, states usage, explains behavior, then lists return values and critical caller caveats. No fluff.

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

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

For a 2-param tool with no output schema, the description gives the full return contract: verdict enum, actual value with citation, reasoning, and error semantics. It also covers edge cases (could_not_verify, unsupported) and the two execution paths, making it self-sufficient.

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

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

Schema already covers both parameters at 100%. The description adds value by explaining tolerance_pct overrides implied tolerance, caps at 5, and recommends 1–2 for hallucination detection, plus claim examples that match schema examples.

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

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

Description opens with natural-language triggers ('Is it true that…', 'fact check') and defines the tool as 'natural-language claim verification against authoritative sources.' The verb+resource (verify claims) is specific and clearly distinguishes from sibling research tools like ask_pipeworx_grounded or deep_research, which don't produce verdicts.

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 explicitly: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the tool replaces 4–6 sequential calls, implying it is the single-call path for fact verification. It doesn't name exclusions or alternatives, so not a 5.

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