Licenses

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context about free default model, BYO key for Anthropic, and per-model return structure, which is valuable 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?

Two sentences concisely convey purpose, usage, parameters, output, and use cases. No redundant information; every phrase 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?

Despite no output schema, the description fully explains return values (per-model {score, confidence, signals, raw_response} + combined view). All parameters are covered, and the tool's behavior is transparent for a probe tool.

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

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

Schema description coverage is 100% with all parameters described. The description adds clarity on the default model, the role of _apiKey (BYO key, direct payment to Anthropic), and the context parameter's disambiguation purpose.

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

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

The description uses specific verb 'probe' and resource 'LLMs', clearly states the output (visibility score 0-100 per model), and distinguishes its scope (business/brand/product/topic) from siblings like 'scan_competitor_ai_presence' which is more focused on competitors.

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 cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional _apiKey parameter. However, it does not contrast with sibling tools or 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds valuable context: it returns structured answers with citations and routes to many tools. It does not contradict annotations and provides a clear picture of behavior.

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

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

The description is detailed but well-structured, with front-loaded key guidance and examples. Every sentence adds value, though it could be slightly more concise without losing substance.

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, no output schema, and many siblings, the description covers expected behavior, usage context, and alternatives well. It lacks detailed output format, but mentions structured answers with citations, which is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description explains the 'question' parameter and its aliases but does not add significant new meaning beyond the schema description. The examples in the schema provide usage context.

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

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

The description specifies the tool routes questions to over 4,800 verified sources and returns structured answers with citations. It clearly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research by stating specific 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 states when to prefer this tool ('START HERE for most questions'), provides detailed examples, and instructs when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad queries). This is exemplary guidance.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description details the internal routing process, return format with success/refusal cases, and specific refusal reasons. 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?

Four well-structured sentences that front-load the key phrase 'Hallucination-resistant answer mode' and efficiently cover purpose, process, return format, use cases, and cost trade-off. No wasted words.

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

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

Despite no output schema and high complexity (6 aliased params, many siblings), the description fully explains internal behavior, return format with examples, and cost trade-off, making it complete for high-stakes 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 description coverage is 100% with clear aliases. The description does not add extra meaning beyond stating it accepts natural language, which is already evident from the schema. Thus 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and specifies that it extracts the answer using only the tool result. It distinguishes itself from the sibling ask_pipeworx by noting the extra LLM call and specific 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 tells when to use ('whenever an answer will be quoted, cited, or acted on') with examples (financial verdicts, legal claims, medical lookups) and when to avoid ('prefer ask_pipeworx for casual 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?

Disclosures are extensive: market resolution, classification, parallel fan-out, response shapes with field details, resolver contract (match confidence, alternatives), parent event extraction, news fallback handling, safety short-circuits, wide-spread warnings, and resolution-rule risk. No contradiction with annotations (readOnly, idempotent, non-destructive).

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 section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded purpose. However, length is substantial; some detail could be trimmed without loss. Earns its place but not maximally 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?

Given no output schema and high complexity (3 params, multiple behaviors, edge cases), the description covers all necessary aspects: input types, fan-out logic per category, response fields, safety mechanisms, market state handling, and resolution risk. 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?

Schema covers 100% of parameters with descriptions. Description adds examples (slug, URL, question text for 'market'), enumeration for 'depth' (quick/thorough with effect), and behavior for 'include_raw' (summary vs full payloads). All meaningfully extend 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' with clear input types and output summary. It distinguishes itself from siblings by focusing on single-bet research with extensive fan-out, setting a specific verb+resource+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?

Provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and examples. Lacks explicit when-not-to-use or sibling comparisons, but 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics (revenue, net income, etc.), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example queries and structured into usage triggers, per-type behavior, and return info. It is informative without being verbose, though 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?

The tool has no output schema, so the description should fully explain return values. While it mentions paired data and citation URIs, it lacks specifics on the output format, exact sorting metric for each type, and error handling. This is a meaningful gap in completeness.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds concrete examples (tickers for company, drug names) and clarifies the expected format, providing additional 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: side-by-side comparison of 2-5 companies or drugs. It uses specific verb-resource ('compare entities') and distinguishes from siblings by explicitly preferring this tool 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?

The description provides explicit usage context: it should be used when users request comparisons ('Compare X and Y', 'rank these companies') and explicitly advises to prefer it over sequential lookups. It also explains when not to use 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 safety (readOnly, idempotent, non-destructive) and open-world hint. The description adds significant behavioral context: expected response time, returns gaps for unanswered facets, and notes that breaking news topics lead to empty results.

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 long but well-structured, front-loading critical prerequisites (account, alternatives) and using bullet-style points. Every sentence provides useful information, earning 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 tool's complexity—multi-source research, parallel tool routing, output with citations and gaps—the description is comprehensive, covering behavior, limitations, and prerequisites. No output schema exists, so the description fully compensates.

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 value by explaining the depth parameter's meaning (number of facets) and that the question should be natural language and multi-part. This goes beyond the schema definitions.

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: grounded multi-source research across structured data sources. It uses specific verbs and resources, and distinguishes from siblings like ask_pipeworx.

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

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

The description explicitly provides when-to-use and when-not-to-use guidance, including alternatives like ask_pipeworx for single lookups or breaking news. It also mentions account requirements.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond by explaining what the tool 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.' This adds valuable 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 concise and front-loaded: first sentence states purpose, then usage context, then return details. Every sentence adds value, with no redundancy or waste. At ~100 words, it is appropriately sized.

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 fully explains the return value: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It also addresses when to call the tool ('FIRST'). Given the tool's complexity (6 params, 1 required), this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema for parameters; it mentions 'query' implicitly but does not explain aliases (q, task, search, description) beyond what the schema provides. The examples in the input schema provide some context, but the description itself does not compensate.

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 uses a specific verb ('find'/'discover') and resource ('tools'). It also distinguishes from siblings by emphasizing that it returns full input schemas with curated examples, unlike other search or lookup 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 tells when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It also implies when not to use it (not for a single answer) by contrasting with other tools.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, GDELT, GLEIF), notes a sunset for patents ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), explains fallback mechanisms ('GDELT→GNews fallback'), and details the return structure. 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 relatively long but front-loaded with example queries, making it easy to grasp the tool's purpose quickly. Every subsequent sentence adds value (data sources, return fields, fallbacks). Could be slightly trimmed, but overall efficient for the complexity of the 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?

Given the tool's complexity (multiple data sources, fallbacks, and no output schema), the description thoroughly explains what is returned: cik, company_name, filings with URIs, fundamentals with sorting, patents status, news fallback, LEI. It also handles edge cases (names not supported, patent sunset). All necessary context 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 coverage is 100% (both parameters described in schema). The description reinforces and extends schema info: it clarifies that 'value' can be a ticker or zero-padded CIK, provides examples ('AAPL', '0000320193'), and mentions that names are not supported. This adds meaningful guidance beyond the schema entries.

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 'full cross-source profile of a US public company in ONE parallel call' and lists diverse example queries ('tell me about X', 'research Acme', etc.), along with a detailed breakdown of returned data. It distinguishes itself from sibling tools like 'resolve_entity' by explicitly stating that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides an exclusion: 'names not supported (use resolve_entity first if you only have a name).' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, which align with the description's 'Delete' verb. The description adds value by noting use cases like clearing sensitive data, 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?

Two sentences: first states purpose, second gives usage guidelines. No fluff, front-loaded with the core action, and 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 1-parameter tool, the description is complete. It explains when to use and pairing with siblings. No output schema exists, but return values are likely straightforward.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The tool description does not add 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?

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It also distinguishes from sibling tools like 'remember' and 'recall' by mentioning them.

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

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

The description provides explicit contexts for when to use the tool (stale context, task done, clear sensitive data) and mentions pairing with remember and recall. It lacks explicit when-not-to-use scenarios but 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 indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds process details (fetches page, extracts info, emits markdown), which complements the annotations without contradiction. The description provides useful behavioral context beyond the annotations.

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

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

The description is two sentences plus a bullet list, efficiently conveying purpose and use cases. It is front-loaded with the main action. There is no superfluous content, though 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?

Given the simplicity of the tool (no output schema, two parameters fully covered), the description adequately covers purpose, process, output format, and use cases. It does not mention error handling or rate limits, but the annotations provide safety context. The description is complete enough 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%, so the schema already documents both parameters (url, max_links). The description mentions 'fetches the page' (url) but adds no additional semantics beyond schema descriptions. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying actions (fetch, extract, emit) and use cases. It distinguishes itself from siblings through its specific output format and purpose, though explicit differentiation is not provided.

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

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

The description lists three explicit use cases (client indexing, drafting, auditing), providing clear context for when to use the tool. However, it does not mention when not to use it or specify alternatives from the sibling list.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds 'Keyless', indicating no authentication needed, which is a behavioral trait. It does not contradict annotations. The description adds value 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 two sentences, no wasted words. It front-loads the key action ('Fetch the full license text') and provides an example. Every word earns its place.

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

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

For a simple tool with one parameter and rich annotations, the description is sufficient. It explains what the tool retrieves and the input. No output schema exists, but the return (full license text) is implied. Minor gap: does not mention what happens if the ID is invalid.

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

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

Schema coverage is 100% with one parameter spdx_id described as 'An SPDX license id.' The description adds an example 'MIT', which provides concrete context. Since schema already covers the parameter well, the description's example raises the 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 'Fetch the full license text for an SPDX id', specifying the verb (Fetch), resource (license text), and input (SPDX id). It also provides an example 'MIT' for clarity. This effectively distinguishes it from sibling tools like search_licenses which search, and lookup_license which may have different purpose.

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

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

The description implies when to use: when you need the full text for a known SPDX ID. However, it does not explicitly state when not to use it or compare with alternatives like search_licenses or lookup_license. The phrase 'Keyless' hints at no auth requirement, but usage guidance is minimal.

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, destructiveHint. Description adds that it returns specific fields and is caller-specific, but doesn't add significant behavioral context beyond annotations.

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

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

Two sentences, front-loaded with action and key details. Efficient 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?

Lists returned fields, covers usage context, and tool is simple with one optional parameter. No output schema but description compensates. Lacks mention of pagination but likely not 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% with description for include_inactive. Description does not add meaning beyond schema; baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' and specifies returned fields. Distinguishes from sibling tools like subscribe/unsubscribe by indicating usage for review or finding id to cancel.

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: 'to review what you're monitoring before adding more or to find an id to cancel.' Implies reading vs writing, though doesn't name alternative tool explicitly.

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 'Keyless' (no auth needed) and specifies return fields (full name, OSI/FSF approval, deprecation status, URLs). No contradictions; adds useful context beyond annotations.

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

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

Two sentences with no filler. Front-loaded with purpose and key constraint (exact SPDX id). Every word earns its place.

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

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

For a tool with one simple parameter and no output schema, the description fully explains input (exact id) and output (specific fields). No missing information 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 describes spdx_id as 'An SPDX license id'. Description adds value by emphasizing 'exact' and providing multiple examples ('MIT', 'Apache-2.0', etc.), clarifying the requirement for precision. Since schema coverage is 100%, baseline is 3; description elevates to 4.

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

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

Clearly states the verb 'look up' and resource 'open-source license' with the specific method 'by its exact SPDX id'. Provides examples of valid IDs. Distinguishes itself from sibling tools like 'search_licenses' and 'get_license_text' by focusing on exact lookup.

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

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

Mentions 'Keyless' indicating no authentication needed, and implies exact ID requirement. While it doesn't explicitly list alternatives, the context of 'exact' ID suggests using 'search_licenses' if uncertain. Lacks explicit when-not-to-use guidance.

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

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

The description discloses important behavioral traits beyond annotations: rate limit of 5 per identifier per day, that it's free and doesn't count against quota, and that the team reads digests daily. Annotations are all false, so no contradiction; description compensates fully.

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

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

The description is concise (two sentences plus a brief note) and front-loads the core action ('Tell the Pipeworx team...'). Every sentence provides essential guidance without redundancy, making it efficient for an 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?

Despite lacking an output schema, the description fully covers what the agent needs: how to use it, constraints (rate limit, free), and context for the feedback. It is complete for a simple feedback tool with three parameters.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the meaning of each type enum value and provides guidance on writing the message (be specific, 1-2 sentences, 2000 chars max). This goes beyond the raw schema to improve 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's purpose: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools by being the only feedback channel, making its purpose unambiguous.

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

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

The description explicitly specifies when to use the tool (bug, feature, data_gap, praise, other) and provides clear guidance on what to describe in terms of Pipeworx tools/packs, and what to avoid (pasting end-user prompt). This helps the agent choose this tool over others.

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 explaining the data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating nature. 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 efficient sentences with no fluff. Purpose front-loaded, followed by usage and context. Every sentence earns its place.

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

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

Given the low complexity (single optional parameter, no output schema), the description provides complete context: return items, data source, caching, and use cases. 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 one parameter that has enum and description. The description adds nuance about window choices (default 24h, trade-off between hot trends and steady-state demand), going beyond schema details.

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, packs, and call volume over a time window, with a specific verb 'returns' and resource 'Pipeworx trending data'. It distinguishes from siblings by focusing on aggregate usage trends rather than answering questions.

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

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

Three concrete use cases are listed (discovering hot sources, confirming canonical tools, aligning use case). While it lacks explicit when-not-to-use or direct comparisons to alternatives, the context is clear and helpful.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral context: internal algorithms (partition-sum checks, monotonicity violations, Jaccard similarity), partition filtering of placeholders, fill checks against live order book, and conditions that void trades. 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 detailed yet efficient. First sentence summarizes purpose, then clearly structures information with sections for modes, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK. Every sentence provides necessary detail 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 fully explains the response format (opportunities array, partition_check object). It covers the tool's complexity including multiple modes, filters, and fill verification. All necessary information for correct usage 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 coverage is 100% with parameter descriptions. Description adds far more: explains the behavior of each parameter with examples (slug vs topic), details the algorithms used per mode, and provides guidance on usage. The schema's short descriptions are fully elaborated.

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: finding arbitrage opportunities via monotonicity violations and partition-sum checks on Polymarket. It distinguishes between trending_scan (no args), event mode, and topic mode, and differentiates from sibling tools by specifying its unique function.

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

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

Explicitly tells when to use each mode: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' Recommends event mode for specific markets and explains when not to trade based on fill check results. References sibling tool polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses internal behavior, including the three model families, edge calculation, response structure (by_segment, fed_candidates, diagnostics), caching policy, and parameter knobs. This adds significant context beyond the annotations, which already mark the tool as read-only and idempotent. No contradictions with annotations are present.

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 and numbered lists, but it is excessively verbose, containing detailed mathematical explanations (e.g., '90d FRED log-returns', 'halved Kelly') that may not be necessary for an AI agent. While front-loaded with purpose, the length reduces conciseness.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is highly complete. It covers the response structure, diagnostic fields, caching, and even explains why certain opportunities are excluded (e.g., Fed bets). The agent has sufficient information to understand all aspects of tool behavior and output.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add some contextual meaning for parameters like 'min_partition_leg_kelly' by explaining its role in partitions, but it largely echoes the schema's own descriptions. Overall, the description provides limited additional value beyond what the schema already offers.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs ('scan', 'return'), identifies the resource ('Polymarket markets'), and defines the scope ('disagreements'). This distinctly separates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which focus on different aspects.

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 the use case 'what should I bet on today' and mentions that it avoids paging through hundreds of markets. It also notes that Fed bets are excluded from ranking and included in separate fields, indicating when the tool might not provide full coverage. However, it does not explicitly contrast with sibling tools or 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 already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds rich detail: it explains that snapshots are written on cache-miss, leading to gaps, and describes the response structure (tracked, expired, snapshot_dates) and edge_pp_net signing. 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 relatively long but efficiently structured: it opens with the core question, then details arguments, response fields, and limitations. Every sentence adds useful information, though some redundancy exists (e.g., 'decay_pp_per_day' description is a bit verbose). Front-loading 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 thoroughly documents the response structure (tracked array with full time-series, trend, decay; expired array with lifespan; snapshot_dates). It explains derived fields, edge_pp_net signing, and system limitations (TTL, snapshot enablement start). Highly complete for a telemetry 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?

Input schema covers 100% of parameters with descriptions. The tool description adds context beyond schema: it specifies default values (days=14, window='1wk'), maximums (days max 30), and explains the meaning of days as lookback and window as snapshot family, adding significant semantic value.

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

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

Description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering the specific question of how long an edge has existed and if it is shrinking. It distinguishes itself from sibling tool polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description implies usage when needing historical edge decay analysis, and mentions limitations (60-day TTL, snapshot gaps). While it does not explicitly list alternatives or when-not-to-use, the context of sibling tools (e.g., polymarket_edges for current edges) makes the use case clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral details like 'walks the ladder', returns verdicts (clean|degraded|cannot_fill), and identifies forced_directional_risk. This goes beyond annotations but could be more concise.

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

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

The description is dense but well-structured, with clear separation of modes and explicit formatting. It front-loads the requirement for either market or event. While lengthy, each sentence serves a purpose; slight trimming possible but appropriate for 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 exists, yet the description comprehensively lists all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc., and basket-specific fields like thin_legs, forced_directional_risk). It also warns about the dominant loss mode (partial basket fills converting arb into unhedged position), making it fully contextual.

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

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

Input schema has 100% coverage, but the description adds context: size_usd interpreted differently for buys (spend) vs sells (target proceeds) and basket mode (settlement notional). It also explains the default side for basket mode (auto from partition sum). This adds 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?

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth', with two distinct modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on risk assessment before execution.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', explaining why (theoretical overround not capturable on thin books, partial basket fills cause directional risk). Also clarifies conditions for single-market vs basket mode.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds significant behavioral context: compatibility_warning conditions, temporal_alignment field, skipped_cross_type counters, and non-equivalent bet shapes. It discloses exactly what happens when matches fail and why, going well 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 relatively long but every sentence adds value. It is well-structured: purpose first, then modes, response format, safety fields. Could be slightly more concise but no redundant content. Front-loads the most important information.

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

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

Given the complexity of cross-venue spread matching and no output schema, the description is remarkably complete. It explains response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and caveats. Covers all critical aspects for correct agent 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 is 100%, but the description adds meaningful context: explains the two modes interacting with parameters, provides examples, and cautions about pre-mapped topic limitations. This adds semantic value beyond the schema's property 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 purpose: compute cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses a specific verb ('cross-venue spread') and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on this specific pair. No ambiguity.

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 explains two modes—pre-mapped topic shortcuts and explicit tickers—and warns that most pre-mapped topics currently return compatibility warnings. It provides context on when each mode is appropriate but does not explicitly contrast with other sibling tools or state when not to use it. Still, the guidance is clear and practical.

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 scoping detail (anonymous IP, BYO key hash, account ID) and the dual behavior (retrieve vs list all keys). 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?

Three sentences, each essential: first defines core function, second provides usage examples and scoping, third indicates pairing. No redundant 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 retrieval tool with one optional parameter and no output schema, the description covers behavior, scoping, and usage context completely. All necessary information 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 already provides 100% coverage with a clear description for the single optional 'key' parameter. Description reinforces the schema but adds no new semantic info beyond what's structurally present. Baseline 3.

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

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

Clearly states verb (retrieve/list) and resource (saved values). Distinguishes from siblings remember and forget by naming them and describing pairing.

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

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

Provides explicit when-to-use context: look up previously stored context without re-deriving. Implicitly indicates when-not (use remember to save, forget to delete) and names 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 readOnly, idempotent, non-destructive. The description adds useful context: returned fields (source, citation_uri, raw payload), filtering, and the mark_read behavior that affects future calls. It also notes polling suitability and an alternative access method, enriching the agent's understanding.

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

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

Three sentences, each serving a distinct purpose: stating the action, describing returned data and filtering, and explaining mark_read and polling. No fluff, front-loaded with the key purpose. Highly 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?

With 5 optional parameters and no output schema, the description covers return fields (source, citation_uri, raw payload), filtering, mark_read effect, and alternative access. It lacks details on the interaction between mark_read and unread_only, and the exact behavior of limit. Still, it provides adequate context for a read-retrieval 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 provides additional context for parameters 'type' (example) and 'since' (ISO timestamp) and explains the effect of 'mark_read'. It does not elaborate on 'limit' or 'unread_only', but the schema already describes them adequately.

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 'Pull fired events from your subscription feed,' which is a specific verb+resource. It distinguishes from siblings like subscribe, list_subscriptions, and recall by focusing on retrieving recent alerts from the subscription 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 implies when to use (retrieve recent alerts) but does not explicitly exclude alternative tools or provide guidance on when not to use. It mentions an alternative HTTP endpoint but no sibling tool alternatives. This is acceptable but not exemplary.

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, openWorldHint, idempotentHint. Description adds valuable context: parallel fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback logic, soft-fail condition, and return format (changes[] grouped by source + total_changes + citation URIs), 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?

Front-loaded with example queries, the description is efficient though slightly dense; every sentence adds value, but minor redundancy (e.g., repeating 'company' examples) could be tightened.

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 (multi-source, fallback, soft-fail) and absence of output schema, the description adequately covers return format and all key behaviors, leaving no critical 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?

With 100% schema description coverage, the description still adds value by detailing 'since' parameter formats (ISO date or relative shorthand like '7d', '30d') and 'value' parameter acceptance of ticker or CIK, enhancing usability 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 explicitly states it's a 'change feed for a company' with example queries like 'What's new with X' and distinguishes from sibling 'entity_profile' by directing users to use that tool for static profiles, providing clear 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?

It provides concrete usage examples, specifies when to use alternative tool (entity_profile for static profiles), advises on 'since' parameter defaults ('30d' for monitoring), and explains fallback behavior (GDELT→GNews) and soft-fail for patents.

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 include idempotentHint: true and destructiveHint: false. The description adds valuable behavioral context: key-value pair storage, scoping by identifier, persistence for 24h for anonymous sessions, and authentication-based persistence. This goes beyond the annotations to explain what happens to the stored data.

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

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

The description is a single paragraph that is informative but somewhat dense. It covers all necessary points without redundancy, though it could be slightly more concise. The key information (purpose, usage, behavior) is front-loaded.

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

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

Given the simple tool (2 parameters, no output schema), the description is complete. It explains what the tool does, when to use it, how it behaves, and how it relates to sibling tools. No gaps remain.

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

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

Schema coverage is 100% with descriptions for both key and value. The description adds example usage patterns (e.g., 'subject_property', 'target_ticker') but does not add meaningfully new information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse across conversations or sessions, with specific examples like 'resolved ticker, target address, user preference'. It also distinguishes from sibling tools like recall and forget by mentioning them as complementary actions.

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 you discover something worth carrying forward'. Also gives context for when not to use by pairing with recall and forget, and mentions scoping and persistence differences for authenticated vs anonymous users.

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 significant context: it details the internal cascading lookups and the exact citation URIs returned, 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 a single well-structured paragraph, front-loaded with the core purpose. Every sentence adds essential information without redundancy. It is concise yet comprehensive.

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

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

Despite lacking an output schema, the description fully explains the return values for each entity type, including specific fields and citation URIs. It also clarifies the internal process, making the tool's behavior entirely transparent.

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

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

Schema coverage is 100%, but the description enriches the meaning with examples (e.g., ticker 'AAPL', CIK '0000320193'), explains auto-disambiguation for company, and lists supported input formats. It 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 resolves names to canonical identifiers, with specific examples and supported entity types. It distinguishes itself from siblings by being the 'first' tool to use when needing an ID from a name.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to use it. However, it does not explicitly mention when not to use it or list alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density, adding behavioral context without contradiction.

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

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

Three sentences, each earning its place: purpose, process, and example use case. Front-loaded with main action. 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?

Covers purpose, process, output format, and typical use. No output schema but describes return fields. Lacks mention of constraints like entity uniqueness or error handling, but adequate for a read-only competitive audit 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% and descriptions are sufficient. Description adds that the first entity is treated as the 'subject', but this is minor. Baseline 3 is appropriate as the description adds limited additional 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 compares AI visibility across multiple entities side-by-side, using the verb 'probes' and ranking by score. It distinguishes from sibling tool ai_visibility_check by focusing on multiple entities.

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

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

Provides explicit use case for competitive AI-marketing audits and implies when to use (multiple entities) vs. single-entity check via sibling. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already mark it as readOnly, idempotent, not destructive. The description adds critical behavioral context: it fans out across two services, can take 5-30s for first bundlephobia measurement, and handles partial failures gracefully with a list of failed sources. 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 front-loaded with the core purpose and provides detailed behavioral information. While relatively long, every sentence adds value. Slightly verbose but efficient for the complexity of the 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?

Given the tool's complexity (composite call, multiple data sources, partial failures, rich output), the description is thorough. It lists the return structure (summary block, per-advisory details, links, recent alternative versions) and explains edge cases (timing, graceful degradation), making it 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 schema already documents both parameters. The description reiterates that 'package' is an npm package name and that 'version' defaults to latest, but does not add significant new semantic 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 composite purpose: a single call combining deps.dev and bundlephobia to evaluate an npm package. It distinguishes itself from siblings by targeting npm and aggregating multiple data sources.

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 provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also specifies ecosystem limitations (NPM only, other ecosystems under deps.dev:version directly) and explains graceful degradation on partial failures.

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 the behavioral note 'Keyless' (no authentication required) which goes beyond annotations. However, it does not describe rate limits, pagination behavior, or the exact return format.

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 sentence with examples, front-loading the core purpose. No extraneous information. Every word serves a purpose, and the structure is optimal for quick scanning by an AI agent.

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

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

Given the tool's simplicity and full parameter documentation, the description covers the key aspects: search target, matching behavior, and authentication requirement. It could mention that results are a list of licenses but is still sufficient. No output schema exists, so the return format is not detailed, but this is acceptable for a search tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by specifying that the query matches both 'id or name', which is not in the schema. It also provides examples. This enriches the semantic understanding 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 searches the SPDX license list by keyword matching id or name, with concrete examples like 'GPL', 'creative commons', 'mozilla'. This is a specific verb-resource-action pair that distinguishes it from siblings like 'lookup_license' or 'get_license_text' which suggest direct lookups or full text retrieval.

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

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

The description implies usage when searching with a keyword but does not explicitly differentiate from siblings. It fails to state when not to use it (e.g., when exact license ID is known, prefer 'lookup_license') or provide alternative tool names. Usage context is only implied via examples.

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 profile (read-only, idempotent). Description adds rich behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and output includes offsets and scores. No contradictions.

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

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

Single paragraph well-structured: first sentence states core action, second explains use case, third provides technical details. Every sentence adds unique value, no filler.

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

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

Despite no output schema, description explains return format (top-N passages with offsets and scores) and covers limitations (200K char cap, truncation flag). Complete for a search tool with 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?

Schema covers all three parameters with descriptions (100% coverage). Description adds value by giving concrete query examples and elaborating on limit's default and range, exceeding 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?

Clearly states tool does semantic search inside a fetched record, returning passages with offsets and scores. Explicitly differentiates from sibling ask_pipeworx_grounded by describing their 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 describes when to use: when record is too large for prompt. Mentions pairing with ask_pipeworx_grounded for grounding. Does not explicitly state when not to use, but context is clear.

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

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

Adds extensive behavioral details beyond annotations: returns id, delivery channels, email/sms/webhook specifics, rate limits (10/day SMS), webhook auto-disable, signing secret returned once. 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?

Well-structured with front-loaded purpose and nested examples. Slightly long but all content is relevant.

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?

Comprehensive given no output schema: explains return value, all types, delivery channels, constraints, and edge cases like webhook validation.

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 significant meaning beyond schema with examples and requirements for each type and delivery option, e.g., 'phone must be verified' and 'sponsor or condition required'.

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

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

Clearly states the action (Create) and resource (proactive monitoring subscription). Distinguishes from siblings like list_subscriptions and unsubscribe. Provides examples of supported 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 requires Pipeworx OAuth account, excluding anonymous/BYO users. Describes context for different subscription types but does not fully compare with alternatives like list_subscriptions for viewing existing subscriptions.

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. The description adds behavioral context: it returns example questions drawn from a live catalog, with exact tool and argument shapes. No contradictions.

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

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

Description is somewhat lengthy but well-organized, front-loaded with key phrases, and every sentence adds value. Could be slightly more concise, but overall efficient.

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

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

For an onboarding tool with a simple schema and no output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shapes) and purpose. It covers what an 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 has 1 optional parameter with 100% coverage. Description adds significant meaning: explains that omitting topic gives full spread, passing one focuses, and lists valid values (finance, pharma, etc.). Adds 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?

The description clearly states it is the onboarding entry point for an agent, returning category-bucketed example questions. It uses specific verbs like 'returns' and 'draw' and distinguishes itself from sibling tools by specifying when to use it first.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions meta-tools like ask_pipeworx. However, it does not explicitly state when not to use it or provide exclusion criteria.

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

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

Annotations indicate non-read-only, idempotent, non-destructive behavior. The description adds significant context: ownership enforcement, deactivation instead of deletion, and historical event availability. 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?

Two sentences efficiently convey the action, constraints, and behavior. No extraneous words; front-loaded with the main purpose.

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

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

For a simple one-parameter tool without output schema, the description covers the core behavior. Could optionally mention return value or error handling, but completeness is adequate given low 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 a clear description of the 'id' parameter. The description does not add additional parameter details beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly specifies the action ('Cancel a subscription by id'), the resource (subscription), and adds context about ownership enforcement and deactivation behavior, distinguishing it from sibling tools like subscribe, list_subscriptions, and recent_alerts.

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

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

The description implicitly distinguishes from siblings (subscribe creates, recent_alerts views history) but lacks explicit guidance on when not to use this tool or alternatives. Ownership enforcement is mentioned, which provides usage context.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable context: returns verdict types, structured form, actual value with citation, and percent delta, 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 well-structured, starting with key phrases in quotes and then expanding. It efficiently covers purpose, scope, and output, but is slightly lengthy. Still, every sentence adds value.

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

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

Given the tool's single parameter and no output schema, the description is complete. It explains the domain, verdict types, and output details (citation, delta). It doesn't cover error handling or all edge cases, but is sufficient 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 has 100% description coverage for the sole parameter 'claim'. The description does not add new information about the parameter 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?

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It provides usage examples and distinguishes from siblings by noting it replaces multiple sequential calls.

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 when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It scopes the domain to company-financial claims via SEC EDGAR + XBRL, implying when not to use, though it doesn't explicitly state exclusions.

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