Data Paris

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds important behavioral details: it probes models, requires BYO Anthropic key with direct payment, and returns a structured response per model plus combined. 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?

Three sentences, each packed with essential information: core function and output, model options and key usage, return format and use cases. No fluff, front-loaded with key actions.

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

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

Despite no output schema, description explains return structure (per-model object plus combined view) and usage contexts. It lacks detail on how scoring works or what signals are, but for a probe tool with 4 parameters, it provides sufficient context for an agent to decide invocation.

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

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

Schema covers all 4 parameters with descriptions. Description adds value by explaining the default model, the purpose of _apiKey (BYO key, direct payment), and how context helps disambiguate, enriching understanding beyond schema.

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

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

The description clearly states the tool probes LLMs for visibility of a business/brand/product/topic and outputs a score 0-100 per model. It specifies the default model and the option to probe Anthropic, distinguishing it from sibling tools that might do similar but different tasks like scan_competitor_ai_presence.

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 specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) providing context for when to use. However, it does not explicitly exclude scenarios or compare with siblings like scan_competitor_ai_presence, which could have overlapping functionality.

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. Description adds context: routes to right tool among 4476, fills arguments, returns structured answer with stable citation URIs. Mentions it works on every tier. Could add details on rate limits or error handling, but overall solid.

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

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

Well-structured with key guidance front-loaded. Includes examples and alternatives. Slightly lengthy but every sentence adds value. Could be trimmed by reducing example list, 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 purpose, usage, alternatives, examples, and behavioral context. No output schema, so description mentions return format (structured answer with citation URIs). Sufficiently complete for a tool of this complexity.

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

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

Schema coverage is 100% with all 6 parameters described (question and 5 aliases). Description does not add parameter-level detail beyond schema, but provides examples illustrating expected input format. Baseline of 3 is appropriate as schema already documents parameters adequately.

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

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

The description clearly states the tool answers factual questions using authoritative structured data, with a specific verb 'ask' and resource 'Pipeworx' (a system of 4476 tools). It distinguishes from sibling tools like web search, ask_pipeworx_grounded, and deep_research by emphasizing its role as a default entry point for most questions with one fast call.

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: 'PREFER OVER WEB SEARCH for questions about current or historical data...' and lists specific query types. It gives clear alternatives: use ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions, and mentions web search for breaking news. Examples illustrate appropriate 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds detailed behavioral traits: returns specific fields including evidence, confidence, source, and refusal_reason; lists explicit refusal scenarios (not_in_source, no_tool_match, etc.); and emphasizes no invention of facts. No contradiction with annotations.

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

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

Every sentence serves a purpose: purpose, routing behavior, output format, refusal reasons, use case guidelines, and cost. Front-loaded with key purpose. No wasted words, well-structured.

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

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

Despite no output schema, the description fully explains the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and lists all possible refusal reasons. It also covers the complexity of routing across 4,476 tools and 1,127 sources, making the tool's behavior predictable for the 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?

Schema coverage is 100% with 6 parameters all aliases for 'question'. The description restates what the schema already provides (accepts natural language and aliases), adding no new meaning beyond 'Your question in natural language'. 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 it is a hallucination-resistant answer mode for high-stakes reads. It specifies the verb 'extracts the answer using ONLY what the tool result contains' and distinguishes from sibling ask_pipeworx by highlighting the grounded extraction and explicit refusal behavior.

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

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

Explicitly states when to use (high-stakes, when answers will be quoted/cited/acted on) and when not to (prefer ask_pipeworx for casual lookups). Also mentions the extra LLM call cost, providing clear decision criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds extensive behavioral details: market resolution, classification fan-out, safety mechanisms (low-confidence match, closed markets), cancellation rule parsing, and news fallback. 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?

Well-structured with clear sections (CLASSIFIERS, FAN-OUT, etc.) and front-loaded with main purpose. While lengthy, every sentence adds value, so it earns its keep. Minor deduction for verbosity.

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

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

Despite no output schema, the description thoroughly details response shapes, evidence structure, safety checks, and resolution risk. Fully compensates for missing structured output, making it complete for agent use.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant meaning beyond schema: explains market input variants (slug, URL, question), depth enum meaning, and include_raw context. Fully compensates.

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

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

Description clearly states it researches a Polymarket bet by pulling Pipeworx data, with specific verb+resource. It distinguishes from siblings like polymarket_edges and polymarket_arbitrage, which focus on edge/arbitrage rather than comprehensive 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?

Explicitly lists use cases ('should I bet on X', etc.) and provides examples. Lacks explicit exclusions or alternatives, but the sibling tool list implies alternatives for edge detection or validation. Still strong guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, explains sorting by primary metric, and notes citation URIs, providing rich behavioral context.

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

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

The description is concise (around 100 words) yet dense with information, front-loading usage examples and covering data sources, special handling, and output format in a logical order.

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 sufficiently explains return format (paired data + citation URIs), input constraints (2-5 items), and data behavior per type, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the meaning of each parameter: for 'type' it specifies data pulled, and for 'values' it clarifies tickers/CIKs for companies and drug names. This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call. It distinguishes itself from siblings by explicitly replacing 8-15 sequential lookups and using specific verbs like 'compare'.

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

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

The description provides explicit usage examples such as 'Compare X and Y' and 'X vs Y', and strongly advises ALWAYS PREFER over sequential single-pack lookups when comparing entities, offering clear guidance on when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, covering safety. The description adds behavioral context by specifying the return content (metadata: fields/schema, themes, record count) and the scope (Paris Open Data). No contradictions with annotations.

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

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

The description is a single, well-crafted sentence that front-loads the purpose and includes a usage hint. No wasted words; every part adds value.

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

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

For a tool with one parameter, rich annotations, and no output schema, the description adequately specifies the metadata content and usage context. It does not detail the output format, but given the simple nature of metadata retrieval, it is sufficiently complete for an AI agent.

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

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

Schema coverage is 100% with a clear description for dataset_id ('Dataset id from search_datasets'). The description adds no extra parameter details beyond the schema, but ties the parameter to a usage step ('call before query to learn the column names'). Baseline 3 is appropriate given full schema 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 the action (get metadata), the resource (one Paris Open Data dataset), and lists what is included (fields/schema, themes, record count). It also distinguishes from sibling tools by explicitly recommending it be called before querying to learn column names, contrasting with querying tools.

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

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

The description provides explicit context on when to use the tool ('call before query') and implies its purpose (to learn column names). It does not explicitly state when not to use alternatives, but the hint is clear enough for an AI agent to differentiate from query or search tools among 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?

Adds context beyond annotations: requires account, returns gaps[] for unanswered facets, runs 15-60s, uses 4,476 tools in parallel, never invents evidence. All align with read-only, idempotent, open-world 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?

Long but front-loaded with critical info and well-structured. Every sentence adds value, though some redundancy could be trimmed. Still efficient for the complexity.

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

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

Despite no output schema, description fully explains return format (findings packet with evidence, confidence, source, citation, gaps[]). Covers limitations, alternatives, and performance expectations, making it self-sufficient.

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

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

Schema covers 100% with descriptions for depth and question. Description adds minor context (depth enum values mapped to facet counts, question accepts broad phrasing) but does not significantly enhance understanding beyond schema.

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

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

The description clearly states it performs grounded multi-source research across structured data sources, decomposing questions into facets and returning findings with evidence. It distinguishes from siblings like ask_pipeworx and mentions it is not open-web search.

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

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

Explicitly states when to use (broad/multi-part questions) and when not to (breaking news, single lookup). Directs to alternatives: ask_pipeworx for single or current news, and notes account requirement with free/paid tiers.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it returns top-N relevant tools with full input schemas and curated examples, ready to call directly. This provides transparency on output format and no side effects, consistent with annotations.

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

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

The description is concise, front-loaded with the core purpose, then lists domains, explains return format, and gives usage advice. Every sentence adds value without fluff. It is appropriately sized for the complexity.

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

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

Given the tool has 6 parameters and no output schema, the description covers the main purpose, usage context, and what the output contains (top-N tools with schemas). It is complete for an AI agent to understand when and how to use it, especially with the sibling context.

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 context by explaining the query parameter as a natural language description and provides examples. However, it does not explicitly explain aliases or the limit parameter beyond schema, which is minor. The added value warrants 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 explicitly states the tool's purpose as finding tools by describing data or task, using verbs like browse, search, look up, discover. It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings by advising to call it first to see the option set.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by a broad list. It also says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly differentiates its usage from direct query tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: it fans out across multiple sources, mentions the USPTO sunset and soft-fail, and notes fallback mechanisms (GDELT→GNews). This goes well beyond annotations.

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

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

The description is relatively long but every sentence adds value. It is front-loaded with example queries and structured by returning fields. While slightly verbose, the complexity of the tool justifies the length.

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

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

Given the tool's complexity (multiple data sources, return fields, fallbacks), the description is complete. It covers all key aspects: what data is returned, how to pass parameters, and edge cases (USPTO sunset). No output schema is needed as the description details return values.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description adds value by explaining accepted formats ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') and explicitly stating that names are not supported, which is 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: 'full cross-source profile of a US public company in ONE parallel call.' It includes example queries ('Tell me about X', 'research Acme') and lists the data sources and return fields, distinguishing it from chaining multiple tools.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also notes that names are not supported and advises using resolve_entity first, providing clear when-to-use and alternative guidance.

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

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

Annotations already provide destructiveHint and readOnlyHint. Description adds context about use cases but not deeper behavior (e.g., idempotency or response). Adequate but not enhancing beyond annotations.

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

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

Two sentences, front-loaded with action and usage. Every sentence adds value with no waste.

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 delete tool with one parameter, the description covers purpose, usage, and context. Lacks mention of return value or confirmation, but no output schema is present.

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

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

Schema coverage is 100% with a description for 'key'. Tool description mentions 'by key' but adds no extra meaning beyond schema. Baseline score for 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?

Description clearly states 'Delete a previously stored memory by key', specifying the action and resource, and distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with 'remember' and 'recall', guiding agent on alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds process detail: fetches page, extracts title/description/key links, emits markdown. Provides behavioral context beyond annotations.

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

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

Three sentences, front-loaded with purpose, then process, then use cases. No extraneous text; 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?

With 2 parameters and no output schema, description explains input (URL, optional max_links) and output ('single text blob ready to drop at site-root/llms.txt'). Sufficient for a straightforward generation tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. Description mentions 'any URL' and 'Maximum number of link entries' but does not add new meaning beyond the schema's 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 uses specific verbs ('Generate', 'Fetches', 'extracts', 'emits') and identifies the resource ('llms.txt file'). It clearly distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on generating the llms.txt format.

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

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

Explicitly lists three use cases: indexing a client's site, drafting for own project, auditing competitor visibility. Does not explicitly state when not to use, but the use cases guide selection among related tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by specifying return fields (id, type, params, created_at, last_fired_at, fire_count) and default behavior (active subscriptions, caller's scope). No contradictions.

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

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

Two sentences, no unnecessary words. Information is front-loaded: purpose, return fields, usage guidance. Highly 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 no output schema, description lists all returned fields. Tool is simple with one optional parameter. Annotations cover safety and idempotency. 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 is 100% (parameter 'include_inactive' described in schema). Description does not add extra parameter meaning beyond what schema provides, so baseline 3 is appropriate.

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

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

Description clearly states verb 'list' and resource 'the caller's active subscriptions', distinguishes from sibling tools 'subscribe' and 'unsubscribe' by specifying it lists existing subscriptions for review or cancellation.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use. Lacks explicit exclusion of alternatives but sufficient for the sibling set.

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

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

Description adds valuable behavioral context beyond annotations: rate limit of 5 per identifier per day, free usage, and that feedback is read daily and influences roadmap. Annotations already indicate the tool is not read-only, destructive, or idempotent, and description is 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?

Five sentences, each adding unique value: what it does, when to use, how to describe feedback, team response, and constraints. Front-loaded with the main action. No unnecessary words or repetition.

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

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

Given the tool's simplicity and the presence of a complete schema and annotations, the description covers all necessary context: purpose, usage scenarios, constraints, and expected content. No gaps remain for an AI agent to use it 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?

Input schema covers parameters thoroughly (100% coverage), so description does not need to repeat param details. However, it provides helpful usage guidance on how to fill in the message and context, adding value beyond the raw schema. A 4 is appropriate as the description complements but doesn't deeply elaborate on parameters.

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

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

Description clearly states the tool is for sending feedback to the Pipeworx team about bugs, missing features, or praise. It uses a specific verb ('Tell') and identifies the resource ('Pipeworx team'). The purpose is distinct from sibling tools like ask_pipeworx or query, which are for retrieving information, not providing feedback.

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

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

Explicitly lists when to use: for bugs, feature/data gaps, or praise. Provides clear instructions on how to describe the issue (in terms of tools/packs, not end-user prompts). No alternative tools for feedback exist, so guidance is complete.

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 transparency about being self-aggregating, derived from CF analytics-engine, no PII, and cached 5min-1h depending on window. This goes beyond the annotations by explaining data source, privacy, and freshness.

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 compact paragraphs with no wasted words. It front-loads the core functionality, then provides use cases, and ends with technical notes. Every sentence adds value and is efficiently structured.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, strong annotations), the description covers function, use cases, data source, caching behavior, and privacy. It is fully sufficient for an agent to decide when and how to use it 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% for the single `window` parameter, which has an enum with descriptions. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the appropriate value meaningfully.

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 returns top tools, top packs, and total call volume over configurable windows (24h, 7d, 30d). It provides three concrete use cases (discovering hot data, confirming popular tools, aligning use cases), distinguishing it from sibling tools like search or data info tools.

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

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

The description explicitly lists when to use the tool (discovering hot data, confirming popular tools, seeing alignment) and implies its aggregative nature versus detailed queries. However, it does not explicitly state when not to use or name alternative tools for specific data needs, but the use cases are well-defined.

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, and non-destructive behavior. The description adds rich context: monotonicity violations, partition-checks, semantic anchor (Jaccard similarity), partition filter, fill check against CLOB depth, and conditions for not trading. 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 long but well-structured with clear sections and front-loaded key information. Some details (e.g., fill check) could be more concise, but given the complexity, the length is justified.

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

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

Despite no output schema, the description explains expected output (opportunities array, partition_check details) and references sibling tools for additional functionality. It covers all necessary context for an agent to select and invoke 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 description coverage is 100%, and the description adds significant meaning beyond schema: explains mode differences, provides example slugs, and details output structure including fill check. The schema descriptions are minimal, while the tool description enriches them.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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 clearly states requirements: 'REQUIRES one of `event` (single-event mode) OR `topic` (cross-event mode) — call with no args fails.' It provides guidance on when to use each mode and references alternatives like polymarket_fill_risk for custom sizing.

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

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

The description adds extensive behavioral context beyond annotations (readOnlyHint, etc.), including caching (1h), data sources (FRED, GDELT), model families, edge calculation details, Kelly fractions, 24h-move warning, tradeable-edge filters, and diagnostics. It does not contradict any annotation.

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

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

The description is very long and detailed, but everything is relevant. The structure with sections and bullet points helps readability, but conciseness could be improved. It is adequately concise for the complexity, but still verbose.

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

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

Given no output schema and 9 parameters, the description thoroughly explains all return segments (by_segment, fed_candidates, _diagnostics) and included fields (edge_pp_net, kelly_fraction, etc.), as well as caching and filtering behavior. All necessary context for a complex discovery tool is provided.

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

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

With 100% schema description coverage, baseline is 3. The description adds value by explaining how parameters interact (e.g., tradeable-edge filters, partition leg Kelly), providing usage context that goes beyond the schema descriptions.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and the context 'what should I bet on today' distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explicitly states the use case ('what should I bet on today') and provides filtering knobs (min_liquidity, max_spread_pp). It does not explicitly state when not to use or list alternatives, but the context is clear and guides appropriate use.

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

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

Extensively details behavior beyond annotations: explains it reads snapshots, returns full time-series, computes trend and decay, lists expired opportunities with lifespan, mentions snapshot gaps and TTL limits. Annotations already declare readOnly and idempotent, but description adds rich 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?

Description is well-structured with purpose first, then parameters, then response format, then limitations. While somewhat long, each part is necessary given the tool's complexity; no redundant 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 no output schema, description fully covers response fields (tracked, expired, snapshot_dates), edge cases (gaps in data, expiration), and limitations (TTL, daily closes only). Provides all information an agent needs to understand usage 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 descriptions. Description adds clamping info for days (2-30), default values, and window family options ('24hr | 1wk | 1mo'), which goes beyond schema and enhances parameter understanding.

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

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

Description clearly states the tool provides edge persistence and decay telemetry, answering how long an edge exists and if it is shrinking. Distinguishes itself from sibling 'polymarket_edges' by focusing on time-series analysis rather than raw snapshot data.

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

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

Implies usage via the question it answers and the mention that a 3-week-old wide edge is different from a fresh one. Provides context on when to use time-series edge tracking but does not explicitly list alternatives or when not to use.

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

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

The description goes beyond annotations by detailing behavioral traits: it checks order book depth, returns a verdict (clean|degraded|cannot_fill), and warns about thin books and directional risk. It mentions the dominant loss mode in real arb-bot P&L. Annotations already indicate read-only and safe behavior; the description adds valuable context without contradiction.

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

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

The description is relatively long but well-structured, with clear sections for single-market and basket modes. Every sentence adds value, though some minor compression could be made without losing clarity. The use of headings-like formatting aids 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 lacking an output schema, the description comprehensively documents all return values for both modes, including edge cases like thin_legs and forced_directional_risk. It explicitly addresses limitations and provides context about partial fills and directional risk. For a complex tool with multiple modes, this is fully 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% (all 4 parameters documented). The description adds significant meaning: it explains that market and event are mutually required, details the default behavior for side in basket mode ('auto from partition sum'), and clarifies the interpretation of size_usd for buys vs. sells and basket mode. This goes well 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 explicitly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes and lists specific return fields (e.g., top_of_book, slippage_pp, verdict). The purpose is further clarified by contrasting with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit guidance on when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risks of not using it (e.g., partial basket fills converting an arb into an unhedged directional position). This effectively differentiates usage from sibling 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, etc. The description adds substantial behavioral context: details on response structure (leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and conditions for meaningful spreads. 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 comprehensive but dense. It front-loads the core purpose and then details modes, response fields, and warnings. Every sentence adds necessary information; however, a slightly more structured layout (e.g., bullet points) could improve readability for agents. Still highly informative.

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

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

Despite no output schema, the description thoroughly explains response fields (leg prices, matched spreads, compatibility_warning, temporal_alignment, skipped counters) and edge cases (when spreads are meaningless). Covers all essential aspects 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% with descriptions for all three parameters. The description adds value by listing the ten topic shortcuts, explaining how explicit tickers override topic-mapped sides, and providing example values. Enhances understanding beyond 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 tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from siblings by focusing on cross-venue comparison, with explicit mention of two modes and conditions for meaningful spreads. Specific and unambiguous.

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

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

The description explains when to use the tool via two modes (topic shortcuts vs explicit tickers) and includes warnings about compatibility and temporal alignment. It advises that most pre-mapped topics are not tradeable. However, it does not explicitly mention when to use sibling tools like 'polymarket_arbitrage' as alternatives, slightly lowering the score.

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, and idempotent hints. The description adds context about using ODSQL language and Paris Open Data, but does not elaborate on pagination behavior, error handling, or data freshness. It is consistent with annotations and provides minimal extra behavioral insight.

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

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

Two sentences: the first states the core purpose, the second lists key capabilities. No wasted words, front-loaded with the most important information. Exemplary conciseness.

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

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

Despite rich annotations and complete schema, the tool has no output schema, so the description should explain return values. It does not. Also missing is guidance that the tool requires prior dataset selection via search_datasets. The description is too minimal for a tool with ODSQL complexity and 8 parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description groups parameters by function (filter, aggregate, sort, paginate) but does not add meaning beyond what the schema descriptions already provide for each parameter. It offers a helpful summary but no new information.

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

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

The description clearly states the tool queries records from a Paris Open Data dataset using ODSQL, with specific verbs and resource. It distinguishes itself from the sibling tool 'search_datasets' by focusing on querying within a dataset rather than finding datasets.

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 capabilities (filter, aggregate, sort, paginate) but does not explicitly state when to use or avoid this tool. It implies that the tool is for querying after obtaining a dataset_id, but no direct guidance on alternatives or prerequisites.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context: scoping to identifier, listing behavior when key omitted, and the pairing with remember/forget. It does not contradict annotations, and provides value beyond them. Minor omission: no mention of latency or rate limits, but adequate for a simple retrieval tool.

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

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

Three sentences, each serving a purpose: what the tool does, when to use it, and how it relates to siblings. Front-loaded with the core action. No redundant or unnecessary words.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, rich annotations), the description covers the behavior, usage context, scope, and relationships to siblings. It is fully complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with one optional parameter 'key'. The description adds that omitting the key lists all keys, which echoes the schema description. It adds context about the scope and usage, but does not significantly extend beyond what the schema already conveys. 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 it retrieves a stored value or lists all keys, with a specific verb ('Retrieve') and resource ('value previously saved via remember'). It distinguishes from siblings 'remember' and 'forget', and specifies the scope ('scoped to your identifier'). This is a specific verb+resource with sibling differentiation.

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

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

Explicitly says when to use ('look up context the agent stored earlier') and provides examples ('ticker, address, notes'). It implies when not to use by omission of key (list all) and explicitly mentions sibling tools for saving and deleting. Context signals (e.g., 'without re-deriving from scratch') help guide decision-making.

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

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

Description discloses mark_read mutation, contradicting annotation readOnlyHint=true. Per rubric, contradiction yields score 1.

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

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

Front-loaded with purpose, contains two sentences that cover key info without unnecessary detail. Could be slightly more concise 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?

Covers purpose, parameters, mark_read behavior, and alternative endpoint. Despite no output schema, describes returned fields sufficiently 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?

Adds value beyond schema with examples (e.g., 'sec_8k') and explanation of mark_read purpose. All 5 parameters are covered and contextualized.

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 'Pull fired events from your subscription feed' describing specific action and resource. However, does not explicitly differentiate from sibling tools like 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?

Provides context on filtering by type/since, mark_read behavior, and mentions polling and alternative endpoint. Does not explicitly state when not to use, but 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 adds significant behavioral detail beyond the annotations (readOnlyHint, openWorldHint, etc.). It explains the fan-out logic, GDELT→GNews fallback, USPTO soft-fail, and return structure (changes[], total_changes, citation URIs). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads example queries, then explains the mechanism, parameters, and return format. Every sentence is informative and 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?

Despite no output schema, the description adequately describes the return type (changes[], total_changes, citation URIs). It covers edge cases (GDELT fallback, USPTO soft-fail) and provides enough detail 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% (all parameters described). The description adds practical usage details: 'since' accepts ISO dates and relative shorthand (e.g., '30d', '3m'), 'value' accepts ticker or CIK. This goes 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 tool's purpose: a change feed for a company over a recent window. It provides example queries ('what's new with X', 'latest on Y') and explicitly distinguishes from the sibling tool 'entity_profile', which returns a static 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?

The description explicitly tells when to use this tool vs. the alternative 'entity_profile' ('Use entity_profile instead when you want the static profile...'). It also explains the data sources and fallback behavior, giving clear context for appropriate 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?

Discloses scoping by identifier, persistence differences for authenticated vs. anonymous sessions, and idempotent nature (implied). Adds value 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?

Five sentences, no waste. Front-loads purpose, then usage, then technical details.

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

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

Covers purpose, usage, persistence, sibling tools. Complete for a simple write 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?

Schema coverage is 100% with descriptions. Description adds example key formats and expands on value as any text.

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

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

Description clearly states 'Save data the agent will need to reuse later' – a specific verb and resource. It distinguishes from sibling tools like recall and forget.

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

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

Explicitly describes when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' Pairs with recall and forget.

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. Description adds concrete behavioral detail: each call cascades through multiple endpoints, replaces 2-3 manual lookups, auto-disambiguates company input, and returns specific fields plus citation URIs. This provides operational context beyond the annotations.

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

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

Description is a single paragraph but well-organized: starts with intuitive query patterns, states the primary directive, then details each type. It is fairly concise given the amount of information, though a bullet list for entity types might improve scannability. No unnecessary 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?

For a tool with 2 simple parameters, rich annotations, and no output schema, the description covers purpose, when-to-use, each type's return structure, and internal complexity. It lacks explicit error handling or edge cases, but the openWorldHint and resolver nature make this acceptable.

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

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

Schema covers both parameters with descriptions. The description greatly enriches meaning: for 'type', it lists the two enum values and details what each returns; for 'value', it gives examples (ticker, CIK, name; brand, generic) and mentions auto-disambiguation. This added context is essential for correct usage.

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

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

Description begins with concrete query patterns users might type, then states the core purpose: resolving a name to a canonical identifier. It lists supported entity types with specific outputs (ticker+CIK for company, RxCUI for drug), making the tool's scope and action very clear. It implicitly distinguishes from siblings like 'entity_profile' or 'compare_entities' by being the first step for name-to-ID conversion.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID,' which is strong when-to guidance. It enumerates supported types and explains the internal cascade that replaces manual lookups. However, it does not explicitly say when not to use (e.g., if ID already known) or compare to specific sibling tools for alternative workflows.

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, so safety profile is clear. The description adds behavioral details: probes each entity with 'ai_visibility_check', ranks by score, returns score/confidence/signal density. 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 two sentences, front-loaded with the main action, and every sentence is meaningful. No wasted words; it efficiently conveys purpose, mechanism, and output.

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 (4 parameters, no output schema), the description provides sufficient context: explains the probing mechanism, ranking, and return fields. It could be slightly more precise about output structure, but overall it's complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds value by explaining that the first entity is treated as the 'subject' for narrative, which is not in the schema. This extra context justifies a score above 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 uses specific verb+resource ('Compare AI visibility across multiple entities side-by-side') and clearly distinguishes from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison). The competitive marketing audit example solidifies the purpose.

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

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

The description explicitly states when to use the tool (competitive AI-marketing audits) and provides a concrete use case. It implies not to use for single-entity checks (use 'ai_visibility_check' instead) but lacks an explicit 'when not to use' statement.

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 context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. 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?

Single paragraph but packed with information; every sentence provides value. Slightly long but efficient and well-structured. Front-loaded with primary purpose.

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

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

Despite no output schema, the description enumerates return fields (is_latest, license, etc.), mentions per-advisory detail, links, alternative versions. Covers failure behavior, limitations (NPM only in v1), and guidance for other ecosystems. 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% (both 'package' and 'version' described). Description adds that 'package' accepts scoped packages (e.g., @types/node) and 'version' defaults to latest published when omitted. This adds value beyond the schema.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, combining deps.dev (license, advisories, version history) and bundlephobia (size, dependencies, ESM support). It distinguishes from siblings by specifying NPM ecosystem only and referencing fallback tools for other ecosystems.

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"'. It also specifies when not to use (non-NPM: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return fields (dataset_ids, titles, themes, record counts) and the nature of keyword-based search. There is 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 consists of two concise sentences that front-load the core purpose and immediately follow with actionable return details. No extraneous information, 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?

With full schema coverage, helpful annotations, and no output schema, the description adequately explains the tool's input, return values, and integration with other tools (query/dataset_info). It could optionally mention pagination details, but offset parameter is in 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?

The input schema covers all three parameters (limit, query, offset) with descriptions. The tool description does not add additional semantic meaning beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states it searches Paris Open Data for datasets by keyword, listing specific example topics (city services, mobility, trees, events, urban planning & environment) and specifies the return value (dataset_ids, titles, themes, record counts). This distinguishes it from sibling tools like 'dataset_info' and 'query'.

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 mentions that returned dataset_ids can be passed to 'query' or 'dataset_info', implying a workflow for further data access. While it does not explicitly state when not to use this tool, the purpose is clear and the context for usage is well-defined.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds valuable internal details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag. 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?

Well-structured with front-loaded purpose. Each sentence adds value, but could be slightly tightened (e.g., combining some technical details). No redundant statements.

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

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

Given no output schema, description fully explains return values (passages with offsets and similarity scores). Covers constraints (200K cap, truncation), technical details (embeddings, window size), and paired tool. Comprehensive for a search tool.

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

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

Schema coverage is 100%. Description adds meaning: explains text as 'already pulled' content, query as natural-language, and limit as top-N passages. Also describes return format (passages with offsets and scores) beyond schema.

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

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

Clearly states 'Semantic search INSIDE a fetched record' and gives concrete examples (SEC 10-K, article, tool result). Distinguishes from sibling tools by naming ask_pipeworx_grounded and explaining when to use each.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt'. Explains the benefit (saves context, returns only relevant passages). Mentions pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use examples, but context is clear.

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

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

Annotations already indicate non-read-only, non-destructive, and idempotent behavior. The description adds valuable behavioral details: OAuth requirement, delivery channel limitations (SMS cap, webhook auto-disable after 10 failures), and webhook signing secret returned once. No contradiction with annotations.

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

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

The description is relatively long but well-structured: starts with purpose, then prerequisites, then types with examples, then delivery details. Every sentence adds useful information. Could be slightly more concise, but the structure is clear and front-loaded.

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

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

Given the complexity (nested objects, no output schema), the description is comprehensive. It covers prerequisites, subscription types with examples, and all delivery options with constraints. It mentions the return value (subscription id) and provides enough context for correct invocation.

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

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

The schema covers all 3 parameters with 100% description coverage. The description goes beyond schema by providing concrete examples for each subscription type (e.g., sec_8k with item codes) and elaborating on delivery webhook behavior (signing, auto-disabling). This significantly aids 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 action ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the output ('Returns the new subscription id'). It effectively distinguishes this tool from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description provides extensive usage context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and details delivery channels (always-on feed, optional email/SMS/webhook) with constraints (SMS verification, 10/day cap, webhook HMAC signing). Although it doesn't explicitly state when not to use, the specificity allows an agent to choose appropriately.

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 that output includes 'exact tool + argument shape' drawn from a live catalog, that calling with no arguments gives full spread, and optional topic filtering—adding significant value beyond the readOnlyHint, openWorldHint, idempotentHint, destructiveHint 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?

Description is detailed and front-loaded with alternative phrasings, but slightly verbose. Each sentence serves a purpose, though a minor reduction in length could improve conciseness.

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

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

Given the tool's role as an onboarding entry point, one optional parameter, no output schema, and the need to explain complex output (bucketized questions with tool+argument shapes), the description is thorough and self-sufficient.

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

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

Adds meaning beyond the schema by listing possible topic values (finance, pharma, etc.) and explaining omission behavior ('Omit for a cross-category spread'). Schema coverage is 100%, but description enhances utility.

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

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

The description clearly states the tool returns category-bucketed example questions, with a strong verb phrase ('returns category-bucketed example questions') and distinguishes itself as the onboarding entry point, differentiating from sibling tools like ask_pipeworx or 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 says to use this 'FIRST when you do not yet know what Pipeworx can do' and to learn how to call meta-tools, providing clear context. However, it does not explicitly state when not to use it, which is a minor gap.

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 significant behavioral context beyond annotations: ownership enforcement, soft deactivation (not deletion), and preservation of historical events. It aligns with all annotation hints (idempotent, not destructive).

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

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

Two sentences, front-loaded purpose, zero wasted words. Every sentence adds essential value.

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

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

For a single-parameter tool with annotations, the description covers all relevant behavioral aspects (ownership, deactivation vs deletion, link to recent_alerts). No missing elements.

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 describes the parameter as a subscription id from subscribe. The description merely restates 'by id' without adding new meaning, so the 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 states a specific verb ('Cancel') and resource ('a subscription by id'), clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Ownership enforcement is explicitly stated ('you can only cancel your own subscriptions'), providing clear usage context. It implicitly warns against canceling others' subscriptions but does not name alternative tools for that case.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral context: it verifies against SEC EDGAR + XBRL, returns a verdict with multiple types, includes structured form, actual value with citation, and percent delta. It explains that it replaces 4-6 sequential calls. No contradiction.

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

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

The description is moderately long but well-structured with parentheses for examples and specifications. Some redundancy exists (list of user intents), but overall it is clear and front-loaded with the tool's purpose. It could be slightly more concise but is effective.

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

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

Given the single parameter, absence of output schema, and rich annotations, the description fully covers what the tool does, its return values, domain scope, and its utility. It is complete for the complexity of 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?

There is only one parameter 'claim' with schema description coverage at 100%. The schema already describes it as a natural-language factual claim with examples. The description adds minimal extra value beyond the schema, providing additional examples but not essential semantics not already covered.

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 identifies the tool as a natural-language claim verification tool, providing specific examples of user intents and stating it is for company-financial claims. It distinguishes from siblings by explaining that it replaces multiple sequential calls.

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

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

The description explicitly states when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain scope (company-financial claims for public US companies), implying when not to use it. It does not provide explicit alternatives 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.