Nuget

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds specifics: it probes multiple models, returns per-model score/confidence/signals/raw_response plus combined view, and discloses that Anthropic calls require a BYO API key and incur direct costs. 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 with no wasted words. First sentence states core function, second adds model details, third covers output and use cases. Front-loaded 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 no output schema, the description fully explains return values (per-model object and combined view). It covers all parameters, usage context, and cost implications. No gaps for a read-only probe tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that 'workers-ai' is the default free model and that `_apiKey` is only needed for Anthropic. This supplements the schema descriptions without redundancy.

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

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

The description clearly states the tool probes LLMs for visibility scores (0-100) per model, specifying the verb 'probe' and resource 'LLMs'. It distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring with a score output, not just asking or scanning.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to use the Anthropic model (requires _apiKey, user pays). It does not explicitly mention alternatives or when not to use, but the context is clear enough for an AI 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 the tool as read-only, idempotent, and non-destructive. The description adds transparency by stating it returns structured answers with stable citations (pipeworx:// URIs), which is valuable context beyond annotations.

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

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

The description is longer than minimal but well-structured with a strong opening directive, clear use-case enumeration, and concrete examples. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Given the tool's broad scope and no output schema, the description adequately covers inputs and behavior. It explains the routing mechanism and return type (citations), which is sufficient for agent selection. Examples fill gaps in detailing expected question varieties.

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 meaning by explaining that the 'question' parameter accepts natural language and lists aliases. It also provides example inputs, helping the agent understand expected format.

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

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

The description clearly states the tool's purpose: answering factual questions about current or historical data from diverse sources, routing to the appropriate specialized tool. It distinguishes itself from siblings by explicitly preferring over web search and listing specific domains (SEC filings, FDA drugs, etc.).

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

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

The description provides explicit guidance on when to use the tool: 'PREFER OVER WEB SEARCH' and lists trigger phrases like 'what is', 'look up', 'find', etc. It gives numerous examples covering various domains, making it easy for an agent to determine applicability.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds refusal behavior (explicit refusal reasons when data doesn't directly answer) and the extraction-only approach, which are valuable behavioral details 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?

Four sentences, front-loaded with the key concept. Efficiently covers purpose, usage, behavior, and return format without redundancy.

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

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

Given no output schema, the description adequately covers return format (answer, evidence, confidence, etc.), refusal reasons, and high-stakes usage context. Complete for the tool 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 aliases all described. The description only mentions 'question' and not aliases, adding no extra semantic value beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode for high-stakes reads, explicitly distinguishing it from sibling 'ask_pipeworx' by noting the extra LLM call and the use case for quoted/cited answers.

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

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

Provides explicit guidance: use when answers will be quoted/cited/acted on (high-stakes), and prefer 'ask_pipeworx' for casual lookups. Also mentions the cost of an extra LLM call.

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

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

The description extensively discloses behavioral traits beyond annotations: it explains the fan-out mechanism, response shapes (market, analysis, evidence), resolver contract with match confidence, parent_event extraction, news fallback handling, and safety checks for low confidence, closed markets, and wide spreads. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

The description is lengthy but well-structured, starting with the core purpose then covering classifiers, fan-out examples, response fields, and edge cases. It is front-loaded with essential info. While it could be slightly more concise, the detail is justified by the tool's complexity.

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

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

Given the tool's complexity (multiple data sources, classifiers, safety checks) and the absence of an output schema, the description is remarkably complete. It covers all major response fields, edge cases (low confidence, closed markets, wide spreads), fallback mechanisms, and provides concrete examples, leaving the agent well-informed.

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

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

The input schema already covers all three parameters with descriptions and examples (100% coverage). The description adds practical context: what each parameter accepts (e.g., market input can be slug, URL, or text), and explains the trade-offs for depth and include_raw. This extra context justifies a score above baseline 3.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists specific input types (slug, URL, question text) and use cases ('should I bet on X'), distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges which are more narrow.

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 and explains when to use the tool (e.g., 'Use for should I bet on X'). It does not explicitly state when not to use it or list alternatives, but it does cover edge cases like low-confidence matches and closed markets, giving the agent context on limited applicability.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds details: type='company' pulls specific 10-K financials, type='drug' pulls FAERS and trial counts, results sorted by primary metric, returns paired data with citation URIs. No contradictions with annotations.

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

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

Well-structured with trigger phrases upfront, but somewhat verbose (around 100 words). Every sentence adds 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?

For a complex tool with two entity types, multiple data sources, and no output schema, the description explains return data, sorting, citation URIs, and efficiency gains. Comprehensive enough for 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 covers 100% of parameters. Description adds significant meaning: examples for values (tickers/CIKs for company, drug names), explains what data each type retrieves, and mentions max/min items. Enhances schema significantly.

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

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

The description clearly states the tool is for side-by-side comparison of 2–5 companies or drugs, gives example queries ('Compare X and Y', 'which is bigger'), specifies data sources (SEC EDGAR, FAERS), and distinguishes it from 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive on when to use this tool versus alternatives like entity_profile or other single-entity tools.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradictions.

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

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

The description is two sentences, perfectly front-loaded with the core purpose, and no redundant information. 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 6 parameters (1 required), full schema coverage, and annotations, the description provides complete guidance: it explains the return format and usage pattern. No output schema exists, but the description covers what the agent needs to know.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'query' parameter as a natural language description and listing aliases (task, q, description, search) with examples. This clarifies usage beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists diverse domains and explicitly distinguishes from siblings by stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 instructs to 'Call this FIRST' for discovery, implying a clear usage context. It does not explicitly state when not to use it, but the context of browsing/searching is well established, and the sibling tool list provides alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral detail: fan-out across SEC, XBRL, USPTO, news, GLEIF; return fields including URIs; patents soft-fail note; news fallback; name unsupported. 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 somewhat lengthy but front-loaded with examples and purpose. Every sentence adds value: usage guidance, return details, limitations. Could be slightly tighter, but given the complexity, the structure is effective.

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

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

Despite no output schema, the description fully details return values: cik, company_name, recent_filings (with URIs), fundamentals, patents status, news fallback, LEI. It covers input constraints, cross-source behavior, and limitations. No gaps for this use case.

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

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

Schema description coverage is 100% with both parameters described. The description reinforces input types (ticker or zero-padded CIK) and the enum restriction. It adds context (e.g., 'zero-padded CIK') beyond the schema, but the schema itself is clear. Baseline 3, plus one for clarifying input 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 starts with concrete examples ('Tell me about X', 'research Acme', etc.), then states 'full cross-source profile of a US public company in ONE parallel call.' It clearly specifies the verb (get profile), resource (US public company), and scope (cross-source). It distinguishes from siblings by recommending this tool over chaining 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?

Explicit guidance: use when user asks for a holistic view of a US public company; prefer over chaining single-pack lookups; if only a name is provided, use resolve_entity first. This provides clear when-to-use and when-not-to-use instruction.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description adds behavioral context about clearing sensitive data, which is useful but doesn't contradict annotations.

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

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

Two sentences with no unnecessary words. The first sentence states the action, the second provides usage context. Front-loaded 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?

For a simple tool with one required parameter, no output schema, and annotations present, the description covers purpose, usage, and links to siblings. Nothing significant is missing.

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

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

Schema coverage is 100% and the parameter 'key' has a straightforward description. The tool description does not add any additional semantics beyond the schema, so it meets the baseline.

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

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

The description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. It also distinguishes the tool from siblings 'remember' and 'recall', making its unique role obvious.

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

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

Explicit usage guidance is given: 'Use when context is stale, the task is done, or you want to clear sensitive data'. This tells the agent exactly when to invoke this tool over alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive; description adds that it fetches the page, extracts content, and emits standard markdown format, providing full behavioral context beyond annotations.

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

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

Description is two sentences plus a bullet list of use cases, all front-loaded. Minimal wordiness, effectively 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 high schema coverage, rich annotations, and no output schema, the description sufficiently explains the tool's output format and process. No critical missing information.

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

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

Parameter schema coverage is 100%, so description doesn't need to add much. It implicitly refers to 'URL' but does not elaborate on 'max_links' beyond the schema's default and max.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action and resource. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on the specific output format.

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

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

Description lists three concrete use cases (client site indexing, personal drafting, competitor auditing). It does not explicitly exclude alternatives but provides clear contextual guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's role is reduced. It adds that the tool returns versions, tags, dependencies, dates, which is useful context but doesn't discuss any behavioral aspects like pagination, rate limits, or authorization needs. No contradictions with annotations.

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

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

The description is a single concise sentence that efficiently communicates the tool's functionality without any wasted words. It is front-loaded with the key concept 'Registration metadata'.

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 rich annotations, the description adequately summarizes what the tool does. However, given sibling tools like 'scan_dependency' and 'list_versions', more explicit differentiation could improve completeness, but it is still sufficient for agent decision-making.

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

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

Schema description coverage is 100% with clear descriptions for both parameters ('id' and 'prerelease') in the schema. The tool description does not add any additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description 'Registration metadata for a package — versions, tags, dependencies, dates' clearly states the tool returns comprehensive metadata for a package, distinguishing it from siblings like 'list_versions' which likely returns only version lists. It uses specific resource terms (package metadata) and implies a retrieval action.

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?

No explicit guidance on when to use this tool vs. alternatives is provided. The phrase 'Registration metadata' implies a comprehensive use case, but there is no 'when to use' or 'when not to use' context. Usage is implied but not directly stated.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds the behavioral nuance that only the most recent released version is returned, which goes beyond the annotations.

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

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

Single sentence, no fluff. Efficiently communicates the core purpose. Could be slightly more informative but remains appropriately concise for a simple tool.

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 an output schema present, return values are covered. The description, schema, and annotations together provide sufficient context for a straightforward 'latest version' retrieval tool, though edge cases are not mentioned.

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

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

Input schema has 100% description coverage, so parameters are well-documented. The description reinforces the meaning (e.g., 'released' implies prerelease default false) but does not add significant new information.

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 'most recent released version of a package', specifying the verb (get), resource (version), and constraint (most recent released), distinguishing from sibling tools like 'list_versions' and 'get_package'.

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?

No explicit guidance on when to use this tool versus alternatives like 'list_versions'. The context of the tool implies usage for retrieving the latest version, but lacks exclusions or conditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return fields and active-only default, complementing annotations.

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

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

Two efficient sentences, front-loaded with key purpose, 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?

Simple tool with one param, no output schema, annotations present. Description fully covers behavior and usage.

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

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

Schema coverage 100%; description does not add meaning beyond schema description for include_inactive. Baseline 3.

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

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

Clear verb 'list' and resource 'subscriptions' with scope 'caller's active'. Distinguishes from siblings like subscribe/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?

Explicitly states when to use: review monitoring before adding more or find id to cancel. No explicit when-not, but clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds no behavioral details beyond 'published versions', which is consistent but not additional transparency.

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

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

Single sentence, no extraneous text. Efficiently conveys the 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 simple tool with one parameter, output schema, and comprehensive annotations, the description is complete. No additional information 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 has 100% description coverage for the single parameter 'id'. The description does not add any meaning beyond the schema's 'Package id'.

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 'All published versions of a package.' clearly states the tool's function (listing versions) and the resource (package). It distinguishes from the sibling 'latest_version' which gets a single 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?

No explicit guidance on when to use this tool versus alternatives like 'get_package' or 'latest_version'. Usage is implied from the description but no context for exclusion or comparison.

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

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

The description discloses that the tool is free, rate-limited to 5 per identifier per day, and that feedback is read daily and affects the roadmap. No annotations contradict this; all annotations are false, and the description adds behavioral context.

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

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

The description is succinct and front-loaded with the purpose. Every sentence adds value, with no redundant or 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?

Given 3 parameters (one nested), no output schema, and the tool's simplicity, the description covers all essential aspects: parameter usage, rate limits, and behavioral notes. Missing confirmation after submission, but not critical for this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by elaborating on the 'type' enum values, giving examples, and providing guidance on the 'message' field (be specific, 1-2 sentences, 2000 chars max). This goes 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: sending feedback about bugs, features, data gaps, or praise. It differentiates itself from sibling tools which are all functional (e.g., search, compare) and not for feedback.

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

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

The description explicitly states when to use the tool: for bugs, feature requests, data gaps, or praise. It also provides guidance on what not to do (don't paste user prompts) and mentions rate limits and quota-free usage.

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

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

Description adds significant context beyond annotations: data derived from CF analytics-engine, no PII, output structure (pack, tool, count), and caching behavior (5min-1h depending on window). 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 concise with 4-5 sentences, front-loaded with purpose, followed by use cases and technical details. Every sentence adds value with no redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully complete: it covers purpose, usage guidance, data source, privacy, caching, and result structure. 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?

The schema already covers the parameter with enum and default. The description adds semantic value by explaining that shorter windows surface hot trends and longer windows show steady-state demand, aiding agent decision-making.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume for a specified window, with a specific verb 'Returns' and resource. It distinguishes from sibling tools like discover_tools by focusing on popularity metrics.

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

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

Three explicit use cases are listed: discovering hot data sources, confirming canonical tools, and aligning use cases with trends. No explicit when-not-to-use or alternatives are mentioned, but the use cases imply appropriate 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds substantial behavioral context: it walks child markets, checks date-axis and threshold-axis ordering, computes partition_check, applies semantic anchor (Jaccard similarity ≥0.30), and filters partitions with placeholders. 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 verbose (multiple paragraphs) but well-structured. It front-loads the requirement and high-level purpose, then dives into details for each mode. Every sentence adds value, but conciseness could be slightly improved without losing clarity.

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

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

Given the tool's complexity (two modes, multiple checks), the description is complete. It covers all necessary aspects: input requirements, mode-specific behavior, constraints (Jaccard similarity, partition filter), and response structure (opportunities array, partition_check). The annotations provide additional context (read-only, idempotent), making the overall picture thorough.

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

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

Schema description coverage is 100% with both parameters described. The description adds further meaning beyond the schema by explaining the specific mode each parameter triggers, providing examples (e.g., 'fed-decision-may-2026'), and detailing the logic behind the 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's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (event and topic) and explains what each does, effectively differentiating from sibling tools like polymarket_edges.

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

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

Explicitly states when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Also warns that 'call with no args fails' and provides examples of inputs. The description implicitly guides the agent away from incorrect usage by highlighting the two mutually exclusive parameters.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds substantial behavioral details: caching at KV level for 1 hour, model calculations, edge computation including slippage, 24h-move warnings, and diagnostic output. 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 extremely detailed (≈350 words) and well-structured, starting with purpose, then model families, output fields, knobs, and caching. However, the verbosity may overwhelm an agent; some model specifics could be moved to external documentation. Score 3 for excessive length despite good structure.

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

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

Given the absence of an output schema, the description fully explains the return structure: by_segment with three segments, fed_candidates, and _diagnostics. It also describes opportunity fields (edge, Kelly, liquidity, spread, volume) and filtering behavior. All 9 parameters are covered. Highly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable extra context beyond the schema, such as how slippage affects edge and Kelly, and practical use cases for knobs like min_liquidity and max_spread_pp. This justifies a 4.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifying it is built for 'what should I bet on today'. It details three distinct model families, making the purpose very specific and distinct from siblings like polymarket_arbitrage.

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

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

The description provides extensive usage context, including when to use (discovery of opportunities), filtering knobs, and behavioral notes (e.g., Fed bets excluded from ranking). However, it does not explicitly contrast with sibling tools or state when not to use, slightly reducing clarity.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safe, non-destructive behavior. The description substantially enhances transparency by detailing safety fields (compatibility_warning, temporal_alignment, skipped counters) and explaining when spreads are meaningful. No contradictions with annotations.

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

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

The description is well-structured with clear sections (MODES, RESPONSE, SAFETY FIELDS) and front-loaded main purpose. However, it is somewhat verbose, especially in the safety fields explanation, which could be more concise without losing essential detail.

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 does a good job explaining the response content (leg prices, matched spreads, safety fields). It covers edge cases and warnings. However, the exact response structure (e.g., JSON keys) is not fully specified, leaving some ambiguity for an AI agent.

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

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

The input schema already has 100% description coverage. The description adds depth by listing all topic shortcut values, explaining how overrides work, and clarifying the relationship between parameters. This goes well beyond the brief schema descriptions.

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

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

The description clearly states the tool computes 'cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies two distinct modes (topic shortcuts and explicit event identifiers), differentiating it from sibling tools like polymarket_arbitrage.

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

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

The description provides explicit usage guidance: when to use topic shortcuts vs. explicit parameters, and warns that most pre-mapped topics return compatibility warnings. However, it does not directly contrast with sibling tools like polymarket_arbitrage for when to use one over the other.

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. Description adds scoping info ('Scoped to your identifier') and explains listing behavior when key omitted. 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, front-loaded with main function, then usage examples, then scoping and pairing. Every sentence adds value.

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

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

For a simple tool with one optional parameter and no output schema, description covers retrieval, listing, scoping, and pairing with remember/forget. 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 covers the single parameter with description. Description reinforces 'omit the key argument' and provides usage examples, adding 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?

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys', using specific verb and resource. Distinguishes from sibling tools 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?

Explicit use case: 'to look up context the agent stored earlier' with concrete examples (ticker, address, notes). Mentions pairing with remember/forget, though no explicit when-not-to-use.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral details: it returns the most recent alerts, explains the effect of mark_read on subsequent calls, and notes the feed is also accessible via a GET endpoint. 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?

Four sentences, no fluff. Each sentence adds distinct value: what it returns, filtering options, mark_read behavior, and alternative access. Front-loaded with the primary 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?

No output schema, but the description covers return fields. Parameters are well-documented in schema. Annotations cover safety. Missing prerequisites (e.g., need to subscribe to the feed first) are not mentioned, but given the context of sibling tools like 'subscribe', it's a minor gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples (e.g., 'sec_8k' for type), clarifying the ISO timestamp format for 'since', and explaining how mark_read works. This goes beyond the schema descriptions.

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

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

The description clearly states it pulls fired events from the subscription feed, specifies what each alert carries (source, citation_uri, raw payload), and uses the specific verb 'Pull'. No sibling tool duplicates this functionality, so it implicitly distinguishes itself.

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 (filtering, polling, alternative access via GET endpoint) but does not explicitly state when not to use this tool or compare it to sibling tools like search. However, it does mention that 'polls work fine' and offers an alternative for scripts/dashboards.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds context about fanning out to multiple APIs, fallbacks, USPTO soft-failure, and return structure (grouped changes, citation URIs). No contradiction.

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

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

Description is packed with necessary details but still compact. Every sentence adds value, though slightly longer than minimal. No redundancy.

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

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

Despite no output schema, description explains return structure (grouped by source with total_changes and URIs). Covers behavior for all parameters and edge cases like fallbacks and soft-failures.

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

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

Schema has 100% coverage with descriptions. Description adds value for 'since' parameter: clarifies ISO vs relative shorthand, gives examples, and recommends '30d' or '1m'. This enhances schema info.

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

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

The description uses specific verbs ('change feed') and explicitly lists the resources (SEC, GDELT/GNews, USPTO). It distinguishes itself from sibling tool 'entity_profile' by contrasting dynamic vs static profiles.

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

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

Provides concrete when-to-use examples (e.g., 'What's new with X') and explicitly directs to use 'entity_profile' for static profiles regardless of window. Also notes fallback behavior for GDELT/GNews and soft-failure for USPTO.

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 provide idempotentHint: true and destructiveHint: false. Description adds valuable context about authenticated vs. anonymous session persistence and scoping, without contradicting 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?

Four sentences, front-loaded with purpose, no redundant information. Each sentence earns its place.

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

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

Covers scoping, persistence, and complementary tools. Does not explain return values, but for a write-only tool without output schema, that is acceptable. Missing explicit mention of overwrite behavior, but overall 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%, so baseline is 3. Description includes examples for key and restates schema for value, adding marginal 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 verb 'Save data' and the resource 'key-value pair'. It distinguishes itself from sibling tools 'recall' and 'forget' by mentioning them explicitly.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and pairs with related tools 'recall' and 'forget'. Also explains scoping by user identifier and session persistence differences.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by revealing internal cascading through multiple endpoints and specifying the return format (ticker, CIK, RxCUI, citation URIs). Could have included more on ambiguous inputs, but still informative.

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

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

Well-structured with front-loaded example queries, type breakdown, and concise bullet-style explanations. Every sentence serves a purpose—no redundancy. Appropriate length for the tool 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 compensates by detailing return values. Covers both entity types, auto-disambiguation, and internal cascading. Missing explicit mention of error handling for ambiguous names, but otherwise highly complete for a lookup tool with strong 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%, but the description adds significant meaning beyond schema descriptions. For each type, it explains accepted input formats (ticker, CIK, name for company; brand/generic for drug), auto-disambiguation, and the exact output fields (ticker, CIK, company name, citation URI). This greatly aids correct parameter usage.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples like 'ticker for...' and 'find the CIK for...'. It verbbly describes the resource (entity identification) and distinguishes from sibling tools by positioning as the go-to for ID resolution.

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 'Use FIRST whenever you have a name but need an ID'. Provides detailed context on supported types and what each returns, with clear guidance on when to use this tool over manual 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?

Beyond annotations (readOnly, idempotent, etc.), description discloses it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, signal density. Adds meaningful behavioral 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 purpose, each sentence earning its place. No wasted words, efficiently communicates function, method, 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?

Description covers high-level behavior and output format. Lacks details on optional parameter usage or edge cases, but schema descriptions handle parameter specifics, making it adequate for a read-only 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 covers 100% of parameters, but description adds value by noting first entity treated as 'subject' and that the tool calls ai_visibility_check, providing context 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?

Description states core function ('Compare AI visibility across multiple entities side-by-side'), identifies specific actions (probes with ai_visibility_check, ranks by score), and distinguishes from sibling tool ai_visibility_check by highlighting batch 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?

Description provides clear context ('competitive AI-marketing audits') and implies when to use via example question. Does not explicitly exclude alternatives or mention when not to use, but context 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?

Annotations already declare readOnly, openWorld, idempotent, and not destructive. The description adds crucial behavioral context: it fans out to two external services, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully and are reported via 'sources_failed'. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and usage, then details return data and limitations. It is somewhat verbose (over 200 words) but every sentence adds value. Could be slightly more concise, but structure is effective.

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

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

Given the tool's complexity (composite, external dependencies, no output schema), the description is thorough: it lists output fields (summary block, per-advisory, links, versions), notes latency and partial failures, and scopes to npm. Minor omission: does not restate idempotence explicitly, but annotations cover it.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds that scoped packages are accepted and version defaults to latest, but this information is already in the schema's description field. No additional parameter meaning beyond what 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 explicitly states it is a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. This clearly identifies the verb ('scan'), resource ('dependency'), and scope ('npm package'), and differentiates it from sibling tools which are unrelated (e.g., bet_research, get_package).

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 provides explicit when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and when not to use ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), along with alternatives for other ecosystems. Also mentions partial failure handling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds no behavioral details beyond the annotations. It does not clarify what constitutes 'full-text search' (e.g., searches name, description, tags?) or any rate limits or result size implications.

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 with no redundant words. It front-loads the core purpose effectively.

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 4 parameters (1 required) and an output schema, the description is minimal but sufficient for a straightforward search operation. However, it could be improved by noting pagination behavior or default result handling, though the schema covers defaults.

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

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

Input schema has 100% coverage with parameter descriptions and examples. The tool description adds no additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Description clearly states 'Full-text search across NuGet packages.' The verb 'search' and resource 'NuGet packages' are specific and differentiate from sibling tools like get_package, list_versions, and scan_dependency, which have narrower scopes.

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

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

No explicit guidance on when to use this versus alternatives. While the purpose implies full-text discovery, the description does not mention that for specific package details other tools (e.g., get_package) should be used, nor does it contrast with other search-like siblings like scan_dependency.

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 BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Adds value beyond annotations (readOnlyHint, idempotentHint) by explaining how the search works.

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

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

Five sentences in a logical order: definition, use case, behavioral details, pairing, and technical specs. No redundant information. Front-loaded with 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?

Despite no output schema, the description specifies return format (passages with offsets and similarity scores), limits (200K chars), and pairing with another tool. Annotations confirm read-only, idempotent. Fully sufficient for effective use.

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

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

Schema covers 100% of parameters. Description adds examples for query (e.g., 'supply-chain risk') and context for text (e.g., 'SEC 10-K body'). While schema explains parameters, the description enriches with real-world 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?

Clearly states tool does semantic search inside a fetched record, with examples (SEC 10-K, article). Distinguishes from sibling 'search' by specifying 'INSIDE a fetched record' and from ask_pipeworx_grounded by pairing.

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

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

Explicitly says use when the record is too large for the prompt, and suggests pairing with ask_pipeworx_grounded for grounding. No confusion about when 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 indicate this is a write (readOnlyHint false), idempotent, non-destructive operation. The description adds behavioral details such as return of subscription id, delivery channel limits (10/day for SMS), webhook HMAC signing, and auto-disable after 10 failures. 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 moderately lengthy but front-loaded with the core purpose and return value. Every sentence contributes meaningful information, though some details about delivery channels could be slightly more compact. Overall, it is well-structured.

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

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

Given the complexity of 3 nested parameters and no output schema, the description covers prerequisites (account requirement), parameter examples, delivery channel behaviors, and error conditions (10/day cap, auto-disable). It is nearly complete, lacking only an explicit description of the response format beyond the subscription id.

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 significantly enriches each parameter by providing concrete examples, format constraints (e.g., E.164 for phone, whsec_ prefix for webhook secret), and usage rules (e.g., phone must be verified at /account). This adds substantial value beyond the schema alone.

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

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

The description clearly uses a specific verb-resource pairing ('Create a proactive monitoring subscription to a live-data event stream') and states the return value ('Returns the new subscription id.'). It distinguishes this tool from siblings such as 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 explicitly states when to use the tool (creating subscriptions), lists required account type ('Requires a Pipeworx OAuth account'), and notes exclusions ('anonymous + BYO cannot persist subscriptions'). It does not name alternative tools for when the user lacks an OAuth account, but provides extensive guidance on supported types and delivery channels.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns example questions and tool shapes, but no further behavioral traits. Does not contradict 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?

Well-structured with trigger phrases first, then return details, then usage instructions. Somewhat long but each sentence adds value. Front-loaded effectively.

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 format (category-bucketed examples with tool shapes). Covers usage, parameters, and context for onboarding. 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 100%, description adds examples of topic values ('finance', 'pharma', etc.) and states 'omit for cross-category spread'. Adds meaning beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes, and lists trigger phrases. It distinguishes itself from siblings as the onboarding entry point for 'what can I ask'.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do'. Provides guidance on omitting topic for full spread or passing a topic to focus. No contrast with siblings but clear context.

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

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

Adds ownership enforcement and deactivation behavior beyond annotations, aligning with destructiveHint=false and providing useful context.

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

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

Two sentences, 34 words, front-loaded, no fluff. Each sentence adds unique 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?

Covers ownership, deactivation, and link to recent_alerts. Lacks return value description but adequate for a simple 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 covers 100% with id description. Description adds ownership context (id must belong to current user), going beyond schema. Baseline 3, plus extra context justifies 4.

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

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

Explicitly states 'Cancel a subscription by id' with clear verb and resource. Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Specifies ownership enforcement and contrasts with deletion by noting deactivation, guiding when to use vs alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: returns a verdict with citation, percent delta, and structured form. It also discloses the limitation (v1 supports only company-financial claims), which goes beyond the annotations.

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

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

The description is concise (6-7 sentences), front-loaded with trigger phrases, and each sentence contributes value: purpose, scope, return details, and efficiency gains. 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 single-parameter tool without output schema, the description covers purpose, input, return verdict types, and scope. It lacks explicit error handling or out-of-scope behavior, but is mostly 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 input schema has 100% coverage with a single parameter description. The tool description enriches this with examples ('Apple's FY2024 revenue...') and clarifies that the claim should be natural language, adding meaning beyond the schema.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources. It lists trigger phrases and distinguishes itself from siblings like 'search' and 'ask_pipeworx' by focusing specifically on factual verification.

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 advises to use this tool 'whenever the agent needs to check whether something a user said is factually correct' and notes it replaces 4-6 sequential calls. It clearly defines the scope (company-financial claims) but does not explicitly state when not to use it or suggest alternatives.

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