Maven Central

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

Annotations already indicate this is read-only, idempotent, and non-destructive. The description adds behavioral details: scores range 0-100 per model, default model is free, calling Anthropic requires the user's own API key and incurs costs, and the return structure includes per-model data and a combined view. It does not mention potential rate limits or error conditions but is largely transparent.

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, using just a few sentences to convey the core functionality, parameters, and return structure. It is front-loaded with the key action and provides essential details without redundancy. Every sentence adds value, making it efficient for an AI agent to parse.

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

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

Given that there is no output schema, the description covers return values (per-model score, confidence, signals, raw_response, plus combined view) and use cases adequately. It could be more detailed about the 'signals' field or potential errors, but overall it provides sufficient context for an AI agent to understand the tool's output and use.

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

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

Schema coverage is 100%, so parameters are well-defined in the schema. The description adds value by clarifying the purpose of each parameter: 'entity' is the brand/topic to probe, 'models' specifies which LLMs (with default omitted), '_apiKey' is optional for Anthropic, and 'context' helps disambiguate. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility from 0-100 per model. It distinguishes itself from siblings by focusing on multi-model visibility scoring, with a default free model and optional Anthropic probe, and lists specific use cases like AI-marketing audits and pre-launch checks.

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

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

The description provides clear usage context: it mentions the default model, the need for a BYO _apiKey for Anthropic, and states use cases such as brand checks and competitive monitoring. However, it does not explicitly compare to sibling tools like 'scan_competitor_ai_presence' or clarify when not to use this tool, which could be improved.

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, and non-destructive behavior. The description adds useful context: it routes to 3,745 tools across 884 sources, fills arguments, and returns structured answers with citation URIs. This goes beyond annotations without contradicting them.

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

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

The description is front-loaded with the key preference over web search and uses a clear, structured format with examples. While slightly long, every sentence adds value. A minor rephrasing to reduce redundancy could improve conciseness.

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

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

Despite no output schema, the description explains return structure (structured answer with citation URIs) and routing behavior. It covers the tool's broad scope and usage, but omits details on error handling, rate limits, or authentication, leaving minor 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 all parameters aliased to 'question', which is well-described as a natural language query. The description provides examples but does not add new meaning beyond what the schema already conveys. Baseline of 3 is appropriate.

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

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

The description clearly states it answers factual questions about current/historical data from verified sources, and explicitly distinguishes itself from web search. It lists specific domains (SEC filings, FDA data, etc.) and provides examples, making the purpose precise and well-differentiated from sibling tools.

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

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

The description gives explicit preference over web search and provides trigger phrases ('what is', 'look up', etc.) and concrete examples. However, it does not specify when to use sibling tools like 'deep_research' or 'search' instead, limiting guidance on alternative choices.

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, openWorld), description adds refusal reasons, evidence format, and cost trade-off ('costs one extra LLM call'). 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?

Front-loaded with purpose and key differentiator. While slightly verbose, each sentence contributes to clarity (use cases, behavior, refusal reasons). Efficient for the complexity.

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

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

Given no output schema, the description fully explains the return structure for both success and refusal, including possible refusal codes. Covers all essential contexts for reliable agent 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% with aliases documented. Description does not add semantics beyond what the input schema provides for the parameters.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results. It distinguishes itself from the sibling tool 'ask_pipeworx' by emphasizing its refusal mechanism and appropriate use cases.

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 provides when to use (quoted, cited, or acted-on answers) and when to prefer the sibling ('prefer ask_pipeworx for casual lookups'). Includes concrete examples like financial verdicts, legal claims, and medical lookups.

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

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

Annotations already indicate safety (readOnly, idempotent, non-destructive). Description adds extensive behavioral details: fan-out patterns, classifiers, response shapes, safety mechanisms (low-confidence short-circuit, closed market detection, wide-spread warnings), and resolution-rule risk. 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?

Description is very long and includes detailed technical sections (classifiers, fan-out examples, response shapes) that are informative but could be more concise. Front-loads main purpose, but overall verbosity lowers score. Structured with section headers helps, but still excessive length.

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

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

Given the tool's complexity (many classifiers, fan-out patterns, safety checks), the description covers a lot. No output schema means description must compensate, which it does by detailing response shapes. Still, some details might be better in a separate doc. Overall adequate for complex 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%, baseline 3. Description adds value by explaining accepted formats for 'market' (slug, URL, question text), effects of 'depth' enum, and purpose of 'include_raw' with size implications. Goes beyond schema with examples and clarifications.

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 it researches a Polymarket bet by pulling Pipeworx data, with specific verb-resource pairing. Lists use cases (e.g., 'should I bet on X') which distinguishes it from sibling tools like ask_pipeworx or deep_research that handle general queries.

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

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

Explicitly says when to use ('Use for...'), but does not explicitly list when not to use or provide direct alternatives. However, context and sibling tool names imply boundaries, and the description covers edge cases (low-confidence, closed markets) that guide appropriate 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 indicate read-only, open-world, idempotent, non-destructive. Description adds detailed behavioral context: for companies, pulls latest financial metrics from SEC EDGAR/XBRL with proper fiscal year handling; for drugs, pulls FAERS, FDA, trial data. Results sorted by primary metric, returns paired data with citation URIs. No contradictions.

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

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

Description is information-dense but front-loaded with user-friendly examples. Every sentence adds value; however, it could be slightly more structured (e.g., bullet points for data fields) to improve scannability. Still concise given the complexity.

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

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

No output schema, but description thoroughly explains return format: paired data, sorted by metric, with citation URIs per entity. Covers both entity types and their specific data sources. Adequate for a comparison 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 for both parameters. Description adds meaning beyond schema: explains what each 'type' value retrieves (financials vs drug data) and specifies 'values' format (tickers/CIKs for companies, names for drugs) and constraints (2–5 items).

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

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

Description starts with user-oriented examples ('Compare X and Y', 'X vs Y') and clearly states the action: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from siblings by explicitly recommending over sequential single-pack lookups.

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

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

Provides explicit when-to-use guidance: for comparisons, rankings, head-to-head queries. Clearly states 'ALWAYS PREFER over sequential single-pack lookups'. Gives example queries that should trigger this tool.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral details: question decomposition, parallel routing to 3,745 tools, explicit gaps for unanswered facets, response time 15-60s, and pre-verified facts. No contradiction with annotations.

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

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

The description is relatively long but each sentence adds value. It is front-loaded with the core purpose. Minor redundancy like the sign-up URL could be trimmed, but overall well-structured for the complexity.

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

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

Without an output schema, the description thoroughly explains the return value: structured findings packet with verbatim evidence, confidence, source, fetched_at, citation, and gaps. It also covers usage context, requirements, timing, and excludes the need for further clarification.

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

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

Schema coverage is 100%, but description adds meaning beyond schema: explains depth enum values (quick=3, standard=5, thorough=8 with paid plan) and clarifies that question can be broad/multi-part in natural language. This enriches the agent's understanding.

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

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

The description clearly states that the tool performs grounded multi-source research in one call by decomposing questions and routing to many tools. It distinguishes itself from the sibling tool ask_pipeworx, which is for single lookups.

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

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

Explicitly states when to use (broad/multi-part questions) and when not to (use ask_pipeworx for single lookups). Also specifies requirements: Pipeworx account and paid plan for thorough depth.

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 idempotentHint=true, indicating safe read operations. The description adds valuable behavioral context: 'each result is ready to call directly, no second schema lookup needed' and that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' This goes beyond annotations and clearly sets expectations for the output format and immediacy of use.

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 appropriately sized for a discovery tool with many use cases. It is front-loaded with the primary purpose and examples, then details the return format and usage note. Every sentence serves a purpose, though a minor redundancy exists ('Accepts...aliases' close to the schema). Overall, it is 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?

Given the tool's complexity (6 parameters, 1 required) and the absence of an output schema, the description provides sufficient detail: what the tool does, when to use it, what it returns (names, descriptions, schemas with examples), and input parameter behavior. It does not cover error cases or default limit behavior explicitly, but the core needs are met. For a discovery tool, this is quite complete.

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

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

Schema coverage is 100% (all 6 parameters documented). The description adds meaning by confirming the 'query' parameter accepts natural language and lists example queries. It also clarifies that 'q', 'task', 'search', and 'description' are aliases for 'query', which is not explicit in the schema descriptions alone. This extra detail enhances understanding, so the description 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: 'Find tools by describing the data or task.' It lists numerous example domains (SEC filings, financials, etc.) and explains that it returns top-N relevant tools with full schemas. It distinguishes itself from sibling tools by advising to call it 'FIRST when you have many tools' to see the option set, which differentiates it from other search or entity-specific tools.

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

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

The description provides explicit when-to-use guidance: 'Call this FIRST when you have many tools available and want to see the option set.' It also lists specific domains for which this tool is appropriate. While it does not explicitly state when not to use it (e.g., if the exact tool is known), the context implies that it is for browsing/discovery rather than direct retrieval. This is strong but could be more exhaustive.

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 and idempotent. The description adds value by detailing the parallel fan-out across multiple sources, specific return fields, and soft-failure for patents. However, it does not cover potential latency or response size.

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 yet information-dense. It front-loads with example queries, states the main function, then lists sources and return fields efficiently. Every sentence serves a purpose with no wasted words.

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

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

Given no output schema, the description comprehensively lists return values and sources (cik, filings, fundamentals, patents, news, LEI). Includes caveats and prerequisites. Could mention error handling or response format, but is largely sufficient for its complexity.

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

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

Schema coverage is 100% with each parameter already well-described. The description reinforces the schema content (e.g., type only 'company', value as ticker/CIK) but adds limited new semantic information beyond what the schema provides. Baseline 3 applies.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company in one parallel call. It includes example queries and explicitly distinguishes itself from chaining individual lookups, making its purpose unmistakable.

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

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

The description explicitly says to prefer this tool over chaining single-pack lookups for holistic views. It advises to use resolve_entity first if only a name is given, and includes a caveat about the patent API sunset, providing clear usage guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, which is beyond annotations but not extensive.

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 purpose, each sentence adds value (purpose, when-to-use, related tools). No wasted words.

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

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

For a simple single-parameter delete tool, the description covers purpose, usage context, and sibling tools. Missing error handling or return details but acceptable given no output schema.

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

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

Schema coverage is 100% with clear description of the 'key' parameter. Description adds no additional meaning beyond 'by key'.

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 states 'Delete a previously stored memory by key' – clear verb, resource, and method. It distinguishes from siblings by naming 'remember' and 'recall'.

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

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

Explicitly lists three use cases: stale context, task completion, clearing sensitive data. Does not explicitly mention when not to use, but pairing with siblings implies alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also specifies the output as 'a single text blob ready to drop at site-root/llms.txt.' No contradiction with annotations. Minor gap: does not mention error handling or what happens if the URL is unreachable.

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 with no wasted words. It front-loads the main action, then explains the process, output, and use cases in a logical order. Every sentence adds value.

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

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

For a simple tool, the description covers purpose, output format, and use cases. However, it lacks details on error handling, rate limits, or privacy considerations when fetching URLs. Given the absence of an output schema, a brief note on the exact markdown structure would have been helpful.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning: it provides an example URL format ('e.g. https://example.com or a specific landing page') and implies the max_links default/range via 'default 25, max 50.' This does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the verb 'generate' and the resource 'llms.txt file', with the scope 'for any URL'. It distinguishes itself from sibling tools by specifying a unique function (generating llms.txt files) not covered by any other tool in the list.

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 use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not discuss when to avoid using the tool or mention alternatives, but 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds minimal behavioral context beyond stating it returns the latest version. 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 concise sentence that is front-loaded with the purpose. It could be slightly more structured but is efficient and free of fluff.

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

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

For a simple tool with two parameters and an output schema, the description is sufficiently complete. It explains the core functionality. Minor gap: could clarify 'release version' excludes snapshots.

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

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

The schema has no descriptions for parameters (0% coverage), so the description compensates by naming the parameters as groupId and artifactId in context, clarifying they are Maven coordinates.

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 that the tool returns the most recent release version for a given Maven groupId and artifactId. It uses specific naming and distinguishes from siblings like 'list_versions'.

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 for fetching the latest version of a Maven artifact, but it does not explicitly state when to use this tool versus alternatives like 'list_versions' or when not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the core behavioral traits. The description adds only that the tool returns specific fields, which does not significantly expand behavioral understanding beyond what annotations provide. No contradiction found.

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 purpose and return fields, followed by usage guidance. Every sentence adds value, with no redundant or extraneous information. Ideal for quick comprehension.

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 no required parameters and no output schema, the description adequately covers what the tool does, what it returns, and when to use it. It could mention handling of empty results or pagination, but these are not necessary given the tool's simplicity and the 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?

The schema has 100% coverage for the single parameter 'include_inactive' with a clear description. The tool description does not add any additional meaning or nuance to this parameter, so it meets the baseline expectation.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', specifying the exact scope. It also lists the return fields, making the purpose unambiguous and distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description gives clear context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This explicitly tells the agent when to invoke this tool. It does not explicitly state when not to use or list alternatives, but the provided context is sufficient for correct 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context such as pagination, rate limits, or authentication requirements.

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 concise sentence with no fluff. It is appropriately front-loaded but could be slightly more 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 presence of an output schema and many sibling tools, the description lacks differentiation and does not mention the optional 'rows' parameter, leaving gaps in understanding.

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 low (33%), and the description does not compensate by explaining the parameters beyond their names. The optional 'rows' parameter is not mentioned.

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 lists all published versions for a given groupId and artifactId. However, it does not explicitly differentiate from the sibling tool 'latest_version', which could cause confusion.

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 when to use (when you need all versions), but provides no explicit guidance on when not to use or alternatives like 'latest_version'.

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 on read/write are minimal, but the description adds critical behavioral context: rate limits (5/day), free nature, quota exemption, and how feedback is processed ('digests daily, signal affects roadmap'), exceeding what annotations provide.

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

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

The description is well-structured and front-loaded with purpose, then usage, then behavioral details. Every sentence adds value, though slightly longer than minimal (but justifies length).

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

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

Given no output schema and moderate parameter complexity, the description covers all necessary aspects: purpose, when to use, how to format, rate limits, quota impact, and relationship to roadmap. No gaps identified.

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

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

With 100% schema coverage, the description still adds significant value by elaborating on each enum value (bug, feature, etc.) and explaining the message format (1-2 sentences, 2000 chars max), complementing 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?

Description uses specific verbs ('tell', 'broke, missing, or needs to exist') and clearly distinguishes the tool's purpose from siblings by framing it as feedback submission rather than tool use.

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 for bugs, features, data gaps, or praise, and provides a negative guideline ('don't paste the end-user's prompt'), leaving no 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 readOnly and idempotent. The description adds behavioral context: derived from CF analytics, no PII, cached 5min-1h. This complements annotations well.

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 main purpose, followed by bullet-like use cases and technical details. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains what is returned, source, privacy, caching, and window interpretation. Annotations cover safety traits.

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 schema description is good. The tool description adds use-case guidance for different windows, slightly enhancing semantics 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 returns trending tools, packs, and call volume. It distinguishes the tool from siblings by focusing on aggregated signal, though it doesn't explicitly contrast with similar tools like 'discover_tools'.

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

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

The description provides three specific use cases (discovering hot sources, confirming popular tools, aligning use cases) and hints at window selection for different needs. It does not explicitly state when not to use this tool or name alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds extensive behavioral detail: required arguments, failure conditions, monotonicity checks, partition checks, fill check with realizable vs theoretical edge, semantic anchor, partition filter, and output structure. No contradiction with annotations, and it transparently explains when not to trade.

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 somewhat verbose, with several long sentences and repeated information (e.g., 'call with no args fails' is stated twice). While structure is logical (stating requirement, then modes, then details), it could be more concise without losing critical 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 no output schema, the description adequately explains the response structure (opportunities[], partition_check, etc.) and edge cases (placeholders, fill check). It covers both modes and the various checks performed. The tool is complex, but the description provides sufficient context for an agent to understand inputs and 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?

Input schema covers 100% of parameters with descriptions. The description adds significant value beyond schema: it recommends event mode for specific markets, explains cross-event scanning with examples, and describes the behavior of each parameter (e.g., 'walks child markets', 'searches related events'). This extra context justifies a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'. It distinguishes between two modes (event and topic), and the verb 'find' plus resource 'arbitrage opportunities' is specific. It also references related sibling tool polymarket_fill_risk, aiding differentiation.

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 guides when to use event vs topic modes, and warns that calling with no arguments fails. It advises using polymarket_fill_risk for custom sizing. However, it does not explicitly compare against other arbitrage-related sibling tools like polymarket_edges, which would improve 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 confirm read-only, idempotent, non-destructive behavior, and the description reinforces this with caching details ('Cached 1h at the KV level'), segmentation logic, and diagnostic output explaining empty segments. 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 detailed but verbose, covering extensive model internals. While structured into segments and front-loaded with purpose, the technical depth may be excessive; a more condensed version 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 no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields. It covers all necessary information for an agent to interpret results correctly.

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

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

Schema coverage is 100%, and the description adds significant nuance beyond schema descriptions, e.g., min_kelly explanation and min_partition_leg_kelly rationale. The description enriches parameter understanding without contradicting 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes from siblings by specifying its use case ('what should I bet on today') and detailing three unique model families, making it distinct from other Polymarket 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 frames the tool for discovering opportunities without paging markets and explains the three segments and tradeable-edge knobs, guiding parameter tuning. However, it lacks explicit when-not-to-use guidelines or references to sibling tools like polymarket_arbitrage for alternative 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 indicate read-only, idempotent, open-world. The description adds significant behavioral details: data sources (daily snapshots), response structure (tracked, expired, snapshot_dates), computation of decay metrics, and constraints (TTL, non-intraday). No contradictions.

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

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

The description is front-loaded with the core purpose and response structure, then dives into details. It is somewhat lengthy but each sentence adds value. Could be slightly more concise but well-organized.

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

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

With no output schema, the description fully explains the return format: tracked[] with full time-series, first_seen, trend, decay; expired[] with lifespan; snapshot_dates. It covers limits and data gaps comprehensively. Complete for a tool of this complexity.

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

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

Both parameters are fully described in the input schema (100% coverage). The description adds trading context and how the lookback affects the analysis, but does not provide additional syntax or format 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 that the tool provides edge persistence and decay telemetry, specifically answering how long an edge has existed and whether it is shrinking. It distinguishes itself from raw edge data by focusing on temporal analysis.

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 context on why decay matters (e.g., old wide edge vs fresh wide edge) and mentions limits (TTL, when snapshotting started). However, it does not explicitly compare to sibling tools like polymarket_edges or provide when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds behavioral details such as walking the order-book ladder, returning verdicts, and explaining risks of partial fills on baskets. 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 thorough but somewhat verbose (around 250 words). It is well-structured with front-loaded purpose, separated modes, and parameter details. Every sentence adds value, but it could be slightly more concise.

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

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

Despite having no output schema, the description fully documents return values for both modes, including edge cases like thin books and partial fills. The tool is complex, and the description provides all necessary 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 descriptions for all 4 parameters. The description adds significant meaning beyond the schema, such as explaining side defaults, size interpretation for buys vs sells and baskets, and clamping range.

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

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

The description clearly states the tool's function as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from siblings by instructing use before arbitrary signals or edges trades above $500.

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

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

The description provides explicit when-to-use guidance (before arbitrage signals or large edges trades) and outlines required parameters (one of market or event) with mode-specific instructions. It lacks explicit when-not-to-use scenarios, but the context is clear 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 declare readOnlyHint, openWorldHint, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral details: two modes, response structure (leg-by-leg prices, matched spreads), safety fields (compatibility_warning, temporal_alignment, skipped_cross_type). It explains edge cases like matched_pairs=0 and why spreads might be invalid. 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 long but well-structured: opening sentence defines purpose, then modes, response, safety fields. Each sentence adds value. Could be slightly more concise, but the complexity of the tool justifies the length.

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

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

No output schema, so description must cover return values. It does: each venue's prices, matched spread, safety fields like compatibility_warning and temporal_alignment. Given the tool's complexity (cross-venue, multiple modes, compatibility checks), the description is comprehensive and covers edge cases.

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 meaning by explaining the difference between the 'topic' parameter (pre-mapped shortcuts) and explicit parameters (kalshi_event_ticker, polymarket_event_slug). It also provides examples and explains when to use each mode.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like 'polymarket_arbitrage' which would be single-venue, and 'compare_entities' which is general. The verb 'spread' and resource 'cross-venue' are specific.

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

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

The description explains two modes (topic and explicit) and when each is appropriate. It warns that pre-mapped topics often return compatibility warnings, thus guiding users to use explicit mode for custom pairings. It lacks an explicit 'when not to use' but provides enough context for the agent to decide.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds behavioral context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)'), which goes 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 long, front-loaded with the action, and contains no unnecessary words. Every sentence adds value.

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

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

Given the tool has one optional parameter and no output schema, the description fully covers both usage modes (retrieve by key, list all keys) and scoping. It is complete for the complexity level.

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 single parameter 'key' described. The description adds value by explaining the behavior when the key is omitted ('list all keys'), which is not explicitly stated in the schema's 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 the purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb ('retrieve') and resource ('value'), and distinguishes from sibling tools like remember and forget.

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

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

The description provides context on when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, and scoping. However, it does not explicitly state when not to use this tool.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds concrete behavioral details: how mark_read flags events as read so subsequent calls return newer ones, and that the feed is persisted. No contradictions.

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

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

Three sentences, each purposeful. The first sentence states the purpose and return fields, the second covers filtering parameters, the third explains mark_read and alternative access. No fluff.

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

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

With 5 optional parameters and no output schema, the description compensates by detailing return fields and the read-marking behavior. It also mentions an alternative HTTP endpoint, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds context beyond schema: it explains 'since' as ISO timestamp, gives an example for 'type' ("sec_8k"), and describes the effect of 'mark_read'. This enhances parameter understanding.

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

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

The description uses specific language ('pull fired events from your subscription feed') and details what the tool returns (source, citation_uri, raw payload). It is clearly distinguished from sibling tools, none of which focus on alert retrieval.

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

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

It explains that polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, giving context for when to use this tool vs direct access. It does not explicitly mention when not to use it or compare to other MCP tools, but the guidance is sufficient.

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 (readOnlyHint, idempotentHint, etc.), the description discloses important behavioral traits: it fans out to SEC EDGAR, GDELT→GNews fallback (with rate-limit and error conditions), and USPTO with a soft-fail. It also mentions the PatentsView API sunset. This provides rich context beyond structured fields.

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 dense paragraph that front-loads example queries, then explains fan-out, parameter details, and alternative. While it packs in information, each sentence serves a purpose. Minor verbosity could be trimmed, but overall it's 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?

Given 3 required parameters, rich annotations, and no output schema, the description covers all essential aspects: what it does, sources, fallback, parameter formats, and alternative. It mentions the output structure (changes grouped by source, total_changes, citation URIs), which is sufficient for an agent to understand the return format.

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

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

Schema coverage is 100%, but the description adds valuable context: it explains the 'since' parameter accepts ISO dates or relative shorthand with examples, and suggests '30d' for typical monitoring. It also clarifies that 'value' can be a ticker or CIK. These additions exceed baseline expectations.

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 within a time window, fanning out to multiple sources. It distinguishes itself from the sibling tool 'entity_profile' by specifying that entity_profile gives a static profile regardless of window. The verb 'get' is implied by the examples, and the resource is explicitly the change feed.

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

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

The description provides explicit query examples ('What's new with X') and clear guidance on when to use this tool versus 'entity_profile'. However, it does not discuss usage relative to other sibling tools like 'search' or 'compare_entities', leaving room for ambiguity in some contexts.

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 idempotency and non-destructiveness. The description adds value by detailing persistence behavior (24h for anonymous, persistent for authenticated users) and scoping by identifier. 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 four sentences long, each serving a distinct purpose: state action, explain when to use, describe storage details, and pair with sibling tools. No fluff, well-structured.

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

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

For a simple tool with 2 parameters and good annotations, the description covers all essential aspects: purpose, usage context, persistence behavior, and relationship to siblings. No output schema needed.

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 3 applies. The description adds context on typical key naming conventions (e.g., 'subject_property') but does not add syntax or format details 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 clearly states the verb 'Save data' and specifies the resource as data needed for reuse. It distinguishes from sibling tools 'recall' and 'forget' by explicitly pairing with them, and mentions scoping by identifier.

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 guidance on when to use the tool ('when you discover something worth carrying forward') and provides context about authentication persistence vs anonymous sessions. It does not explicitly state when not to use, but the guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by revealing that each call cascades through several internal lookup endpoints, replacing 2-3 manual lookups. No contradictions.

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

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

The description is moderately sized but front-loaded with examples and action-oriented phrasing. Every sentence contributes valuable context without redundancy. Could be slightly more concise but highly effective.

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

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

Given the tool's complexity (2 parameters, enum type, no output schema), the description covers the purpose, types supported, return details, and even includes citation URIs. It is sufficiently complete for an agent to understand and use correctly.

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

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

Schema coverage is 100% (both parameters described). The description enhances semantics by giving concrete examples of accepted values (e.g., tickers, CIKs, names) and detailing the return information for each type (e.g., company returns ticker, CIK, company_name).

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, illustrating with examples like ticker, CIK, RxCUI. It distinguishes from sibling tools by positioning itself as the first step when an ID is needed, and explicitly lists supported entity 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?

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', providing clear context. It does not explicitly state when not to use or name alternatives, but the scope is well-defined by supported types.

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

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

Discloses it internally calls ai_visibility_check for each entity, ranks results, and returns structured data. Annotations already indicate readOnly, idempotent, and non-destructive; description adds no contradiction and enriches with internal process details.

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

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

Three sentences, front-loaded with main purpose, no redundant words. Every sentence adds value: purpose, method, output, and use case.

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, description adequately explains return format (ranked list with score, confidence, signal density). Covers parameters, internal calls, and use case. No gaps for an agent to 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?

Adds beyond schema: first entity treated as 'subject', others as competitors; default model is workers-ai; context disambiguates names. Schema covers all parameters, and description provides narrative context for correct usage.

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

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

Description clearly states verb 'Compare AI visibility' and resource 'multiple entities side-by-side'. Specifies output: ranked list with score, confidence, signal density. Distinguishes from sibling tools like ai_visibility_check (single probe) by emphasizing side-by-side comparison.

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

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

Explicitly gives use case: 'competitive AI-marketing audits'. Implies when to use (multi-entity comparison) but does not explicitly state when not to use or alternatives like calling ai_visibility_check repeatedly. Still clear enough for appropriate 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?

Discloses partial failure behavior (bundlephobia timeout 5-30s, sources_failed listed). Returns a detailed summary block. Annotations already indicate read-only, idempotent, non-destructive; description adds dynamic behavior insights.

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?

Dense but well-organized: starts with main purpose, then usage guidelines, return contents, limitations, and edge cases. Every sentence provides necessary information without redundancy.

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

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

Despite no output schema, the description fully explains return structure, potential delays, and ecosystem scope. Covers composite nature and graceful degradation, making it complete for agent 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 covers both parameters with descriptions. Description adds example version format and clarifies scoped packages are accepted, providing slight extra value. Baseline 3 raised to 4 for the practical 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?

Clearly states it's a composite check for npm package evaluation covering license, advisories, version history, bundle size, and tree-shake support. Differentiates from sibling tools like list_versions which are simpler. Mentions NPM-only scope.

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

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

Explicitly tells when to use: when agent asks about safety/popularity/size or cost of adding a package. Also tells when not: for non-NPM ecosystems, advise using deps.dev directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the searchable fields (groupId, artifactId, version, tags), which is behavioral context beyond annotations. However, it omits details like pagination behavior or result limits, which are partially covered in parameter descriptions.

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, clear sentence that immediately conveys the tool's purpose. It is front-loaded with the key action and scope, with no unnecessary words. Every part earns its place.

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

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

Given the existence of an output schema (not shown here but indicated as present), the description does not need to detail return values. The three parameters are well-documented. However, the description could mention default sorting or behavior when no results, but overall it is sufficient for a straightforward search tool.

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

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

Schema description coverage is 100%, so all parameters (query, rows, start) have clear descriptions in the schema (e.g., 'Max rows, 1-200 (default 20)'). The description adds no extra meaning beyond the schema, meeting the baseline expectation but not exceeding it.

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 full-text search across specific fields (groupId, artifactId, version, tags), which distinguishes it from siblings like search_by_coords (coordinate search) and search_within (scoped search). The verb 'search' and resource 'groupId, artifactId, version, tags' are explicit.

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

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

The description provides no guidance on when to use this tool versus alternative search tools (e.g., search_by_coords, search_within). It simply states the action without context for selection, leaving the agent to infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. Description adds little beyond stating flexibility of parameters.

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

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

Two sentences, front-loaded, no unnecessary 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?

Adequate for a read-only lookup tool with output schema. Could mention the data source (e.g., Maven Central), but not essential.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that any combination of parameters can be 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 ('lookup') and resource ('Maven coordinates'), distinguishing it from sibling tools like 'search' and 'latest_version'.

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

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

Indicates to use when you have Maven coordinates, but does not explicitly state when not to use or provide alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. Description adds rich behavioral details: return format (passages with character offsets and similarity scores), embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K) with truncation flagging. No contradictions.

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

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

Three sentences: first defines purpose, second explains when to use and benefit, third adds technical details. No wasted words, well-organized, and front-loaded with the core action.

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, description fully explains return values (passages with offsets and scores) and edge cases (truncation). All necessary information for an agent to invoke the tool correctly is present.

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 3 parameters (100% coverage). Description enhances meaning by explaining text as 'document text', providing query examples, and stating limit defaults. Also notes the cap and truncation behavior tied to the text parameter.

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 it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result) and mentions returning passages with offsets and scores. However, it does not explicitly differentiate from sibling tools like search or search_by_coords, though context implies it's for in-document search.

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

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

Explicitly says to use when a record is too large for the prompt and mentions pairing with ask_pipeworx_grounded. Clear context for usage, but lacks explicit 'when not to use' or direct alternatives beyond the paired tool.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, which align with creating a subscription. The description adds behavior details: requires OAuth account, delivery channels (feed always on, email/sms/webhook with specific constraints like SMS cap and webhook auto-disable). Could mention idempotency explicitly but overall transparent.

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 purpose, then prerequisites, subscription types with examples, and delivery channels. Although thorough, it is slightly lengthy but every sentence adds value.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers all necessary aspects: types, parameters, delivery behavior, prerequisites, and return value ('new subscription id'). It feels complete for an agent to 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 coverage is 100% with descriptions, and the description adds significant context: examples for each subscription type, parameter structure, and delivery options (including webhook signing and phone verification). This goes well 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: 'Create a proactive monitoring subscription to a live-data event stream.' It identifies the specific action (create subscription), the resource (alerts), and distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description provides context on when to use (subscription creation), prerequisites (Pipeworx OAuth account), and details about delivery channels and limits. It implicitly covers usage but lacks explicit comparisons to sibling tools or 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, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns category-bucketed examples with tool+argument shapes drawn from a live catalog, and explains behavior with and 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 front-loaded with common user queries and is well-structured. While slightly lengthy due to listing all categories (also in schema), it is informative and avoids redundancy with the annotations.

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

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

For a tool with one optional parameter and no output schema, the description is complete. It explains the output format (category-bucketed examples with tool shapes), use cases, and how to invoke. No gaps identified given the 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?

Schema coverage is 100% for the single optional parameter. The description adds meaning by listing the allowed topic values (finance, pharma, etc.) and explaining the behavior when omitted (full spread). It also specifies that returned examples include tool and argument shapes, 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 is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs like 'returns' and distinguishes from siblings such as ask_pipeworx and discover_tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides guidance on passing a topic to focus, implying alternatives for direct 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 indicate it's a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds context that the row is deactivated (not deleted) and historical events remain, which aligns with annotations and provides additional insight.

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 efficient sentences with no redundancy. First sentence states action and constraint; second explains outcome. Every sentence serves a 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?

For a single-parameter tool with annotations, the description fully covers behavior (ownership, deactivation, historical availability) without needing output schema. It is complete.

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

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

The schema has 100% coverage with a clear description for 'id' (uuid returned by subscribe). The description adds no further parameter meaning beyond mentioning 'by id'. 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 action ('Cancel a subscription by id') and the tool name is explicit. However, it does not explicitly differentiate from sibling tools like 'subscribe' or 'list_subscriptions', which is a minor gap.

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

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

The description specifies ownership enforcement ('you can only cancel your own subscriptions') and the behavioral outcome (deactivation, not deletion). It lacks explicit 'when to use' vs alternatives, but the context is sufficient given the simplicity.

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

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

Annotations already provide safety hints. Description adds source (SEC EDGAR + XBRL), return values (verdict, structured form, citation, delta), and replaces multiple calls. 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?

Somewhat verbose (5 sentences) but each sentence adds distinct value. Could be slightly tighter but still effective.

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

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

Given single parameter and no output schema, description fully covers purpose, usage, behavior, parameters, and return values. No gaps.

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

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

Schema coverage is 100% with a good parameter description. The description further clarifies natural-language format with examples, adding significant value beyond schema.

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

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

Clear verb-resource pair 'validate claim' backed by multiple example user intents. Distinguishes from siblings by specifying scope (company-financial via SEC/XBRL).

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 ('check factual correctness') and hints at efficiency (replaces sequential calls). Does not explicitly mention when not to use, but scope limitation is clear.

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