Nihr

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that the default model is free (Workers AI) and that Anthropic requires a BYO key with direct billing, plus return structure. No contradictions.

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

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

The description is a single paragraph with no wasted words. It front-loads the main action and key details, earning every sentence.

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 details the per-model return fields {score, confidence, signals, raw_response} and a combined view. It covers usage scenarios, parameters, and cost implications—complete for a probe 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 descriptions for all 4 parameters. The description adds context: default model, how _apiKey works, and purpose of context parameter, going beyond the schema.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it 0-100. It specifies the verb 'probe', resource 'LLMs', and output 'score visibility', distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly state when not to use it or compare to siblings, but the use cases are clear.

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

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

Annotations already mark it as read-only and idempotent. Description adds context: returns structured answers with pipeworx:// citation URIs, routes appropriately, covers numerous domains. No contradiction with annotations. Could mention rate limits or authentication, but sufficient given annotations.

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

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

Description is longer but front-loaded with key instruction 'PREFER OVER WEB SEARCH'. Uses clear structure with examples and alternatives. Every sentence adds value; could be slightly more concise but remains 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?

Despite 6 parameters (only one meaningful) and no output schema, the description thoroughly explains behavior, use cases, alternatives, and return format (structured answer with citations). Fits the complexity and richness of the tool.

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

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

Schema description coverage is 100% as all parameters are aliases for 'question' with descriptions. Description adds example questions but does not provide new semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool routes questions to 5,269 tools across 1,374 sources and returns structured answers with citations. It uses specific verbs and resources ('ask', 'Pipeworx'), distinguishes from siblings by naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for factual questions and lists domains. Provides step-up guidance: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for multi-part queries. Includes examples and advises starting here for most questions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that candidate routing improvements may be active, currently none are active making it identical, and it explicitly states 'Falls back to nothing — this IS a full working router', providing useful behavioral context beyond annotations.

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

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

The description is two sentences with no wasted words. Each sentence adds value: first explains identity and purpose, second details current state and usage guidance.

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

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

Given the tool's complexity as a beta router with many underlying tools, the description adequately explains its relationship to the stable version, the candidate testing framework, and its current identical state. It lacks details about return format or outcome evidence, but is sufficient for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description does not add additional meaning or context for any parameter; it only mentions 'same arguments' without elaboration.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tool set and arguments. It distinguishes from siblings by specifying it's the experimental edge for routing improvements.

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

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

It instructs to use exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. However, it does not provide explicit when-not-to-use scenarios or alternatives beyond stating the current identical state.

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

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

Beyond annotations (readOnly, idempotent), the description details the return structure including evidence, confidence, refusal_reason values, and the extra LLM call cost. It fully discloses behavior without contradictions.

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

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

The description is front-loaded with the key concept and is dense with information. Every sentence adds value, though slightly longer than minimal. Still well-structured and efficient.

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

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

Despite no output schema, the description thoroughly explains the return object fields and refusal reasons. Given the tool's complexity and numerous siblings, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100% with each parameter described. The description adds a sentence listing aliases but does not provide deeper semantic meaning beyond what the schema already offers. 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 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers exclusively from tool results. It distinguishes itself from sibling ask_pipeworx by noting the same routing but grounded extraction, 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?

Explicitly tells when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with example domains. Also advises preferring ask_pipeworx for casual lookups due to extra cost, providing clear selection criteria.

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

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

Extremely detailed behavioral description: explains market resolution, classification, parallel fan-out, response shape with evidence packet and model comparison, resolver contract, parent event extraction, news fallback fields, safety mechanisms (low-confidence closure, closed market, wide spread handling), cancellation rule parsing. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent and enriched by description. 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 lengthy but well-structured: starts with a concise summary, then partitions into classifiers, fan-out examples, response shapes, resolver contract, parent event extraction, news fields, safety, and cancellation rules. Every section adds necessary detail for a complex tool. However, some sections are very verbose (e.g., cancellation rule parsing details). Could be slightly more concise, but structure earns 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?

Given the tool's complexity (multiple data sources, edge cases, response shapes), the description is extremely complete. It covers all scenarios: low-confidence matches, closed markets, wide spreads, cancellation rules, parent events, news fallbacks. No output schema, so the description thoroughly explains return structure (result.market, result.analysis, result.evidence). No missing information for effective use.

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

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

Schema coverage is 100% (all 3 parameters described). Description adds value: for 'market', it clarifies acceptable formats (slug, URL, question text). For 'depth', it explains the difference ('quick = 2-3 evidence sources, thorough = full fan-out'). For 'include_raw', it describes when to use true (recomputation, citation, post-processing) and the size implications. Provides examples in schema and description.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet via Pipeworx data) and the action (research). Distinguishes from sibling tools by focusing on in-depth data retrieval and analysis, not just edges or arbitrage. Provides concrete usage 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?

Explicitly states when to use: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' Does not explicitly state when not to use or mention alternatives, but the context from sibling tool names and the detailed fan-out examples imply this is for comprehensive research. Clear context but lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavioral details: it pulls latest 10-K revenue/net income/cash/debt for companies (with fiscal year handling), FAERS adverse-event counts and FDA approval counts for drugs, and sorts results by primary metric. No contradictions with annotations.

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

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

The description is a single paragraph but packs significant information with minimal redundancy. It uses trigger phrases and dashes to structure ideas. Could be slightly more structured (e.g., bullet points) for easier parsing, but overall it is concise and front-loads the core purpose.

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

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

Given the simple schema (2 parameters, no output schema) and rich annotations, the description covers all necessary context: what data is returned per type, how results are sorted, and the efficiency gain over sequential lookups. It is complete for an AI agent to understand when and how to use the tool.

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

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

Schema coverage is 100%, but the description enriches both parameters: it explains the enum values for 'type' (what each pulls), clarifies that 'values' should be tickers/CIKs for company and drug names for drug, and reinforces the min/max constraints. This goes beyond the schema's descriptions.

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

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

The description uses specific verbs ('compare', 'side-by-side comparison') and clearly identifies the resource (2–5 companies or drugs) and the action (comparison of financial or trial data). It distinguishes itself from sibling tools like entity_profile by explicitly stating it replaces sequential single-entity lookups and by listing trigger phrases.

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 ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides clear context for each type (company vs drug), including the data sources and metrics pulled. It also specifies the range of entities (2–5) and gives example inputs.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds extensive behavioral details: account requirement, tier differences, parallel decomposition, gap recovery, contradictions, hop fields, citation URIs, semantic excerpting, time expectations. 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?

Long but well-structured and front-loaded with critical prerequisite and usage guidance. Every sentence adds value, though could be slightly more concise. Minor deduction for 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?

No output schema, but description thoroughly explains return format (findings packet with evidence, confidence, source, citation, gaps, contradictions). Covers all necessary operational details: account, depth, decomposition, behavior, time expectations. Very complete.

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

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

Schema has 100% coverage with descriptions. Description adds meaningful context about depth levels (how many facets, behavior differences) and reiterates that question can be broad. Enhances schema but schema already good.

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

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

Clearly states it performs grounded multi-source research across 1374 structured data sources. Distinguishes itself from sibling tools like ask_pipeworx, which is for single lookups or breaking news. Specific verb 'research' and explicit scope.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not to (single lookups, breaking news, current events). Names alternative (ask_pipeworx) and explains why it's better for other 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 already declare readOnlyHint=true and destructiveHint=false. The description adds that results include full schemas with examples, are ready to call, and no second lookup is needed—useful behavioral context beyond annotations. Slight missed opportunity to mention result ranking or pagination.

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

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

The description is information-dense but not excessively long. It front-loads the purpose, enumerates example domains, and ends with usage guidance. The domain list could be slightly trimmed but is helpful for illustration.

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 the return value: tool names, descriptions, full schemas with examples, ready to call. It also addresses the pain point of 'no second schema lookup,' making it complete for an agent.

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

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

Schema coverage is 100% with detailed descriptions for all 6 parameters. The description adds little beyond restating that 'query' accepts natural language. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool finds tools by describing data or tasks, listing many domains. It distinguishes itself from siblings by advising 'Call this FIRST' when exploring available tools, making its role as a meta-tool explicit.

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

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

Provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST... when you want to see the option set (not just one answer).' This effectively tells the agent when to use it versus other tools.

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

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

Annotations already mark as read-only and idempotent. Description adds behavioral details: fans out across multiple sources, returns specific fields, notes patent API sunset with soft-fail, and mentions parallel execution. 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 substantial but every sentence is informative. Front-loaded with examples and usage guidance. Minor improvements could make it more concise without losing content.

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

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

Without output schema, the description fully details return fields (cik, filings, fundamentals, patents, news, LEI) and limitations (patent sunset, name restriction). Complete enough for an agent to understand what the tool returns.

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

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

Schema coverage is 100%. Description adds examples and clarifies that names are not supported, reinforcing the schema. Slightly redundant but helpful.

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

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

The description opens with specific query examples and clearly states 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools like 'resolve_entity' and 'compare_entities' by indicating it provides a holistic view.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and advises using 'resolve_entity' first if only have a name. Provides clear context on when and when not to use.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context that this is about 'sensitive data the agent saved earlier' and clarifies the action as deletion, which aligns with destructiveHint. It does not contradict annotations. The description enriches behavioral context by explaining the motivation (clearing stale context or sensitive data), which goes beyond what annotations alone 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?

Two concise sentences front-load the purpose and then provide usage guidelines. Every word adds value; there is no redundancy or filler. Extremely well-structured for an AI agent to parse quickly.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description covers all necessary aspects: what it does, when to use it, and how it relates to siblings. No additional context is needed for correct invocation.

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

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

Input schema coverage is 100%, with the 'key' parameter fully described ('Memory key to delete'). The description adds no additional information about the parameter beyond what is in the schema. Baseline is 3, and no extra value is provided.

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

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

The description clearly states the action ('Delete a previously stored memory by key'). The verb 'Delete' is specific and directly indicates the resource being acted upon ('memory'). It also implicitly distinguishes itself from sibling tools like 'remember' and 'recall' by mentioning them in a pairing context.

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

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

The description provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', offering guidance on complementary tools. However, it does not explicitly exclude situations where this tool should not be used or suggest direct alternatives beyond the paired tools, which would make it 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 indicate readOnly, idempotent, and non-destructive. The description adds that it fetches the page, extracts title/description/key links, and returns markdown text. This aligns with annotations and provides behavioral context, though it could mention that no modifications are made to the site.

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

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

The description is concise: two sentences plus a brief list of use cases. It is front-loaded with the core action and every part adds value, with no redundant or superfluous content.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description adequately covers functionality, output format, and use cases. It does not cover error handling or limitations (e.g., invalid URLs), but for a straightforward 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 description coverage is 100%, so the schema already documents both parameters well. The description reinforces the meaning of 'url' (site to summarize) and 'max_links' (controls number of link entries) but does not add significant new information beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (fetch, extract, emit) and the output format. It distinguishes itself from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' by focusing on 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 explicitly lists use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor AI visibility. It provides clear context but does not mention when not to use this tool or prerequisites like URL accessibility.

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 return field list and confirms active subscriptions, providing useful behavioral context beyond annotations.

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

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

Two sentences: first covers purpose and output, second gives usage guidance. No extraneous information, 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 simple list tool with rich annotations and one optional parameter, the description sufficiently covers purpose, output, and usage. No gaps for correct agent invocation.

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

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

Schema coverage is 100% with one parameter fully described. Description does not mention the parameter, but schema carries the burden. Baseline score of 3 is appropriate.

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

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

Description clearly states verb 'list', resource 'subscriptions', and scope 'caller's active'. It also lists returned fields, making purpose unambiguous. Siblings include subscribe/unsubscribe, so it effectively distinguishes.

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

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

Explicitly says to use for reviewing monitoring before adding more or to find an id to cancel. Provides clear usage context, though it does not explicitly mention when not to use.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds that results include ORCID, role, and project IDs, the record count (12,644), and the ability to pivot to another tool. No contradictions.

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

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

Two sentences: first states core purpose, second explains output and use cases. No filler, front-loaded with essential information.

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

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

No output schema, but the description details the return structure (ORCID, role, project IDs). It covers all key aspects for a search tool with optional parameters, making it complete for an agent.

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

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

Schema covers all 6 parameters with descriptions (100%). The description reinforces the role of name, orcid, and involvement_type by mentioning roles and the pivot use case, adding value beyond the schema.

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

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

The description clearly states the action (Find) and the resource (researchers named on UK NIHR awards) and specifies search by personal name or ORCID identifier. It distinguishes from sibling tools like nihr_get_award and nihr_search_awards by focusing on award holders.

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 three explicit questions the tool answers and mentions pivoting to nihr_get_award for grant detail. It does not explicitly contrast with siblings like nihr_awards_by_organisation, but the given use cases are clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety profile is clear. The description adds beyond that: it explains that totals cover all matches regardless of pagination, the return includes programme breakdown and individual awards, and the matching is case-insensitive substring. No contradictions.

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

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

The description is four sentences long, front-loaded with the main purpose in the first sentence. Every sentence adds unique information with no redundancy or fluff. Efficient and well-structured.

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

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

For a tool with 6 parameters, 1 required, and no output schema, the description thoroughly explains the return structure (count, sum, variants, programme breakdown, individual awards) and clarifies scope (totals cover all matches). It covers common use cases and edge cases (e.g., limit on listed awards only). 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 detailed descriptions for all 6 parameters. The description adds context: explains the matching behavior (case-insensitive substring of contracted_organisation) and clarifies that the limit parameter only affects listed awards, not the totals. This adds value beyond what the schema provides.

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

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

The description uses specific verbs ('total up', 'get back') and explicitly names the resource (UK NIHR health research funding by institution). It lists return fields (number of awards, summed value, organisation variants, programme breakdown, individual awards) and provides example queries, clearly distinguishing from sibling tools like nihr_awards_by_programme.

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 clear context: provide any part of the institution name. It provides concrete examples ('Imperial', 'University of Leeds') and states the tool answers league-table comparisons. However, it does not explicitly state when NOT to use it or mention alternatives, missing some guidance for distinguishing from closely related tools.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds specifics: it aggregates by programme, returns counts/total value/mean size/date range, and lists all programmes when called without arguments. No contradictions.

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

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

The description is two tight sentences plus example questions, front-loading the core action and purpose. Every sentence is informative; 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?

No output schema exists, but the description covers key return fields: award counts, total value, mean size, date range. It also describes default behavior. While exact JSON structure is missing, the summary is adequate for an AI to understand outputs.

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 the default behavior (no args lists all programmes) and providing an example call. It also clarifies the meaning of group_by options (e.g., 'funding_stream' is finer-grained).

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: breaking down UK NIHR funding by programme or funding stream, with award counts, total value, mean size, and date range. It distinguishes itself from siblings like nihr_search_awards and nihr_awards_by_organisation by focusing on aggregation.

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

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

The description explicitly advises calling with no arguments to discover valid programme names before filtering, and provides concrete example questions (e.g., 'which NIHR programme spends the most'). It implicitly excludes use cases for individual award details.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it handles two forms of project IDs and returns a comprehensive list of fields, providing useful behavioral context beyond annotations.

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

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

The description is a single paragraph that starts with the purpose and lists key outputs. It is well-organized and concise, though it could be slightly shorter.

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 good annotations, the description covers the return values comprehensively. It lacks details on errors, but overall it 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% and the schema's description of project_id is detailed. The description repeats the two forms but does not add significant new meaning beyond the schema.

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

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

The description specifies the verb 'retrieve' and the resource 'UK NIHR award in full', and distinguishes from sibling tools by listing detailed fields returned. It clearly identifies what the tool does.

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 it: when an agent has an NIHR project reference and needs detail. It does not mention when not to use it, but the context is clear.

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

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

Annotations already indicate the tool is read-only and idempotent. The description adds useful behavioral context: it lists what data is returned (project id, title, programme, etc.), mentions filtering by program/status/amount, and sorting options. No destructive behavior is implied, consistent with annotations. No contradiction.

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

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

The description is compact at 5-6 lines, front-loaded with the core purpose. Every sentence serves a clear function: stating the action and outputs, listing filters/sorting, and providing concrete usage examples. No fluff or redundancy.

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

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

Given the complexity (13 params, no output schema), the description is reasonably complete. It covers the main functionality, returned fields, filtering options, and example queries. It does not mention pagination parameters (offset/limit) but the schema already describes those. Without an output schema, the description adequately describes the return fields. Minor gap: it could explicitly state that results are a list, but the examples imply that.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description summarizes the key filtering and sorting capabilities in a high-level way, but does not add significant new semantic meaning beyond the schema's detailed descriptions. It includes an example with parameters, which helps, but does not elevate the score above the baseline.

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

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

The description clearly states the tool searches NIHR grants by keyword over titles and abstracts, and lists returned fields. It provides concrete examples of questions it can answer. However, it does not explicitly distinguish this tool from sibling tools like nihr_awards_by_programme, which slightly reduces clarity for an agent deciding between tools.

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

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

The description implies usage scenarios through example questions, but it does not explicitly state when to use this tool versus alternatives (e.g., nihr_awards_by_programme for list all awards in a programme). There are no 'when not to use' statements or comparisons to siblings, leaving the agent to infer usage context.

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

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

Annotations indicate it's not read-only, not idempotent, and not destructive, but the description adds key behavioral details: rate-limited to 5 per identifier per day, free, and does not count against quota. 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 concise at 6 sentences, front-loads the main action, and efficiently covers usage, constraints, and best practices. Every sentence adds meaningful guidance without redundancy.

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

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

Given the tool's simple purpose (sending feedback) and the absence of an output schema, the description fully covers what the agent needs: when to use, required and optional parameters, rate limits, and formatting tips. It is complete for effective invocation.

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

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

Input schema has 100% description coverage, providing clear definitions for each parameter. The description reinforces this with examples and adds an important semantic constraint: 'don't paste the end-user's prompt' and to describe issues in terms of tools/packs. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: to send feedback about bugs, feature requests, data gaps, or praise. It specifies the exact use cases and distinguishes it from sibling tools (none of which are for feedback), making the tool's role unique 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 provides explicit when-to-use guidance: for wrong/stale data (bug), missing tools (feature/data_gap), or positive experiences (praise). It also notes rate limits (5 per identifier per day) and that the tool is free, aiding the agent in deciding usage.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable context: 'Self-aggregating signal from CF analytics-engine, no PII, cached 5min-1h depending on window.'

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 well-structured sentences: output, use cases, caveats. No wasted words; front-loaded with 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?

For a single-parameter, no-output-schema tool with robust annotations, the description fully covers purpose, usage, behavior, and caching. Nothing missing.

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

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

Schema covers 100% with enum and description. Description adds semantic nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' 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 title 'Pipeworx Trending' and description clearly state it returns top tools, packs, and call volume over recent windows. It distinguishes from siblings like 'discover_tools' by focusing on aggregate usage trends.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case with demand). While it doesn't mention when not to use, sibling names provide context.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: describes the response structure (opportunities[], partition_check), explains fill check logic (theoretical vs realizable edge), and warns against trading when realizable_edge_pp <= 0. 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 somewhat lengthy but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loads main purpose and usage modes. Some details like 'skipped_low_similarity surfaces the rejected pair count' could be moved to parameter descriptions, but overall not wasteful. Scores 3 for moderate conciseness.

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

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

Given the tool has 2 optional parameters, no output schema, and high complexity, the description covers purpose, usage modes, behavioral nuances, and response structure comprehensively. Includes important constraints like Jaccard similarity threshold and placeholder filter. Adequate for an AI agent to correctly select and invoke the tool.

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

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

Schema has 100% coverage with descriptions for both event and topic. The description adds value beyond schema by explaining the semantic difference, giving example inputs, and describing behavioral differences between modes (e.g., cross-event catches date-axis patterns single-event misses). Schema already adequate, so baseline 3; description adds enough extra context to warrant 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?

Clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' Distinguishes from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by specifying unique methodology.

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 describes three usage modes: no args for trending_scan, event for single-event partition checks, topic for cross-event scanning. Provides specific guidance on when to use each, e.g., 'event (recommended for a specific market)' and explains cross-event mode catches patterns single-event misses. Also advises using polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses behavioral traits beyond annotations, including caching (1h KV-level), return fields (edge_pp_net, kelly fractions, liquidity, spread, volume, 24h-move warning), model families, and diagnostics. Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds rich context about internal calculations and filtering logic.

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

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

The description is comprehensive but verbose, with complex sentences and detailed enumerations. While it is well-organized into sections (model families, knobs, response structure), it could be trimmed without losing essential information, scoring it as adequately structured but not optimally concise for its length.

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

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

Despite the absence of an output schema, the description explains the complete response structure (by_segment segments, fed_candidates/diagnostics) and the meaning of each returned field. The tool is complex with three segments and diagnostics, and the description covers all aspects needed for an agent to understand what to expect, making it fully complete.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema for each parameter. For example, it explains the context for slippage_pp ('Bump for very thin partitions; drop to 0 if you have a smarter fill model') and clarifies the interaction between min_kelly and min_partition_leg_kelly, providing actionable guidance that the schema alone does not offer.

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 for opportunities where Pipeworx data disagrees with market price. It explicitly distinguishes its purpose as a discovery tool for "what should I bet on today" and breaks down three model segments, making the verb+resource specific and distinctive from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear guidance on when to use the tool (discovery without paging hundreds of markets) and explains tradeable-edge knobs for filtering. However, it does not explicitly mention when not to use it or directly contrast with sibling tools such as polymarket_edge_tracker for tracking specific edges, leaving some room for improvement in exclusionary 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, open-world, idempotent, non-destructive behavior. The description adds significant behavioral detail: response structure (tracked, expired, snapshot_dates), computation details (decay from daily closes, not intraday), and data availability conditions (snapshots written on cache-miss). 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 verbose but well-organized with clear sections for purpose, response structure, and limits. Every sentence provides useful information, though some streamlining could reduce length without losing 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?

No output schema is provided, but the description fully explains the return format including fields for tracked, expired, and snapshot_dates along with their meanings. It also covers limits (60-day TTL, computation details). For a time-series telemetry tool, this is comprehensive.

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

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

Schema coverage is 100% (both parameters have descriptions). The description adds minimal extra meaning beyond re-stating defaults and clamping boundaries. Baseline 3 is appropriate as schema already does the heavy lifting.

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

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

The description clearly identifies the tool as providing edge persistence and decay telemetry from daily snapshots. It uses specific language like 'answers how long has this edge existed and is it shrinking?' and distinguishes from sibling tool 'polymarket_edges' by focusing on historical time-series rather than current edges.

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

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

The description explains when to use this tool—when needing to know edge longevity and decay trends—and contrasts fresh vs. old wide edges. It provides context on limits (60-day TTL) but does not explicitly state when not to use or list alternative tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains that the tool simulates fills (walks the ladder, returns slippage, verdict) and warns about forced directional risk. 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-organized into sections (single-market vs basket) and front-loads the core purpose. However, it is somewhat verbose (nearly 4 paragraphs with complex sentences). While detail is appropriate for a complex tool, slight tightening 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?

Given the complexity (4 parameters, no output schema), the description is highly complete. It covers all modes, parameter interpretations, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), warnings about thin books, and forced directional risk. 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 description coverage is 100%, but the description adds meaning beyond the schema. For example, it explains that in basket mode, size_usd is 'settlement notional — shares per leg, each paying $1 at resolution,' and that side defaults to 'auto from partition sum.' This clarifies parameter semantics significantly.

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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific about the resource (Polymarket markets/events) and the action (check fill risk). Among sibling tools like polymarket_arbitrage, it carves a distinct role.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns that partial basket fills convert arb into an unhedged directional position. This provides 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?

Annotations already indicate read-only, idempotent behavior, and the description adds deep transparency: it explains how spreads are computed only when bet shapes match, details compatibility warnings, temporal alignment, and skipped leg counters. No contradictions with annotations.

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

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

The description is well-structured with headings (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. It is somewhat dense but every sentence adds value. Could be slightly more concise, but overall very 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?

Without an output schema, the description provides a good overview of the response format (leg-by-leg prices, top_spreads_pp, safety fields). It covers the essential behavioral details. A complete output schema would improve it, but given the absence, it is fairly comprehensive.

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

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

Schema coverage is 100%, and the description adds significant value: for 'topic', it lists all 10 shortcuts; for 'kalshi_event_ticker' and 'polymarket_event_slug', it provides examples and explains they override the mapped side. This goes well 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's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the two modes (topic shortcuts and explicit tickers) and includes details on the response, making it distinct from sibling tools like polynarket_arbitrage.

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

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

The description explains when to use each mode and provides important caveats, such as the rarity of real spreads and the role of compatibility warnings. However, it does not explicitly contrast with alternatives like polynarket_arbitrage, though the purpose is distinct enough.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping by identifier and the listing behavior when omitting key, providing useful context beyond annotations.

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

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

Three sentences, front-loaded with core purpose, no fluff. Efficient structure.

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

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

Covers purpose, usage, scope, relationship to siblings. Lacks description of return format, but tool is simple and for a single-parameter, read-only operation, it is nearly complete.

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

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

Schema description covers the parameter well (100% coverage). Description adds examples but no additional semantics beyond what schema already provides.

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

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

Clearly states the tool retrieves a value by key or lists all keys. Distinguishes from siblings (remember and forget) and gives concrete examples of stored items.

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

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

Explicitly says to use for looking up previously stored context without re-deriving. Pairs with remember and forget, providing a clear context, though no explicit when-not-to-use.

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

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

The description contradicts annotations: it describes a side effect (mark_read) while annotations declare readOnlyHint=true, implying no state changes. This is a serious inconsistency that undermines trust.

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, front-loaded with the main purpose, and includes necessary details without verbosity. It could be slightly more compact but is well-structured.

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

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

Given no output schema and 5 optional parameters, the description covers return fields, filtering options, the mark_read side effect, polling suitability, and an alternative access method. It is comprehensive for a query tool.

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

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

The description adds context beyond the schema (e.g., 'ISO timestamp' for since, 'sec_8k' as type example, and the effect of mark_read on future calls). With 100% schema coverage, the description still adds value by clarifying behavior and providing examples.

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

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

The description clearly states it pulls fired events from the subscription feed, specifying the resources returned (source, citation_uri, raw payload). It is specific about the tool's function and distinguishes it from siblings by focusing on alerts rather than changes or subscriptions.

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

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

The description provides context on when to use this tool (e.g., polling is fine) and mentions an alternative endpoint for scripts. However, it does not explicitly guide the agent on when to use this tool over other siblings like 'recent_changes' or 'list_subscriptions', limiting its usefulness for selection.

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

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

Beyond the annotations indicating read-only and idempotent behavior, the description details the underlying data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), notes that USPTO soft-fails until reactivated, and explains that the tool fans out in one parallel call. This provides a thorough understanding of the tool's 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?

The description is well-structured, starting with example queries, then explaining functionality, sources, parameter, return format, and alternative. It is efficient with no unnecessary words, though it is relatively long. Every sentence adds value, but it could be slightly more concise. Still, it is clear and 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 the tool has 3 required parameters, no output schema, and moderate complexity with multiple data sources and fallback logic, the description covers everything needed: input format, data sources, return structure (grouped changes, total count, citation URIs), and a clear alternative. It is complete and leaves no major gaps.

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

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

All three parameters are described in the input schema with 100% coverage, so the baseline is 3. The description adds extra context by providing examples for the `since` parameter (e.g., '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for monitoring, and clarifies that `value` accepts ticker or zero-padded CIK. This added usage guidance 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 provides a change feed for a company, listing multiple example queries such as 'What's new with X' and 'latest on Y'. It explicitly differentiates from the sibling tool entity_profile by recommending its use for static profiles.

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

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

The description provides specific when-to-use guidance with example queries and explicitly tells the agent to use entity_profile for static profile. It also gives parameter recommendations, like using '30d' or '1m' for typical monitoring of the `since` parameter.

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

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

Adds significant context beyond annotations: key-value scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. No contradictions with annotations.

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

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

Three well-structured sentences with no redundancy. Front-loaded with core action, followed by usage context and behavioral notes.

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

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

Given the tool's simplicity (no output schema, 2 parameters), the description covers purpose, usage, behavior, and parameter examples comprehensively. 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 already describes both parameters clearly. Description adds concrete examples for key (e.g., 'subject_property', 'target_ticker') and value ('findings, addresses, preferences'), enhancing practical understanding.

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

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

Description explicitly states 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from sibling tools recall and forget by positioning them as complementary.

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?

Directly says 'Use when you discover something worth carrying forward' and advises pairing with recall and forget. Though it doesn't state when not to use, the context is clear and actionable.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups', revealing internal complexity and efficiency benefit. 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?

Every sentence adds value: purpose, use case, supported types with specifics, and a usage tip. Front-loaded with key action phrases ('What's the ticker for…', 'Use FIRST'). No wasted words; efficient and structured.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers all necessary aspects: when to use, what each type returns, input formats, and internal behavior. It is fully self-contained and leaves no ambiguity.

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 significantly enriches parameter understanding by explaining accepted input formats (ticker, CIK, name for company; brand/generic for drug) and what each returns (e.g., ticker+10-digit CIK+name, RxCUI+ingredient+brand). Includes disambiguation and citation URI details beyond schema.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, provides specific query examples (ticker, CIK, RxCUI), and lists supported entity types (company, drug) with their output details. It distinguishes itself from siblings by being the primary name-to-ID resolver.

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 FIRST whenever you have a name but need an ID', giving strong when-to-use guidance. Does not explicitly list alternatives or when not to use, but the context is clear. Could mention related tools like entity_profile or compare_entities as alternatives for other tasks.

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 beyond annotations by explaining that the tool probes each entity with ai_visibility_check, ranks results by score, and returns a ranked list with score, confidence, and signal density. Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior, and the description adds valuable behavioral context without contradiction.

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

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

The description is concise (three sentences) and well-structured: first sentence states the action, second explains the process, third provides a use case and return value summary. No redundant information.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description covers essentials: process, return format, and use case. It could mention entity count limits or error handling, but overall it is sufficiently complete for a read-only, non-destructive tool with good annotations.

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

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

With 100% schema description coverage, the baseline is 3. The description adds meaning by specifying that the first entity is treated as the 'subject' for narrative and that context disambiguates common names. It does not significantly elaborate on models or _apiKey, but the schema descriptions are already clear.

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: 'Compare AI visibility across multiple entities side-by-side.' It explains the process of probing each entity with ai_visibility_check, ranking by score, and surfacing most/least recognized. This distinguishes it from siblings 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?

The description provides a clear use case: 'competitive AI-marketing audits' with an illustrative question. It implies this tool is for comparing multiple entities, contrasting with the single-entity probe ai_visibility_check. However, it does not explicitly mention when to use or avoid alternatives like compare_entities, leaving some ambiguity.

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 read-only, idempotent, non-destructive. Description adds details on partial failures, bundlephobia latency (5-30s), and sources_failed behavior. 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?

Long but efficient, every sentence adds value. Front-loaded with composite nature. Slightly verbose in middle but acceptable.

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, but description details return block fields, per-advisory detail, links, alternatives. Complete for the tool's 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 covers both parameters fully (100% coverage). Description adds minor context (defaults to latest) but mostly repeats schema.

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

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

Clearly states it's a composite check for npm packages covering license, advisories, bundle size, etc. Distinct from sibling tools which are unrelated.

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

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

Explicitly says to use when agent asks about safety, popularity, or cost of adding an npm package. Also notes NPM-only and mentions deps.dev:version for other ecosystems.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals detailed behavioral traits: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output format including offsets and scores. 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 concise at five sentences, front-loaded with the core purpose, and every sentence provides useful information without unnecessary words. It efficiently covers use case, behavior, and output.

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

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

Given no output schema, the description fully explains return values (top-N passages with offsets and scores), input constraints (200K cap), and behavior (truncation flag). It covers all necessary context for a tool with three parameters.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by reinforcing the 'max ~200K chars' for text and providing query examples. This goes beyond the schema but does not substantially new information beyond reinforcing constraints.

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

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

The description clearly states it performs semantic search inside a fetched record, using verb 'search' and specific resource 'record'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing internal search over external tools.

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

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

The description explicitly advises using this tool when 'the record is too big to cram into the prompt' and recommends pairing with another specific tool. However, it does not explicitly state when not to use it or provide alternative tools for contrast.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description aligns: it creates a subscription (write), is idempotent, and non-destructive. It also discloses account prerequisites, SMS caps (10/day), webhook auto-disable after 10 failures, and HMAC signing. No contradictions.

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

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

Well-organized: core purpose, then types, then delivery channels. The webhook detail is lengthy but valuable. Every sentence adds meaningful information; could be slightly more concise without losing clarity.

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

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

For a complex tool with multiple subscription types, delivery channels, and validation requirements, the description covers everything needed: account prerequisites, supported types, parameter syntax, delivery options, failure behavior, and limitations (SMS cap, webhook auto-disable). Output schema is absent but subscription id is mentioned.

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

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

Schema coverage is 100%, but the description adds significant value: concrete examples for each type (e.g., sec_8k items codes, fred_series series_id), detailed param structures, and delivery constraints (SMS must match verified phone, webhook HMAC). Far exceeds the schema's basic 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and specifying supported event types.

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

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

Provides when to use (subscribe to alerts), mentions account requirements (Pipeworx OAuth), and limitations (anonymous/BYO cannot persist). It gives type-specific examples and delivery options but does not explicitly contrast with sibling tools like recent_alerts or polymarket_edge_tracker for one-time queries.

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. The description adds that results are category-bucketed with tool+argument shapes from a live catalog, and explains the effect of the topic parameter. 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 verbose, opening with several synonymous phrases. While well-structured and front-loaded, it could be more concise without losing clarity.

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

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

Given the single optional parameter and lack of output schema, the description adequately explains the tool's role, usage, and output. It covers purpose, usage guidelines, and expected results, making it sufficiently complete for correct invocation.

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 for the topic parameter mirrors the schema exactly. No additional meaning is added beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states it is the onboarding entry point for an agent to learn what Pipeworx can do. It uses specific verbs and resources, distinguishing it from sibling tools by being the first action to take when unsure of capabilities.

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

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

It explicitly states to use this tool first when uncertain about Pipeworx's capabilities or to learn meta-tool usage. It provides calling conventions (no args or topic), but does not explicitly state when not to use it, though this is implied.

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

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

The description discloses key behavioral details beyond annotations: the row is deactivated (not deleted) and historical events remain accessible via recent_alerts. 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?

Two concise sentences with no wasted words, front-loading the core purpose and ownership rule.

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

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

Given the simple tool (one required param, no output schema), the description covers purpose, ownership, and behavioral outcome completely.

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

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

Schema coverage is 100% with a description for the 'id' parameter; the description adds no further semantic value beyond stating 'by id', which is already clear from the schema.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id', and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions'.

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

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

It explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for appropriate use, though it doesn't explicitly mention when not to use or alternatives.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds value by detailing the processing pipeline (SEC EDGAR vs grounded pipeline) and the return format (verdict, value, citation, reasoning). It also explains how tolerance_pct interacts with the verdict, providing behavioral insight 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 dense with information but remains well-organized. It front-loads trigger phrases and key actions. Some sentences are longer, but every part serves a purpose, so it earns a high score.

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 covers return values (verdict, actual value, citation, reasoning). It also explains the two processing paths and how tolerance works. This is complete for the tool's complexity and parameter set.

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 for both parameters. The description adds further context: example values for 'claim', and explains the default and override logic for 'tolerance_pct'. This enhances understanding 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's purpose: verify factual claims against authoritative sources. It provides concrete trigger phrases ('Is it true that…', 'fact check'), distinguishes between company-financial vs other claims, and notes it replaces multiple sequential calls. This makes the purpose unmistakable and differentiates it from siblings.

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

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

Explicitly advises 'Use whenever the agent needs to check whether something a user said is factually correct'. Provides examples of claim types and processing paths. While it doesn't explicitly list when not to use, the context is clear enough for an agent to decide.

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