Nager Holidays

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about external API calls (consistent with openWorldHint), cost implications for Anthropic probing, and return format. 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?

Four sentences, each adding distinct value: purpose, default/API key usage, return structure, use cases. No fluff, front-loaded with key action verb.

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 (per-model score, confidence, signals, raw_response + combined view). Covers inputs, behavior, and outputs completely for moderate complexity tool.

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

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

Schema coverage is 100%, but description adds significant semantic value: explains default model (Workers AI Llama-3.3-70b free), that _apiKey enables Anthropic probing with BYO key, and entity examples. Enhances understanding 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?

Clearly states the tool probes LLMs for knowledge and scores visibility (0-100) per model. However, does not explicitly differentiate from sibling tool 'scan_competitor_ai_presence', which may have similar 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?

Provides context for when to use (AI-marketing audits, pre-launch, competitive monitoring) and explains default model and API key usage. Lacks explicit when-not-to-use or alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: it routes to the right tool, fills arguments, and returns structured answers with citation URIs. No contradictions with annotations.

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

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

The description is detailed but efficiently packed with essential information, starting with a key preference directive. Every sentence adds value, though minor redundancy exists (e.g., listing many domains could be shortened).

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

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

Given the tool's complexity as a meta-router, the description covers purpose, usage, behavior, and return format (structured answers with citations). No output schema exists, but the description adequately explains what the tool returns.

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

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

Schema coverage is 100% with detailed descriptions of each parameter alias, so the schema already provides full meaning. The main description does not add extra parameter details beyond what the schema offers, so baseline score 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 answers factual questions using authoritative structured data from 3,745 tools across 884 verified sources, providing citations. It explicitly differentiates from web search and gives numerous domain examples, making the purpose highly specific and 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 instructs to prefer this tool over web search for factual queries, lists trigger phrases like 'what is', 'look up', 'find', and provides concrete examples (e.g., 'current US unemployment rate'). It clearly defines when to use without ambiguity.

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

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

Describes the internal behavior: picks the right tool from 3,745 sources, fetches data, extracts answer only from tool result. Explains return structure including 'refusal_reason' with enumerated types. Compatible with annotations (readOnlyHint, idempotentHint); no contradiction.

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

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

Description is thorough but not overly verbose; each sentence serves a purpose. Front-loads key purpose and usage guidance. Slightly long but justified by complexity; could be tightened slightly without losing information.

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

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

Despite lacking an output schema, the description fully explains the return value structure (answer, evidence, confidence, etc.) and refusal reasons. Combined with annotations and sibling info, it provides a complete understanding of tool behavior and constraints.

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

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

Input schema has 100% coverage with description in schema properties. The description adds context about routing ('picks the right tool from 3,745 across 884 sources') but does not materially enhance parameter meaning beyond the schema's alias documentation. 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 specifies the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes itself from 'ask_pipeworx' by emphasizing grounded extraction using only tool results, which differentiates it effectively from its sibling.

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

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

Provides explicit guidance on when to use ('when an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). Includes concrete example contexts (financial verdicts, legal claims) and cost trade-off.

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 cover safety and idempotency; description adds that output includes ISO code and English name, and that it's keyless.

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 concise sentences, each providing essential information without redundancy.

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

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

For a zero-parameter tool, description fully covers output format, usage context, and authentication, 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?

No parameters, baseline score of 4 applies; description does not need to explain parameters.

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

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

The description explicitly states it lists every country with ISO code and English name, and distinguishes from siblings by specifying usage for holiday tools.

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

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

Explicitly says what the tool is used for (getting codes for other holiday tools) and mentions keyless access, but no direct when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: it explains market resolution, classification, parallel fan-out, response shapes, resolver contract, parent event extraction, news fallback handling, low-confidence short-circuiting, closed market handling, wide-spread warnings, and resolution-rule risk parsing. 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 quite lengthy and contains many details. While it is well-structured with headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), it could be more concise by summarizing some of the behavioral details that are better suited for a separate documentation page. However, given the complexity, the verbosity is somewhat justified.

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 classifiers, fan-out, resolution contracts, safety mechanisms) and the absence of an output schema, the description is remarkably complete. It covers response shapes, resolver contract, parent event extractor, news fields, safety, resolution-rule risk, and edge cases (closed markets, wide spreads). 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 description coverage is 100%. The description adds value beyond schema by explaining what market_input can be (slug, URL, question text) with examples, clarifying depth (quick vs thorough), and detailing include_raw (summarized vs full payloads). This enhances understanding of parameter usage.

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

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

The description clearly states that the tool researches a Polymarket bet by pulling Pipeworx data. It specifies multiple input formats (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). This differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges, which have different purposes.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides extensive examples of fan-out for different bet types (BTC, Fed, Hormuz, etc.) and explains when to check resolution confidence or parent event. However, it does not explicitly state when not to use the tool or mention alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotent, but the description adds critical behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URI generation. 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 example queries and packs essential information efficiently. While slightly verbose, every sentence adds value. Minor improvement could be trimming redundant phrasing, but overall concise for the depth provided.

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

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

Despite no output schema, the description explains return payload includes paired data and citation URIs. It covers all relevant aspects: entity types, data sources, constraints (2–5), sorting, and replaces many lookups. Fully complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value beyond the schema by explaining how 'values' should be formatted (tickers/CIKs for company, drug names for drug), constraints (2–5 items), and how 'type' affects the data pulled.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs, using natural language triggers like 'Compare X and Y'. It distinguishes itself from siblings by noting it should be preferred over sequential single-pack lookups, making the purpose unambiguous.

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

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

The description provides clear when-to-use guidance: any comparison query for companies or drugs. It explicitly advises against sequential lookups ('ALWAYS PREFER over sequential single-pack lookups'), making the usage context precise.

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 adds crucial behavioral traits: parallel decomposition, evidence with citations, explicit gaps, pre-verified facts, and expected execution time (15-60s). 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 fairly long but well-structured, starting with the core purpose. Each sentence adds specific information. Could be slightly more concise, but no wasted words.

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

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

For a complex tool with no output schema, the description covers all important aspects: evidence format, citations, gaps, timing, prerequisites. It fully prepares the agent for 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% with both parameters described. The description adds useful context: depth defaults to 'standard', explains the number of facets per depth, and clarifies that the question can be broad. 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 performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to many sources. It distinguishes itself from sibling tools like ask_pipeworx by explicitly noting it handles broad or multi-part 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?

Provides explicit guidance on when to use (broad/multi-part questions) and when not to (use ask_pipeworx for single lookups). Also mentions prerequisites: Pipeworx account and paid plan for thorough depth.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, so the tool is clearly safe and idempotent. The description adds behavioral context: results include 'full input schemas (with curated examples)' and each result is 'ready to call directly, no second schema lookup needed.' This enriches understanding 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 front-loaded with the core purpose and then lists domains and output details. It is informative without being overly verbose, though the list of domains could be slightly condensed. 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 a tool with 6 parameters (only 1 required) and no output schema, the description adequately explains what it does and what it returns. It covers the key behavioral aspects and usage context, though it could mention default limit behavior explicitly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions accepting natural language and gives examples, but does not add significant meaning beyond the schema. It notes multiple aliases, which is helpful but not essential.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains the output (top-N relevant tools with full schemas). This distinguishes it from sibling tools which are specific-purpose tools.

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

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

The description explicitly advises when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear contextual guidance, even if it does not explicitly state when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about fanning out across multiple sources, returning specific fields, the USPTO sunset soft-fail, and the GDELT→GNews fallback. No contradictions. Slightly more detail could be added (e.g., error handling), but it's strong.

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 a clear directive. It is somewhat dense with a run-on sentence structure, but every sentence provides value. Could be more concise, but effectively communicates the tool's capabilities.

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 and lack of output schema, the description covers return fields (filings, fundamentals, patents, news, LEI), data sources, and known limitations (USPTO sunset). It could mention error cases for invalid tickers or rate limits, but overall it is complete for a holistic profile 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 both parameters. The description adds context beyond schema: clarifies that type is only 'company' currently, specifies that value must be ticker or zero-padded CIK, and explicitly says names are not supported with a pointer to resolve_entity. This adds significant 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?

The description clearly states the tool provides a full cross-source profile of a US public company in one parallel call, with example queries and explicit comparison to chaining single-pack lookups. It distinguishes itself from siblings like resolve_entity by specifying input requirements (ticker/CIK vs 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 states when to prefer this tool over alternatives ('ALWAYS PREFER over chaining...') and when to use resolve_entity for names. It also notes the USPTO soft-fail and the required input format, providing clear guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, confirming deletion action. No contradictions; adds value beyond annotation by specifying use case.

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

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

Two concise sentences: first defines purpose, second provides usage guidance and sibling pairing. Zero wasted words.

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

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

For a simple one-parameter delete operation, description covers purpose, usage, and relationships. Missing return value details, but given idempotent and simple nature, it is adequate.

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 'Memory key to delete.' Description reiterates 'by key' but adds no additional syntax or format details. Baseline 3 is appropriate as schema carries full parameter meaning.

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

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

The description clearly states 'Delete a previously stored memory by key,' which combines a specific verb and resource. It differentiates from siblings 'remember' and 'recall' and explicitly pairs with 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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also directs to pair with remember and recall, providing clear context and alternatives.

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

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

Annotations already indicate a safe, read-only operation. The description adds that it fetches the page, extracts title/description/key links, and outputs a standard markdown blob, providing useful behavioral context beyond annotations.

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

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

Two efficient sentences plus a bullet list of use cases. Front-loaded with the main action and output, no unnecessary words.

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

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

Despite no output schema, the description clearly explains the output format (single text blob, standard llms.txt). Combined with annotations covering safety and schema covering inputs, the description is fully adequate for agent invocation.

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

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

Input schema covers both parameters with descriptions (100% coverage). The description adds no additional parameter semantics beyond what the schema 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 generates a production-ready llms.txt file for a URL, specifying the output format and use cases. It does not explicitly distinguish from sibling tools like 'scan_competitor_ai_presence' but the purpose is 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?

Provides clear context with listed use cases (getting a site indexed, drafting for own project, auditing competitor). Does not mention when not to use or alternatives, but the context is sufficient for an agent to decide applicability.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to the caller and lists output fields, offering meaningful 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 purpose, then output, then usage. No unnecessary words.

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

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

Given low complexity, one optional parameter, and rich annotations, description covers purpose, output, and usage completely. 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% and parameter description is sufficient. Description does not add extra semantics beyond the schema, meeting baseline.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies returned fields, and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to call 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, idempotentHint, and no destructiveness. The description adds context about the data source and bridge day feature. No contradictions found.

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

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

Single sentence that is front-loaded with purpose, concise, and wastes no words.

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

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

Simple tool with few parameters and no output schema. Description covers source, what is returned, and key constraint (year range). No missing critical details.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reinforces the year range and country code usage via available_countries, but adds minimal new meaning beyond the schema.

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

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

Description clearly states the tool lists long weekends for a given year and country, specifying multi-day stretches of weekends plus public holidays and bridge day information. It distinguishes from siblings like 'public_holidays' and 'next_holidays' by focusing on multi-day events.

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

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

Description mentions the data source (Nager.Date) and that no API key is needed ('Keyless'), but does not explicitly state when to use this tool versus alternatives or provide any exclusions. However, context is clear enough for typical use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the agent knows the tool is safe and read-only. The description adds value by specifying the data source (Nager.Date) and that it requires no API key, which is 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 concise (two sentences) and front-loaded with the verb 'List', efficiently conveying the action, scope, source, and return details without 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 tool with one parameter and comprehensive annotations covering safety, the description is complete. It enumerates the return fields (date, names, flags, subdivisions, types) despite no output schema, providing sufficient context for selection and 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% for the single parameter 'country_code', with a clear description in the schema. The tool description does not add additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states it lists upcoming public holidays for a country over the next 365 days, specifies the data source (Nager.Date), and details the returned fields (date, local+English name, nationwide flag, subdivisions, types). This distinguishes it from sibling tools like 'public_holidays' and 'long_weekends' which likely have different scopes.

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

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

The description implies usage by mentioning 'upcoming public holidays' and 'Keyless', but does not explicitly state when to use this tool versus siblings like 'public_holidays' or 'long_weekends'. It references 'available_countries' for valid codes, providing indirect context, but lacks explicit when-to-use/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 adds behavioral context beyond annotations: rate limits, daily team review, roadmap impact, and quota-free nature. No contradiction with annotations (all false).

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?

Compact with no wasted sentences. Front-loaded with purpose, followed by usage guidance, then behavioral notes. Every sentence earns its place.

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

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

For a feedback tool with 3 parameters (2 required), nested object, and no output schema, the description covers typical scenarios, constraints, and expected input format completely.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining enum values (type), providing guidelines for message (be specific, 1-2 sentences, 2000 char max), and examples for context fields. However, the schema itself already defines these, so not a 5.

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

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

The description starts with a clear verb 'Tell' and resource 'Pipeworx team' and specifies the types of feedback (broken, missing, needs to exist). It distinguishes itself from sibling tools, which are all data retrieval or analysis tools, by being the only feedback mechanism.

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

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

Explicitly states when to use each feedback type (bug, feature, data_gap, praise) and what not to do (don't paste end-user's prompt). Mentions rate limits (5 per identifier per day), quota-free usage, and the signal's impact on roadmap, providing clear context for usage.

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

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

Adds value beyond annotations by disclosing data source (CF analytics-engine), no PII, and caching details (5min-1h). No contradiction with annotations (readOnlyHint, etc.).

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

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

Three sentences front-loaded with purpose, then use cases, then data/caching info. 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?

Despite no output schema, description explains return values (top tools, packs, count). Single parameter is fully covered. Complete for a simple aggregation tool.

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

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

Schema covers 100% of parameters, and description adds explanatory context for the window parameter (shorter vs. longer windows) that is not in the schema enum description.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a window. Distinguishes from siblings like 'discover_tools' by focusing on trending/popularity rather than generic discovery.

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 three explicit use cases but does not name alternative tools or mention when not to use. Context is clear, but could be improved with direct exclusions.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds significant behavioral context: monotonicity checks, partition_sum, fill check with CLOB depth, realizable vs theoretical edge, and placeholders filter. No contradictions.

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

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

The description is comprehensive but somewhat lengthy. It packs many details into a single paragraph. Structured with internal logic but could benefit from clearer bullet points or sections.

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 details the response structure (opportunities[], partition_check, fill check) and relates to sibling tool polymarket_fill_risk. Covers all necessary context for 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 descriptions for event and topic are present (100% coverage). The tool description adds further meaning: clarifies slug vs seed question, accepts full URLs, and explains mode semantics.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges.

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

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

Explicitly guides when to use each parameter: event for specific markets, topic for cross-event scanning. It also notes that calling with no args fails and provides semantic anchors like Jaccard similarity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral context: caching behavior ('Cached 1h at the KV level'), diagnostic output for empty segments, explanation of Fed bet exclusion, and details on Kelly fractions and slippage. 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 lengthy but front-loaded with the core purpose. It is structured into logical sections (model families, response structure, knobs, diagnostics), with each sentence adding value. While thorough, it could be slightly more concise without losing necessary detail for this complex 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 (9 parameters, three model families, no output schema), the description fully compensates by explaining the response structure (by_segment, diagnostics), caching, and edge cases (Fed bet exclusion). It covers all critical aspects an agent needs to understand 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?

Input schema covers 100% of parameters with descriptions. The description adds meaningful context beyond schema: explains why min_kelly does not filter partition opportunities, provides rationale for slippage defaults, and details tradeable-edge knobs (min_liquidity, max_spread_pp). This enhances the agent's understanding of parameter behavior and selection.

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

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

The description explicitly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It provides a specific verb ('scan'), resource ('Polymarket markets'), and desired output ('opportunities'), distinguishing it from sibling tools like 'polymarket_arbitrage' by focusing on Pipeworx data disagreement and a unique methodology.

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

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

The description positions the tool for discovery ('what should I bet on today') and explains that agents can avoid paging hundreds of markets. It details knobs and filters for tuning. However, it does not explicitly state when not to use this tool versus siblings like 'polymarket_arbitrage', missing an opportunity to provide clearer guidance on 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, openWorld, idempotent, non-destructive. The description adds critical behavioral details: history depth bounded by 60-day snapshot TTL, snapshots written on cache-miss (gaps mean no scan that day), and decay numbers from daily closes not intraday. No contradiction with annotations.

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

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

The description is dense but well-structured, starting with purpose and then detailing response fields and limitations. Every sentence adds value, though it is somewhat verbose. Could be slightly more concise without losing information.

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

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

With no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and their fields. It covers limitations and provides sufficient context for an agent to use the tool correctly. Complete given the tool's complexity.

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

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

Input schema describes both parameters with 100% coverage, so baseline is 3. The description adds value by stating defaults (days=14, window='1wk') and max days=30, and explains that snapshots depend on polymarket_edges runs on cache-miss. This provides meaningful context beyond schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge duration and trend. It distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis rather than raw edge data.

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

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

The description explains when to use the tool: to assess edge longevity and decay, contrasting fresh vs old edges. It implicitly sets expectations but does not explicitly list alternatives or when not to use. The sibling list includes polymarket_edges, which provides the raw data, so context is sufficient but not fully explicit.

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, openWorldHint, and non-destructive. The description adds valuable transparency: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), warns about forced directional risk, and details basket mode behavior. No contradictions. Slightly high verbosity keeps it from a perfect 5.

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

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

The description is lengthy (~350 words) and dense. While informative, it could be more concise or structured with bullet points for modes and return fields. Every sentence is useful, but the density reduces quick readability for 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?

For a complex tool with two modes, 4 parameters, no output schema, and important warnings, the description is thoroughly complete. It covers parameter interactions, defaults, return fields for both modes, and explicitly warns about the dominant loss mode (unhedged directional from partial fills). 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 coverage is 100%, so baselines are met. The description adds context beyond schema: explains side defaults for both modes, defines size_usd differently for single-market (spend/proceeds) vs basket (settlement notional), and clarifies mutual exclusivity of market/event. This enriches understanding without repeating 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 begins with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly stating the verb and resource. It distinguishes single-market and basket modes with explicit details, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk assessment.

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

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

The description explicitly states 'REQUIRES one of `market` or `event`' and advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why—thin books make overround uncapturable and partial baskets create directional risk—providing clear when-to-use and when-not-to-use guidance.

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

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

Goes well beyond readOnlyHint annotations by detailing safety fields: compatibility_warning scenarios, temporal_alignment, skipped_cross counters. Explains exactly when spreads are meaningful and when they are not.

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?

Very dense and well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though length could be trimmed slightly without losing essential information.

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

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

Despite no output schema, description fully documents return fields (leg-by-leg prices, top_spreads_pp, safety fields) and explains their meaning. Covers all aspects needed for correct invocation and interpretation.

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 description adds substantial meaning: explains the two modes, provides examples of topic values, clarifies explicit override behavior, and links parameters to response behavior.

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 calculates cross-venue spreads between Kalshi and Polymarket, explains the two modes (topic shortcuts and explicit tickers), and distinguishes it from siblings like polymarket_arbitrage.

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

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

Explicitly states when to use (comparing same-resolving question across venues) and when not to (compatibility warnings indicate non-tradeable spreads). Provides criteria for meaningful spreads: temporal alignment and matching bet shapes.

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 that it is keyless, sources from Nager.Date, and details returned fields. No contradictions.

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

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

Two sentences, front-loaded with main purpose. Every detail earns its place. No redundancy.

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

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

Given no output schema, description fully explains return values (date, names, nationwide flag, subdivisions, types). Also mentions keyless access. Complete for a read-only list tool.

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

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

Schema covers both parameters with descriptions. Description adds context: 'Use available_countries to list valid codes' for country_code. Baseline 3 for 100% coverage, extra hint raises 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?

Clear verb (list) and resource (public holidays). Specifies inputs (year, country) and outputs (date, names, scope, subdivisions, types). Distinguishes from siblings like available_countries, long_weekends, next_holidays.

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

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

States when to use (list holidays for a given year and country). Includes hint to use available_countries for valid codes. Lacks explicit when-not or alternatives, but sibling names imply other holiday tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. Description adds scoping to identifier (anonymous IP, BYO key, account ID) and clarifies that omitting key lists all saved keys. 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 concise sentences that front-load the core function, use examples, and pair with sibling tools. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (one optional param), annotations, and no output schema, the description fully explains usage, return behavior, scoping, and relationship to siblings. 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 'key' described as 'Memory key to retrieve (omit to list all keys)'. Description restates this but adds no new semantics beyond examples and context. Baseline 3 is appropriate.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. It distinguishes from siblings remember and forget, and provides concrete examples like 'user's target ticker'.

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

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

Explicitly says when to use: 'Use to look up context the agent stored earlier'. Pairs with remember and forget for complete workflow. However, it does not explicitly state when not to use or list alternatives like search tools, leaving some room for ambiguity.

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

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

Description states mark_read:true flags events as read, a side effect that modifies state. This contradicts the readOnlyHint annotation, which implies no write operations. The behavioral disclosure is misleading due to this inconsistency.

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-load purpose and key details, then expand on parameters and alternatives. Efficient but could be slightly more concise; still well-structured.

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

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

Description covers most aspects but the annotation contradiction undermines trust and completeness. Without the contradiction, it would be sufficient given rich schema and annotations.

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

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

Schema coverage is 100%, providing baseline 3. Description adds context beyond schema: type example 'sec_8k', since as ISO timestamp, and explains mark_read behavior (flags events as read). This adds 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?

The description clearly states it pulls fired events from subscription feed and returns recent alerts with source, citation_uri, and payload. It distinguishes from siblings like list_subscriptions which lists subscriptions, not 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?

Description indicates when to use (to get recent alerts) and provides an alternative external URL for scripts/dashboards. It does not explicitly contrast with other tools like ask_pipeworx, 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it fans out to multiple sources (SEC, GDELT/GNews, USPTO), describes fallback behavior (GDELT→GNews, USPTO soft-fails), makes one parallel call, and specifies the output format (changes grouped by source, total_changes count, 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 is fairly long, but every sentence adds value. It is efficient for the amount of information provided, though slightly verbose.

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

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

Given the tool's complexity (multi-source, fallback, soft-fail) and no output schema, the description is complete. It explains source behaviors, output format, and when to use alternatives, fully satisfying the need for contextual 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 all three parameters. The description adds meaning beyond the schema by explaining the 'since' parameter accepts ISO dates or relative shorthand and suggests typical usage, and clarifies that 'value' can be a ticker or CIK.

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 as a change feed for companies, covering news, filings, and patents. It is specific about the verb (fans out), resource (company), and distinguishes from the sibling tool entity_profile by noting that entity_profile is for static profiles.

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

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

The description provides explicit when-to-use guidance with example queries and suggests typical values for the 'since' parameter ('30d' or '1m'). It also gives a clear alternative: 'Use entity_profile instead when you want the static profile', which helps the agent choose the correct 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 provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. Description adds scoping by identifier and retention details (persistent vs 24hr), which goes beyond annotations 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?

Single paragraph with front-loaded main purpose, each sentence adds meaningful information, no wasted words.

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

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

Given no output schema, description covers usage, scope, persistence, and pairing with other tools comprehensively.

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 has 100% coverage with descriptions. Description adds value by suggesting key naming conventions (e.g., 'subject_property') and clarifying value type ('any text').

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, provides concrete examples (resolved ticker, address, preference), and distinguishes itself from sibling tools like recall and forget.

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

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

It explicitly says when to use ('when you discover something worth carrying forward'), pairs with recall/forget, and explains persistence based on authentication status.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds that each call cascades through multiple internal endpoints, replacing 2-3 manual lookups, providing useful behavioral context beyond annotations.

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

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

Description is well-structured with examples and bullet points, but slightly verbose with parenthetical details. Front-loads purpose effectively, though minor trimming could improve conciseness.

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

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

Despite no output schema, description fully explains return values for both entity types. With only 2 params and no nested objects, it provides all necessary context for correct invocation.

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

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

Schema covers both parameters (type, value) with descriptions. Description adds significant meaning by detailing return values for each type (e.g., company returns ticker, CIK, company name, citation URI), enhancing schema info.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples ('What's the ticker for…'). It distinguishes from sibling tools like entity_profile by focusing on identifier 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?

Explicitly advises 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. Supported types are listed with details, though no explicit when-not-to-use is given.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) indicate safety and nondestructive behavior. The description adds specific behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density. No contradictions.

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

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

Two sentences plus a parenthetical example, no filler, efficient and front-loaded with key action and outcome.

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 sufficiently explains the return format ('ranked list with score, confidence, signal density per entity') and the role of the first parameter. Usage context, parameters, and output are all addressed.

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

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

Schema description coverage is 100%, but the description adds meaningful context beyond schema: 'First entry treated as the subject for narrative', explanation of 'models' default and apiKey requirement, and 'context' as shared disambiguation. This helps an agent understand parameter use.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and clearly states the tool compares AI visibility across multiple entities, distinguishing it from sibling tool 'ai_visibility_check' which handles single entities. The use case for competitive AI-marketing audits is explicit.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and implies via sibling context that this tool is for multiple entities while 'ai_visibility_check' is for single. However, it does not explicitly state when not to use this tool or directly name alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as true/true/true/false. Description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, sources_failed list if timeout. No contradiction.

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

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

Description is somewhat long but every sentence is informative. It is well-structured with clear front-loading of purpose, then details on data sources, return values, and edge cases.

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?

Since there is no output schema, the description fully documents return values (summary block fields, per-advisory details, links, alternative versions). Also covers failure behavior and timing.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that package accepts scoped packages, version defaults to latest when omitted, and implies what version does.

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 performs a composite check for npm packages, combining deps.dev and bundlephobia data. It uses specific verbs and resources, and distinguishes from sibling tools like validate_claim.

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 use cases: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also notes ecosystem limitation (NPM only in v1) and directs to deps.dev directly for other ecosystems.

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

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

Discloses implementation details beyond annotations: uses BGE-base-en embeddings, cosine similarity, overlapping 500-char windows, 200K char limit with truncation flag. Annotations already indicate read-only, idempotent, safe; description adds meaningful technical 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?

Description is concise with no extraneous text. Logically structured: upfront purpose, usage context, then technical details and pairing. Every sentence serves a purpose.

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

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

Despite no output schema, the description explains return values (top-N passages with character offsets and similarity scores). It covers behavior (truncation), pairing with other tools, and limitations. Complete for a search tool with high annotation coverage.

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

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

Schema coverage is 100%, but description adds value: clarifies 'text' is the document to search (max chars), gives example queries for 'query', and specifies 'limit' range and default. Each parameter is enhanced with practical usage guidance.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result). It distinguishes itself from sibling tools by mentioning ask_pipeworx_grounded and explaining how it pairs with the gateway tool.

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 the record is too big to cram into the prompt' and explains it saves context. Also provides usage pairing with ask_pipeworx_grounded and warns about truncation for long inputs.

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

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

Annotations already convey readOnly and destructive hints. Description adds behavioral context: returns id, requires OAuth, delivery constraints (10/day cap, phone verification). Does not address idempotency or duplicate subscriptions, which is a minor gap given the idempotentHint annotation.

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: first sentence states purpose and return, then requirements, type examples, delivery details. Every sentence adds value, no filler, appropriately 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?

Complex tool with 3 params (nested, enums) and no output schema. Description covers purpose, prerequisites, type details, delivery options. Lacks error behavior or duplicate handling, but is otherwise thorough.

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

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

Schema coverage is 100%, yet description enriches beyond schema with concrete examples for each type and delivery option, clarifying required vs optional fields and constraints like phone verification and SMS cap.

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

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

Description clearly states it creates a subscription to a live-data event stream and returns the new subscription id. This verb+resource combination distinguishes it from sibling tools like list_subscriptions (list) and unsubscribe (delete).

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 clear prerequisites (Pipeworx OAuth account) and examples for each supported type. However, it does not explicitly contrast with alternatives like list_subscriptions or recent_alerts for when to use them instead, leaving some implicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it returns example questions with exact tool+argument shape from a live catalog, and explains the return structure.

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 packs extensive information without redundancy. It could be slightly more structured (e.g., bulleted categories), but remains efficient and 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?

With no output schema, the description adequately explains the return value (category-bucketed example questions). It covers the optional parameter use case. Minor gaps in edge cases or limitations, but sufficient for a discovery 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 repeats category options and adds minor context (e.g., 'to focus'), but doesn't significantly enhance the schema-provided parameter meaning.

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's an onboarding entry point returning category-bucketed example questions. It uses specific verbs and resources, and distinguishes from siblings by referencing exploring capabilities vs. direct queries.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with or without the topic parameter. No exclusionary language needed.

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 meaningful behavioral context beyond annotations: ownership enforcement, deactivation vs deletion, and preservation of historical events. Annotations already indicate non-destructive and idempotent, and description aligns.

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, no wasted words. Front-loaded with action and key constraint.

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

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

For a simple tool with one required param, annotations, and no output schema, the description covers behavior, ownership, and side effects. 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%, so baseline is 3. The description doesn't add much beyond 'cancel by id', but it implies the id comes from subscribe, which is minor additional 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 clearly states 'Cancel a subscription by id' which is a specific verb+resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It explicitly states ownership enforcement and that deactivation preserves history, providing context on when to use it. It could be more specific about when not to use, but the ownership constraint guides usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations, such as the return format (verdict, structured form, actual value, citation, percent delta) and the fact that it replaces multiple sequential calls. 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 well-structured with front-loaded purpose and examples. It is concise enough while including essential details about supported claim types and return format. Every sentence adds value, though a slightly tighter focus on key points could improve conciseness.

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

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

Given no output schema, the description thoroughly explains what the tool returns: a verdict, structured form, actual value, citation, and percent delta. It also notes the domain limitation (company-financial claims for US public companies). For a single-parameter tool, this provides complete information for an agent to invoke and interpret results.

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 schema coverage at 100% (the parameter 'claim' has a description), the baseline is 3. The tool description adds further value by providing multiple natural-language examples (e.g., "Apple's FY2024 revenue was $400 billion") and explaining how the claim is used, enhancing understanding beyond the schema.

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

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

The description clearly defines the tool's purpose as claim verification/fact-checking with explicit examples and use cases. It distinguishes itself from siblings like 'bet_research' or 'compare_entities' by focusing on factual checking of statements, including mention that 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 states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides domain constraints: 'v1 supports company-financial claims...' This gives clear guidance on when to use the tool and the scope of supported claims, though it does not explicitly list alternative tools for other domains.

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