Data Reunion

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: default model, requirement of '_apiKey' for Anthropic, and return structure. No contradictions.

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

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

The description is a single paragraph, front-loaded with purpose, then details. Every sentence adds value: usage context, parameter notes, return format. 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?

Given no output schema, the description adequately explains return format (per-model {score, confidence, signals, raw_response} + combined view). It covers all parameters and use cases. The tool's complexity is well-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 has 100% description coverage, but the description adds meaning: explains default model, optional API key purpose, and context usage for disambiguation. This goes beyond the schema's basic descriptions.

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

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

The description uses a specific verb ('probe') and noun ('LLMs for what they know about a business / brand / product / topic'), and explicitly differentiates itself from sibling tools like 'ask_pipeworx' and 'entity_profile' by focusing on multi-model visibility scoring.

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 clearly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. While it doesn't explicitly mention when not to use, the context and siblings provide sufficient guidance for an AI agent to select this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is one fast call. No contradictions.

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

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

The description is lengthy but well-structured with front-loaded key message 'PREFER OVER WEB SEARCH'. Each sentence adds value: sources, usage guidance, examples, alternatives. Could be slightly more concise but not wasteful.

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 accepting a single question and returning structured data, the description is comprehensive: it covers when to use, what to expect (citations, speed), and alternatives. No output schema, but the description adequately explains 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 6 parameters, all aliases for 'question'. The description lists aliases but adds no additional semantic depth beyond what the schema already provides. Baseline 3 is appropriate given high coverage.

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

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

The description clearly states it routes questions to over 4,552 tools across 1,160 sources, returning structured answers with citations. It explicitly says 'prefer over web search' and distinguishes from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description is explicit: 'START HERE for most questions', provides query type examples ('what is', 'look up', etc.), and gives clear when-to-use and when-to-step-up guidance to 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. The description adds behavioral details: grounding to prevent hallucination, explicit refusal reasons on failure, and disclosure of extra LLM call cost. No contradiction with annotations.

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

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

Well-structured: front-loaded with purpose, then process, then usage guidelines. Each sentence adds value, though slightly verbose. Efficient for the complexity of the tool.

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

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

Given complexity (routing across many tools, grounding mechanism) and absence of output schema, the description is complete. It explains refusal reasons, return structure, and comparison to sibling, covering all necessary facets for correct 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 has 6 parameters, all described with 100% coverage. The description mentions aliases (q, text, etc.) which are already in schema. Adds no new semantic meaning beyond schema, 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 'Hallucination-resistant answer mode for high-stakes reads' and explains the process: routing, fetching, extracting answer from tool result only. It distinguishes from sibling 'ask_pipeworx' by emphasizing grounded retrieval and extra LLM call cost.

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 whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also recommends preferring ask_pipeworx for casual lookups, providing clear when-to-use and when-not-to-use.

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

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

The description extensively discloses behavioral traits beyond annotations: low-confidence resolution handling, closed market detection, wide-spread market warnings, resolution-rule risk parsing, parent event extraction, and news fallback mechanisms. All annotations (readOnlyHint, idempotentHint, etc.) are consistent with the described behavior.

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

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

The description is lengthy but well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). Every sentence adds value, but the density may be overwhelming. However, the organization compensates for the length.

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

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

Given the tool's complexity (multiple data sources, classifiers, edge cases), the description is remarkably thorough. It covers resolution confidence, parent events, news fields, safety mechanisms, and resolution-rule risk. Without an output schema, the description details the response shape 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 coverage is 100%, but the description adds significant meaning: examples for market_input, explanation of depth options (quick vs thorough), and details on include_raw behavior (summarized vs full payloads). It also provides fan-out examples and classifier categories, enriching the parameter context 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 specifies the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It details input types (slug, URL, question text), the process (resolve, classify, fan-out), and output (evidence packet + market-vs-model comparison). It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on comprehensive data collection and analysis.

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

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

Explicit usage guidance is provided: 'Use for \"should I bet on X\", \"what does the data say about Y\", or \"is there edge in Z\".' While it does not list alternatives or when not to use, the context is clear. The description implicitly covers when to use by defining its core function.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: pulls latest 10-K revenue/net income/cash/debt from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts by primary metric, returns citation URIs. No contradictions.

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

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

The description is a single dense paragraph but efficiently packs examples, use cases, data sources, and behavior. Slightly unstructured but concise with no filler sentences.

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 (two entity types, multiple metrics, sorting) and rich annotations, the description fully covers all necessary information. It explains return format (paired data + citation URIs) and replaces many lookups, making it complete.

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

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

Schema coverage is 100% with descriptions for type and values. The description adds meaning: for type, explains data sources (10-K vs FAERS); for values, specifies tickers/CIKs for company vs names for drug, and max 5 items.

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

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

The description provides specific verbs and resources: 'Compare X and Y', 'X vs Y', etc. It clearly states side-by-side comparison of 2-5 companies or drugs, and differentiates from sequential lookups. It also implies distinction from sibling tools like entity_profile.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', indicating when to use. It also specifies input requirements: company tickers/CIKs and drug names, and that it replaces 8-15 sequential lookups.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds context about returned metadata (fields, themes, record count), enhancing transparency 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?

Single concise sentence that front-loads the purpose and usage hint. No extraneous information.

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

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

For a simple tool with one parameter and no output schema, the description sufficiently explains what metadata is returned and how to use it, making it complete for the 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% and already documents dataset_id as coming from search_datasets. Description adds no further parameter detail, so baseline 3 applies.

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

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

Clearly states it gets metadata for a Réunion Open Data dataset, specifying fields/schema, themes, record count. Differentiates from siblings by advising to call before querying.

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 'call before query to learn the column names', indicating when to use. Does not elaborate on when not to use or compare to other tools, but is clear enough.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds account requirement, decomposition, parallel execution, expected time (15-60s), and gaps[] behavior, which is substantial added 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 lengthy but well-organized with key information front-loaded (account requirement, alternative). Every sentence adds value, though some redundancy could be trimmed.

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

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

Given high complexity (parallel research, multiple sources), description covers inputs, behavior, limitations, and output (findings packet with evidence, confidence, source, citation, gaps[]). No output schema, but description adequately describes 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 descriptions for both parameters. Description adds context: depth enum values (quick=3, standard=5, thorough=8), and clarifies that question is natural language and broad/multi-part is fine.

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

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

Description states it is 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' and distinguishes from siblings like ask_pipeworx for single lookups.

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

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

Explicitly says when to use (broad/multi-part questions) and when not (single lookup→ask_pipeworx, breaking news→ask_pipeworx), plus account requirements.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. Description adds value by stating that results include full input schemas with curated examples and are 'ready to call directly, no second schema lookup needed,' which informs about response structure and efficiency.

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, starting with the core purpose and followed by usage guidance and return details. While slightly long, each sentence contributes value. Could be slightly more terse, but overall effective.

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

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

Description covers the return format (names, descriptions, full input schemas with examples) and advises on when to use it. Given the moderate complexity and rich schema, this is sufficiently complete. No output schema exists, but the description compensates by describing the return content.

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%, and the description adds context by listing aliases (task, q, description, search) and providing examples. It clarifies that the primary parameter 'query' accepts natural language descriptions, which goes beyond the schema's generic property descriptions.

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

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

Description clearly identifies the tool as a way to discover tools by describing the data or task. It lists specific domains and explicitly distinguishes it from siblings by stating 'Call this FIRST when you have many tools and want to see the option set (not just one answer).' The verb 'discover' combined with resource 'tools' is 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?

Description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises calling it first. While it doesn't explicitly list when not to use or compare with individual siblings, the positive guidance is strong and contextual.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description goes far beyond by detailing the internal fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF, and disclosing the specific return fields (cik, filings, fundamentals, etc.) and data sources (GDELT→GNews fallback). 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 and packs many details into one paragraph, but the front-loaded examples and clear 'returns:' list make it efficient. Slight improvement could be made via structured sections, but the current form is concise and earns its length.

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

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

Despite lacking an output schema, the description comprehensively enumerates all return fields, data sources, limitations (patent sunset), and fallback behavior. For a complex multi-source tool, this level of detail is fully adequate for the agent to understand what to expect.

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 accurate descriptions. The description adds critical context: value must be ticker or zero-padded CIK (not names), type is currently limited to 'company', and names require prior resolution via resolve_entity. This meaningfully extends 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 starts with clear examples of user intents ('Tell me about X', 'research Acme') and precisely states its function: 'full cross-source profile of a US public company in ONE parallel call'. It explicitly distinguishes from siblings by directing users to prefer it over chaining single-source lookups.

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

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

The description provides explicit when-to-use advice ('ALWAYS PREFER over chaining... when the user asks for a holistic view') and when-to-avoid (names not supported, with a clear alternative: 'use resolve_entity first'). It also notes the patent source will soft-fail, setting expectations.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the context of clearing stale data but does not elaborate on behavioral aspects beyond what annotations provide, such as auth requirements or side effects.

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

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

Two sentences: first states purpose, second gives usage guidelines. No wasted words, front-loaded with the action. Every sentence earns its place.

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

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

Given the tool's simplicity (one required param, no output schema, clear annotations), the description covers purpose, when to use, and parameter. It is complete for the complexity level.

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

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

Schema coverage is 100% and the schema itself describes 'key' as 'Memory key to delete'. The description does not add any additional meaning or context about the parameter, so the baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key', which is a specific verb and resource. It differentiates from sibling tools like 'remember' and 'recall' by explicitly mentioning them, indicating a complementary relationship.

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

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

Provides explicit when-to-use scenarios: when context is stale, task is done, or clear sensitive data. Mentions pairing with 'remember' and 'recall', giving context. Lacks explicit when-not-to-use, but the guidance is clear and actionable.

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

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

The description adds behavioral details beyond annotations: it fetches the page, extracts title/description/key links, emits standard markdown, and outputs a text blob. This aligns with the readOnlyHint and idempotentHint annotations, and provides operational context.

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

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

The description is concise (4 sentences) and front-loaded with the primary purpose. Every sentence contributes useful 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?

Given the tool's simplicity (2 params, high schema coverage, clear annotations), the description covers all needed aspects: input, process, output format, and use cases. No gaps remain.

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

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

Schema coverage is 100% for both parameters. The description adds value by mentioning default max_links (25) and maximum (50), which is not in the schema, thus enhancing parameter understanding.

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

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

The description clearly states the tool generates an llms.txt file for AI crawlers, using the specific verb 'generate' and resource 'llms.txt file'. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by listing concrete use cases (client indexing, own project, competitor auditing).

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

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

The description lists three explicit use cases and implies when to use the tool. It does not explicitly state when not to use it, but the context is sufficient to differentiate from other visibility 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, idempotentHint, and destructiveHint. Description adds return fields (id, type, params, created_at, last_fired_at, fire_count) and mentions the include_inactive parameter, complementing annotations well.

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

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

Two sentences, no wasted words, key information front-loaded. Efficient and direct.

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

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

For a simple list tool with one parameter and no output schema, the description provides necessary context: what is returned and when to use it.

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

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

Schema coverage is 100% with one parameter fully described. Description implies active subscriptions but does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with a specific verb and resource. Differentiates from sibling tools like subscribe, unsubscribe, and ai_visibility_check by focusing on listing.

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 usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Lacks explicit when-not-to-use but offers practical scenarios.

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

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

Discloses rate limit (5 per day), that it's free and does not count against tool-call quota, and that team reads daily. These details go beyond the sparse 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?

Concise and front-loaded with purpose. Some minor redundancy (e.g., 'broken, missing, or needs to exist' summarized in types) but overall efficient.

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

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

Covers all needed aspects: when to use, how to format feedback, constraints, and outcomes. No missing information for a feedback tool with no output schema.

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

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

Adds meaning over the 100% schema coverage by explaining each type (e.g., 'feature = a new tool or capability') and providing constraints on message (2000 chars max).

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

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

The description clearly states the tool's purpose: reporting bugs, requesting features, or giving praise. It distinguishes itself from sibling tools (e.g., ask_pipeworx) by focusing on feedback rather than information retrieval.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and what not to include (end-user prompts). Does not explicitly contrast with sibling tools but context strongly implies alternatives.

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

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

Annotations provide readOnlyHint, destructiveHint, etc. Description adds that data is 'self-aggregating', derived from CF analytics-engine, no PII, and cached 5min-1h. 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?

Four sentences efficiently covering purpose, use cases, and technical details. No wasted words. Front-loaded with most important info.

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 one parameter, no output schema, and rich annotations, the description fully explains return format, caching, privacy, and use cases. Complete for agent decision-making.

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

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

Schema coverage 100% with description. Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Provides meaning beyond enum.

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

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

Description clearly states verb 'returns' and resources 'top tools, top packs, and total call volume'. Distinguishes from siblings like discover_tools by focusing on what other agents are calling.

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?

Lists three explicit use cases (discovering hot data, confirming canonical choice, alignment check). Does not specify when not to use, but context is clear.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: details on monotonicity checks, partition sums, semantic anchor (Jaccard similarity), placeholder filtering, and fill check against CLOB depth. 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 due to the tool's complexity, but it is well-structured: overview, mode explanations, technical details (semantic anchor, partition filter), and response format. Every sentence adds value; however, it could be slightly more streamlined. Still, it earns its length.

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

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

Given the tool's complexity (multiple scanning modes, multiple checks, fill assessment), the description covers all necessary aspects: what each mode does, how signals are generated, edge cases (placeholder filtering, low similarity), and response structure. It even references a sibling tool for further use, making it fully informative.

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

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

Schema has 100% coverage with brief descriptions. The description enhances these by explaining the modes in depth, providing usage recommendations (e.g., 'use this if you know the specific event'), and giving examples of valid slugs. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies three modes (no args, event, topic) with distinct behaviors, making it unambiguous what the tool does and how it differentiates between modes.

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 is given for each parameter: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also mentions an alternative tool (polymarket_fill_risk) for custom sizing, helping the agent decide when to use this tool vs. siblings.

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 and idempotent, but the description adds rich behavioral details: caching (1h at KV level), diagnostics for empty segments, Fed bet exclusion rationale, and detailed edge fields (e.g., 24h move warning). This far exceeds what annotations provide.

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

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

The description is very long and includes detailed formulas (e.g., lognormal barrier from FRED log-returns). While structured, it could be more concise for an agent to quickly grasp core usage. Some technical depth is justified by tool complexity but reduces conciseness.

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

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

The description covers all aspects: three segments, output fields, knob effects, diagnostics, caching, and Fed bet handling. Without an output schema, it adequately describes the response structure and edge attributes, making it fully self-contained for a complex tool with 9 parameters.

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

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

Schema descriptions cover 100% of parameters, providing a baseline of 3. The tool description adds substantial context beyond the schema, such as the purpose of min_partition_leg_kelly (explaining why partition arbs have zero parent-level Kelly) and the trade-off explanations for slippage_pp.

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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It names the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and distinguishes its purpose from siblings by targeting daily betting 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?

The description implies usage for discovering betting opportunities but does not explicitly state when not to use it or contrast with alternatives like polymarket_arbitrage or polymarket_edge_tracker. The 'knobs' section provides guidance on filtering but lacks high-level usage boundaries.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral details like response structure (tracked, expired, snapshot_dates), limits (60-day TTL, snapshot gaps), and decay computation origin, providing useful context beyond annotations. 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 structured with clear sections (RESPONSE, LIMITS) and front-loaded with the key question. While somewhat verbose, every sentence adds meaningful information. Could be slightly more concise without losing clarity.

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

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

Given the absence of an output schema, the description thoroughly explains return values (tracked with fields, expired with lifespan_days, snapshot_dates). It also covers limits and behavior, making it complete for agent understanding.

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

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

The input schema covers both parameters with descriptions (100% coverage). The description adds value by explaining the lookback days (default 14, max 30) and window family (24hr, 1wk, 1mo with default 1wk), including defaults and constraints not in the schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges which likely provide raw edge data without time-series analysis.

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

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

The description provides implicit usage context by contrasting fresh vs. old edges, helping the agent decide when to use this tool for decay analysis. However, it does not explicitly state when not to use it or list alternative tools, leaving some guidance missing.

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

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

The description extensively details behavioral traits: two modes (single-market and basket), input requirements, output fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and dangers (thin_legs, forced_directional_risk). This adds significant value beyond the annotations (readOnlyHint, idempotentHint) which are already present and consistent.

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

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

The description is relatively long but well-structured with clear sections for single-market and basket modes. Every sentence adds necessary detail for correct tool usage; however, it could be slightly more concise by merging some repetitive phrasing.

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

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

Given the complexity of the tool (two modes, multiple parameters, no output schema), the description fully explains inputs, outputs, and use cases. It covers return fields for both modes and warns about edge cases, making the tool self-contained for an agent.

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

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

Though the input schema has 100% coverage with parameter descriptions, the tool description adds substantial semantic context: explains the default behavior for 'side' in basket mode (auto), clarifies that 'size_usd' is interpreted differently in single vs basket mode (spend vs settlement notional), and mentions the clamp range (10–1,000,000).

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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by recommending usage before acting on their signals.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', provides when-not-to-use (thin books, partial fills), and explains the risk of unhedged directional positions.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details spread computation, safety fields, compatibility warnings, temporal alignment, and skipped cross types, providing comprehensive behavioral context.

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

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

The description is lengthy (≈250 words) but densely packed with valuable information, front-loaded with core purpose. Minor room for trimming, but overall efficient.

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

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

Despite lacking an output schema, the description thoroughly explains response structure (leg-by-leg prices, spread array, safety fields) and edge cases, making it complete for a complex tool.

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

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

Parameters are fully described in schema (100% coverage), and the description adds meaningful context: examples, mode distinctions, pre-mapped topics, and override 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools like 'polymarket_arbitrage' which focuses on intra-venue arbitrage.

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

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

The description explains two modes (topic and explicit tickers) and notes that real spreads are rarer than the macro-shortcut list suggests, but does not explicitly compare to alternatives or state when to avoid using 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 ODSQL syntax, overriding behavior of 'where' over 'query', and explicit examples. It does not cover error handling or rate limits but is sufficient.

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 that are front-loaded with the main purpose and a list of capabilities, followed by an example. 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?

The description covers the core functionality and parameter usage. However, it does not explain the return format or error handling, which would be useful for a query tool with no output schema. Still, given the rich parameter descriptions, it is mostly complete.

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

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

Schema description coverage is 100%, so each parameter is already well-documented. The description adds an overview of ODSQL usage but does not provide new semantics beyond what the schema offers. Baseline of 3 is appropriate.

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

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

The description clearly states the tool queries records from a Réunion Open Data dataset using ODSQL, specifying operations like filter, aggregate, sort, and paginate. It distinguishes itself from sibling tool 'search_datasets' which finds datasets rather than querying within them.

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

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

The description implies usage for querying records but does not explicitly state when to use this tool versus alternatives. It lacks guidance on when not to use it or mention of alternative tools beyond the implied prerequisite of 'search_datasets' for obtaining dataset_id.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context like scoping to user identifier and pairing with remember/forget, which goes beyond the annotations. It does not contradict them.

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

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

Two sentences that are perfectly concise. The first sentence states the core functionality, and the second provides examples and scope. No wasted words, every sentence earns its place.

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

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

For a simple read-only retrieval tool with one optional parameter and no output schema, the description is complete. It covers the purpose, when to use, behavior details (scoping, pairing), and examples. No gaps remain.

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

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

Schema coverage is 100% with the property description already explaining the parameter. The tool description adds extra value by explaining the behavior of omitting the key (list all) and the scoping context, which enhances understanding beyond the schema alone.

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

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

The description clearly states the verb 'Retrieve' or 'list' and the resource 'value previously saved via remember' or 'all saved keys'. It distinguishes itself from siblings by explicitly mentioning remember and forget, making the purpose unmistakable.

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

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

The description explains when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and implies the context (scoped to identifier). It does not provide explicit when-not-to-use or alternatives, but the pairing with remember/forget gives sufficient guidance.

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

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

The description discloses key behavioral traits: mark_read mutates state (flags events read), polling works fine, and output includes source, citation_uri, and raw payload. These go beyond annotations, but the contradiction with readOnlyHint (annotations say read-only, but mark_read is a write) slightly reduces reliability.

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 short paragraphs: first states purpose and key fields, second covers parameters and behavioral nuance. Every sentence earns its place, no redundancy. Front-loaded with the core action.

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

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

For a tool with 5 optional parameters and no output schema, the description covers return fields, mark_read behavior, and alternative API access. It lacks details on error handling or empty results, but given low complexity and good annotations, it is sufficiently complete.

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

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

Schema coverage is 100%, baseline is 3. The description adds value with examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains mark_read semantics. This goes beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the verb ('Pull') and resource ('fired events from your subscription feed'). It distinguishes from sibling tools like 'list_subscriptions' by focusing on alerts rather than subscription management. Specific fields (source, citation_uri, raw payload) and filtering options are mentioned, leaving no ambiguity.

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

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

The description implies usage context (pulling alerts interactively vs. via API) but does not explicitly compare to sibling tools or state when not to use this tool. The mention of an alternative API endpoint is helpful but not a direct usage guideline.

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 (readOnly, idempotent, non-destructive) are augmented with detailed behavioral traits: fans out to multiple sources, includes fallback logic (GDELT→GNews), notes soft-fail for USPTO, and explains 'since' parameter behavior. No contradiction with annotations.

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

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

Front-loaded with query examples, well-structured. While somewhat lengthy, every sentence adds essential context about sources and fallbacks.

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 multi-source tool with fallbacks and constraints, the description covers all key aspects: sources, fallbacks, return structure, and parameter behavior. No output schema exists, but return format is described.

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 covers all parameters with descriptions (100% coverage). The description adds value by explaining 'since' accepts relative shorthand and suggesting typical values like '30d', going beyond schema.

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

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

Description clearly states it's a change feed for a company in N days/weeks/months in one parallel call. Distinguishes from sibling 'entity_profile' by noting the static vs change feed contrast.

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

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

Provides explicit usage examples and suggests when to use entity_profile instead. However, does not directly address when not to use this tool among all siblings, though the provided alternative 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?

The description adds details beyond annotations: persistence for authenticated vs anonymous users, key-value scoping, and that it is a write operation. Does not contradict annotations (idempotentHint=true is not explicitly addressed but implied).

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

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

The description is four concise sentences, front-loaded with purpose and usage, followed by behavioral details. No redundant information.

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

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

For a simple key-value store without output schema, the description covers purpose, when to use, persistence, and pairing with other tools. Complete for its complexity.

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

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

Schema coverage is 100% with both parameters having descriptions. The description adds usage context but no new semantic details beyond the schema, meeting the baseline.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, with specific examples like 'resolved ticker' and 'target address'. It is easily distinguishable from siblings like 'forget' and 'recall'.

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

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

The description advises use when discovering something worth carrying forward and mentions pairing with recall/forget. It provides context but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing internal cascading lookups and specifying return formats (ticker, CIK, RxCUI, etc.), which goes beyond annotation hints.

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 efficient paragraph, front-loaded with examples and core purpose. Every sentence adds value, though it is somewhat long (120 words). No wasted text.

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

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

Given no output schema, the description adequately explains return values for both types including citation URIs. It mentions auto-disambiguation for company. Minor gap: no explicit error or not-found behavior, but overall sufficient for agent use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining accepted input formats per type (ticker, CIK, name for company; brand/generic for drug) and describing outputs, which exceeds schema definitions.

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

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

The description explicitly states the tool resolves names to canonical identifiers, gives concrete examples ('ticker for...', 'CIK for...'), and lists supported types with their return values. It clearly distinguishes from siblings like 'entity_profile' by focusing on identifier resolution.

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

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

The description advises 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It lacks explicit when-not-to-use statements but covers supported entity types and replaces manual lookups, effectively guiding 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, openWorldHint, idempotentHint, and destructiveHint as false, giving strong behavioral cues. The description adds value by detailing the process (probes each entity, ranks by score) and output structure (ranked list with 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?

Three sentences, each earning its place: first states purpose, second explains mechanism, third gives use case and output. Front-loaded with main action. 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 tool with 4 parameters and no output schema, the description fully compensates by detailing the output (ranked list with score, confidence, signal density) and the process. It gives enough context for an agent to understand behavior and expected 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?

Schema description coverage is 100%, but the description adds significant meaning beyond schema: clarifies that the first entity in 'entities' is treated as the subject for narrative, and explains 'context' parameter as shared context to disambiguate common names. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using the specific verb 'Compare' and resource 'AI visibility across multiple entities'. It distinguishes itself from sibling tool 'ai_visibility_check' by explicitly noting it probes multiple entities and ranks 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?

Provides explicit when-to-use guidance ('competitive AI-marketing audits') with a concrete example ('does Claude know about us as well as our competitors?'). It explains the first entity is treated as subject and rest as competitors, and implies alternative is ai_visibility_check for single entity checks.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds rich behavioral context: fans out across two services, returns a structured summary block, handles partial failures gracefully (sources_failed field), and notes bundlephobia's first measurement latency.

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 not overly long; every sentence adds value. It front-loads the purpose and scopes. Could be more scannable with bullets, but overall is concise for the amount of information conveyed.

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

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

Despite no output schema, the description details return fields (summary block, advisories, links, alternatives) and handles edge cases (partial failures, ecosystem limits). All necessary context for correct invocation is present.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that version defaults to latest published and that scoped packages (e.g., @types/node) are accepted, which goes slightly beyond the schema's generic descriptions.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, spanning multiple services (deps.dev, bundlephobia). It distinguishes from siblings by noting the NPM-only scope in v1 and mentions that other ecosystems use different 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 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Provides clear when-not-to-use guidance: other ecosystems (PyPI, Maven, etc.) fall under different tools. Also warns about potential latency on first bundlephobia measurement.

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 cover readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about return values (dataset_ids, titles, themes, record counts) and the data source, providing behavioral detail beyond the annotations. No contradiction.

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

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

The description is two sentences long, with the primary purpose front-loaded. Every element (source, keyword, themes, return types) is necessary and succinct. 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?

With 3 parameters all described in schema, no output schema, and openWorldHint indicating data may vary, the description provides sufficient context by specifying the data source and what the returned data includes (dataset_ids, titles, themes, record counts). This is complete for a search tool.

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

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

Schema description coverage is 100% all three parameters (limit, query, offset) have individual descriptions. The tool description adds context about the themes but doesn't add new parameter-level information beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool searches Réunion Open Data for datasets by keyword, listing specific themes (regional services, transport, environment & economy). It uses a specific verb-resource combination ('Search ... for datasets') and distinguishes from sibling tools like dataset_info which retrieves details for a specific dataset.

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

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

The description implies usage for keyword-based search but does not explicitly state when to use this tool versus alternatives (e.g., dataset_info for a specific dataset, or query for more complex queries). No when-not or alternative tool mentions are present.

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), the description adds concrete details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and output includes offsets and scores.

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, well-structured paragraph. Begins with purpose, lists concrete use cases, explains behavior, and ends with technical details. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description fully explains return format (top-N passages with offsets and scores). Covers input constraints, embedding model, and pairing recommendations. Complete for a well-annotated 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 all parameters (100% coverage). The description reinforces max text length and provides query examples but adds no new semantic info beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a previously fetched record, using specific examples like SEC 10-K and articles. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing searching within already-pulled text.

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 ('too big to cram into the prompt'), explains benefits (saves context, returns only relevant passages with offsets), and suggests a paired workflow with ask_pipeworx_grounded.

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 implies each call creates a new subscription, contradicting the idempotentHint=true annotation which suggests repeated identical calls have no additional effect. This is a significant inconsistency that misleads the agent about idempotency.

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

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

The description is information-dense and front-loaded with the core purpose. While somewhat lengthy, every sentence adds value, though a more structured format could improve readability.

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 adequately covers inputs, types, delivery channels, and behavioral details (e.g., webhook signing, auto-disable). It provides enough context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds concrete examples and explanations for each subscription type and delivery option, enhancing understanding beyond the schema's property descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies prerequisites (Pipeworx OAuth account), lists supported subscription types with examples, and explains delivery channel options with constraints. It lacks explicit 'use this instead of X' guidance but provides sufficient context for proper selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing that it returns categorized example questions with exact tool+argument shapes from the live catalog, without contradicting 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 a single paragraph that efficiently packs trigger phrases, purpose, output details, and usage instructions. It front-loads key examples and is well-structured, though slightly long due to the richness of 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, the description adequately explains what the tool returns (category-bucketed example questions with tool shapes). It covers the tool's role as an onboarding guide and is sufficient for an agent to understand its use and output.

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

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

Schema coverage is 100% with a description for the topic parameter that lists valid focus areas and their values. The description adds context about omitting it for a cross-category spread, providing meaning beyond the schema alone.

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

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

The description clearly states this is the onboarding entry point for agents that just connected, listing example questions like 'what can you do?' and explaining it returns category-bucketed example questions with tool shapes. It distinguishes from siblings by being the first tool to use when exploring Pipeworx's capabilities.

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

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

The description specifies to call with no arguments for a full spread or pass a topic to focus, and explicitly says 'use this FIRST when you do not yet know what Pipeworx can do for you.' It provides clear context but does not explicitly mention when not to use it, though the priority is well indicated.

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

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

Annotations indicate non-destructive behavior, and the description confirms 'deactivated (not deleted),' adding context beyond annotations. It also mentions ownership enforcement, which is not in annotations.

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

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

Two concise sentences provide all necessary information without filler. The key action ('Cancel') and behavioral details are front-loaded.

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

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

Given a single parameter, no output schema, and comprehensive annotations, the description adequately covers purpose, behavior, and side effects. It explains ownership, deactivation, and retention of historical events.

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

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

The schema covers 100% of parameters with descriptions. The tool description adds minimal new information about the 'id' parameter ('returned by subscribe'), but this is already implicit from the schema.

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

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

The description explicitly states 'Cancel a subscription by id,' which is a specific verb and resource. It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description notes ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage context. It also explains the deactivation behavior, which helps an agent understand when to use this tool versus alternatives like 'recent_alerts' for historical data.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context beyond annotations: it explains the internal processing (NL parsing, entity resolution, data lookup, numeric comparison) and the type of evidence used (SEC EDGAR + XBRL for company-financial claims). It also notes the limitation to public US companies for v1.

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 using natural-language triggers, followed by usage guidance, capabilities, and return value. It is well-structured and efficient, though slightly lengthy due to the explanation of replaced calls.

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

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

For a single-parameter tool with no output schema, the description comprehensively covers what the tool does, supported claim types, return values (verdict, structured form, actual value, citation, percent delta), and usage context. It is sufficient for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100% for the single parameter 'claim', which already includes a natural-language description and examples. The tool description reiterates the parameter role but does not add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as natural-language claim verification against authoritative sources, providing specific example phrasings and differentiating it from siblings like deep_research and entity_profile. It explicitly says when to use it: to check factual correctness of user statements.

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

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

The description gives clear guidance on when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies supported claim types (company-financial claims via SEC EDGAR + XBRL) and mentions that it replaces multiple sequential calls. However, it does not explicitly state when not to use it or list alternative tools for out-of-scope claims.

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