Openagenda

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

Discloses that _apiKey is passed directly to Anthropic (BYO key, pay them), and that the default model is free. Describes return structure (per-model score, confidence, signals, raw_response). Annotations already cover readOnly, idempotent, not destructive; description adds valuable context beyond annotations.

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

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

Three concise sentences with no fluff. First sentence states core purpose, second adds model/key details, third lists use cases. Well front-loaded and efficient.

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

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

Provides a clear picture of tool behavior, parameters, and output structure. Lacks error handling or rate limit info, but for a read-only probing tool with no output schema, it is sufficient and informative.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds minimal extra meaning beyond the schema, e.g., default model and key usage, which is more about behavior than parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool probes LLMs for AI visibility and scores per model (0-100), with specific verb 'Probe' and resource 'LLMs'. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring rather than presence scanning.

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

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

Explicitly mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also clarifies when _apiKey is needed (for Anthropic probe). Does not explicitly state when not to use or contrast with similar tools, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, so safety is covered. The description adds behavioral context: routes to 4,552 tools, returns structured answers with citation URIs. It does not contradict annotations. Could mention rate limits or response size but sufficient.

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

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

Description is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and uses bullet-like structure with examples. It is somewhat verbose but every sentence adds value; could be slightly trimmed but remains efficient.

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

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

Given the tool's complexity (routing to many sources), the description covers purpose, usage guidelines, parameter semantics, and alternatives. No output schema exists, but the description mentions 'structured answer with citation URIs,' which is adequate. It provides a complete mental model for selection and invocation.

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

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

Schema coverage is 100% (6 params, all aliases for question), so baseline is 3. The description adds: 'Your question or request in natural language. Accepts query, q, prompt, text, input as aliases.' This clarifies parameter usage beyond schema, supporting ease of use.

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

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

The description clearly states the tool routes factual questions to structured data sources, provides specific examples, and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. It uses specific verb+resource ('routes the question to the right one of 4,552 tools') and clarifies it covers authoritative data with citations.

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 (for factual questions, 'START HERE for most questions'), when not to use (for breaking news, though it can handle it), and provides alternatives: ask_pipeworx_grounded for single grounded answers, deep_research for multi-part questions. Also gives example question types.

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 costs (one extra LLM call), return structure with evidence and refusal reasons, and does not contradict annotations (readOnlyHint, etc.).

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

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

Well-structured and front-loaded with key purpose, but slightly verbose with detailed refusal reasons that could be compressed.

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?

Thoroughly covers usage context, behavior, refusal modes, and return format (since no output schema), leaving no important gap.

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

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

Schema coverage is 100% with descriptions for all parameters; description only restates alias information, adding marginal value beyond the schema.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, explains the process of routing and extracting only from tool results, and distinguishes from sibling ask_pipeworx for casual lookups.

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

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

Explicitly says when to use (when answer will be quoted/cited/acted on, in domains like financial/legal/medical) and when not to ('prefer ask_pipeworx for casual lookups'), with clear 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?

The annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: fan-out to category-specific data packs, response shapes with specific fields, resolver contract with confidence levels and alternatives, parent event extractor, news fallback handling, and resolution-rule risk. It discloses that low-confidence resolutions short-circuit and closed markets return specific statuses. 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 lengthy but well-structured: it starts with a clear statement of purpose, then classifiers, examples, response shapes, resolver contract, parent event, news fields, safety, and resolution risk. Every section adds necessary detail for correct tool usage. It is not excessively verbose given the complexity, but some redundancy (e.g., repeating status codes) could be trimmed.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers input formats, output fields (result.market, result.analysis, result.evidence), resolver contract, parent event extraction, news fallback, safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. It equips the agent to handle edge cases and interpret results 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 three parameters described). The description adds significant value beyond schema: it explains the difference between depth values ('quick' vs 'thorough'), elaborates on market input formats with examples, and details include_raw behavior (summarized vs full payloads). However, since schema already has adequate descriptions, this is slightly above baseline but not the highest.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action, input types, and output components (evidence packet + market-vs-model comparison). It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on research rather than edge calculation or arbitrage.

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

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

The description explicitly says when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifiers, input examples, and detailed guidance on inspecting market_match_confidence, parent_event, and resolution-rule risk before trusting results. It also explains safety mechanisms like low-confidence short-circuit and closed market handling.

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

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

Annotations already indicate safe, idempotent read operation. Description adds rich behavioral context: parallel call, data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and citation URIs. No contradictions.

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

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

Description is relatively long but well-structured: starts with common queries, then core action, then type-specific details. Every sentence is informative. Could be slightly tighter, but value density is high.

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 two types, multiple entities, and sorting, the description covers inputs, data sources, behavior, and output format (paired data + URIs). No output schema exists, but description mentions return elements. Complete enough for selection.

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

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

Schema coverage is 100% (baseline 3). Description adds concrete examples (e.g., 'AAPL','MSFT' for company, 'ozempic','mounjaro' for drug) and explains that company values are tickers/CIKs, drug values are names. Also clarifies sorting behavior. Adds meaning beyond schema.

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

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

Description starts with intuitive query patterns and clearly defines the tool as side-by-side comparison of 2–5 companies or drugs. Distinguishes from sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives typical use cases. Does not mention when not to use, but given specificity, it's adequate.

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 account requirements, paid restrictions, return format (findings packet with gaps[]), non-open-web nature, and limitations for current events. Adds significant context beyond annotations (readOnlyHint, idempotentHint).

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

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

Each sentence adds value; critical information is front-loaded (account requirement, alternative tool). Length is justified by the tool's complexity, and structure is logical.

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 output format (findings packet with evidence, source, gaps[]). Covers usage conditions, limitations, and expectations, making it 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%, so baseline 3. Description adds clarity on paid plan restriction for 'thorough' depth and explains facet counts per depth level, slightly enhancing schema 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 defines the tool as a grounded multi-source research tool across structured data, distinguishing it from open-web search and sibling tools like ask_pipeworx. It specifies the decomposition and parallel execution process.

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 this tool vs. alternatives: use ask_pipeworx if not signed in, for single lookups, or for breaking news. Provides detailed context on account requirements and expected time.

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 safe read-only idempotent behavior. Description adds specifics about return content (top-N tools with schemas, examples, ready to call) 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?

Well-structured with purpose first, but somewhat long. Every sentence adds value; no wasted words.

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

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

Despite no output schema, description fully explains what is returned (tools with schemas, examples, ready to call). Also gives usage ordering advice, which is complete for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats schema info (natural language query, aliases) but does not add significant new meaning beyond examples.

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

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

The description clearly states the verb 'discover' and resource 'tools', lists many domains, and distinguishes 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?

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set', providing clear usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: fans out across multiple data sources, lists specific return fields, mentions that patents may soft-fail due to sunset, and includes URIs for filings. 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 fairly long but front-loads with user-facing examples and organizes information logically (examples, general purpose, then detailed breakdown of outputs). It is efficient given the complexity of the tool, though some repetition (e.g., 'company' mentioned multiple times) could be trimmed.

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

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

No output schema exists, so the description must explain return values. It does so by listing all major data categories (cik, filings, fundamentals, patents, news, LEI) and notes the patents sunset. While it could mention display formats or limits, it covers the essential output for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond the schema: value examples ('AAPL', '0000320193'), clarification that names are not supported, and reinforcement of the type enum. This lifts the score to 4.

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

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

The description begins with concrete example queries ('Tell me about X', 'research Acme'), defines the tool as providing a holistic cross-source profile of US public companies, and distinguishes it from sibling tools like resolve_entity. The verb 'profile' and resource 'entity' are clearly stated.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and 'Names not supported — use resolve_entity first', providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld hints. Description adds default behavior (upcoming only), return fields (title, dates, venue, coordinates, keywords), and language fallback (English/French). 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?

Two sentences: first states core function and prerequisite, second covers defaults, filters, and return fields. Every sentence is informative and essential.

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 annotations covering safety/idempotency and schema covering parameters, description completes by explaining return values, language behavior, and default date scope. No output schema needed given the clear return description.

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

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

Schema has 100% description coverage. Description adds value by explaining default behavior for date parameters (upcoming) and that query is a keyword filter. Language note adds context not in 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 it lists events from one OpenAgenda agenda, references the sibling tool search_agendas to obtain the uid. Distinguishes itself from siblings by specifying the resource (events) and the context (from a single agenda).

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 context: get uid from search_agendas first, defaults to upcoming events, optional filters. Does not mention when not to use, but the sibling set contains no alternative for listing events from an agenda.

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

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

Annotations already declare destructiveHint=true, so the description's 'delete' is consistent but adds little beyond that. The description does not specify behavior for non-existent keys or confirm idempotency, which are known via annotations but not elaborated.

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?

Extremely concise: one sentence for purpose, one for usage. No wasted words; front-loads the action.

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

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

Given the tool's simplicity (one param, no output schema, annotations present), the description covers purpose and usage adequately. Could add a note on behavior for missing keys, but not a major gap.

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

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

Schema coverage is 100%, and the description's 'by key' adds no new meaning beyond the schema's 'Memory key to delete' description for the key parameter. Schema already handles parameter documentation.

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 'delete a previously stored memory by key', specifying verb and resource. The mention of pairing with 'remember' and 'recall' distinguishes it from sibling tools with complementary roles.

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

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

Provides explicit use cases (stale context, task done, clearing sensitive data) and mentions pairing with related tools. Lacks explicit 'when not to use', but the given context is sufficient for appropriate selection.

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

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

The description details the steps (fetches page, extracts title/description/key links, emits markdown) and confirms non-destructive, idempotent behavior, aligning with annotations and providing clarity beyond them.

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

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

The description is well-structured with a clear lead sentence, followed by details and use cases. Every sentence earns its place, though slightly verbose.

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

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

Given the simple input schema and no output schema, the description sufficiently explains the output format (single text blob in markdown) and the tool's behavior, making it complete 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?

Schema coverage is 100%; description does not add new meaning beyond the schema for url and max_links, meeting the baseline.

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

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

The description clearly states it generates an llms.txt file from a URL, specifies the output format and use cases, and distinguishes it from sibling tools like ai_visibility_check or deep_research.

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

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

It provides explicit use cases (get client site indexed, draft llms.txt, audit competitor) but does not explicitly state when not to use it, though the context implies it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that it lists active subscriptions by default and mentions the include_inactive parameter, aligning with annotations without contradiction.

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

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

Two concise sentences: first defines purpose and output, second gives guidance. No unnecessary words, well-structured 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?

For a simple read-only list tool with one optional parameter, the description covers purpose, return fields, and usage guidance. Annotations handle safety. No output schema needed.

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

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

Schema coverage is 100% with a clear parameter description. The description reinforces the default behavior ('active' implies include_inactive=false) but adds little beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with verb, resource, and scope. Specifies returned fields, distinguishing it from subscription management siblings like subscribe and unsubscribe.

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

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

Provides explicit usage scenarios: 'review what you're monitoring before adding more or to find an id to cancel.' Implicitly suggests alternatives (subscribe/unsubscribe) via context of 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?

Discloses beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and team reads digests daily. 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?

A single paragraph, front-loaded with purpose, and concise. Every sentence adds value without 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?

Covers all necessary aspects for a feedback tool: what to include, format, constraints, and outcome. Output schema is not needed.

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

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

Schema coverage is 100%, but the description adds extra context: elaborates on type enum values and advises to describe issues in terms of tools/packs, not paste prompts.

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

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

The description clearly states the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It is distinct from sibling tools, none of which are for feedback.

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

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

Explicitly specifies when to use (for bugs, missing features, data gaps, praise) and what not to do (don't paste end-user prompt). Also provides guidance on format, rate limits, and that it's free.

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. The description adds value by disclosing it's self-aggregating from CF analytics, no PII included, and caching behavior (5min-1h depending on window). No contradiction with annotations.

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

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

The description is concise with no wasted words. It uses a clear structure: opening statement, then what is returned, then bullet-point use cases, then technical notes. Every sentence adds value.

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

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

Given no output schema, the description adequately explains the return values (top tools, top packs, total call volume) and the data source (CF analytics, no PII). It also mentions caching. This is sufficient for an agent to understand what the tool provides.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the right window.

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

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

The description starts with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It then enumerates exactly what is returned (top tools, top packs, total call volume) and the windows. This clearly distinguishes it from siblings like 'discover_tools' or 'suggest_questions'.

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

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

The description explicitly lists three use cases (discovering hot data, confirming canonical tool, aligning use case). While it does not state when not to use it, the provided contexts are clear and practical, giving the agent 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 extensively details internal checks (monotonicity, partition sum, Jaccard similarity, placeholder filter, fill check) and warns about non-actionable outputs when realizable edge is ≤ 0. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent and the description enhances them with concrete 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 detailed but not overly verbose; it front-loads the core purpose and then progressively details modes and checks. While it could be slightly more structured with bullet points, it remains readable and 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 clearly outlines the response structure (opportunities array, partition_check, fill check with fields) and covers all aspects: inputs, modes, internal logic, and output details. It is fully complete for a complex arbitrage detection tool.

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

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

Schema coverage is 100% and both parameters are described in the schema. The description adds value by explaining the modes, recommending usage, and noting that full Polymarket URLs are accepted, which is not in 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (default trending scan, event-specific, and cross-event topic), each with clear resource and action.

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

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

The description provides explicit guidance on when to use each mode: no args for a top markets scan, event for a specific market (recommended), and topic for cross-event scanning. It also explains when not to trade based on the fill check. However, it does not contrast with sibling tools like polymarket_edges or polymarket_kalshi_spread, which could help agents decide between them.

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 the annotations: explains caching (1h KV-level), output structure (by_segment with three segments, fed_candidates, diagnostics), and detailed methodology for each model family (e.g., 24h-move warning). Annotations (readOnlyHint, etc.) are consistent and 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 very long and dense, packed with technical details about models and knobs. While front-loaded with purpose, it could be more concise by summarizing core functionality and moving details to the parameters. It is not overly verbose but suffers from information overload.

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

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

Given no output schema, the description explains the output structure thoroughly (segments, diagnostics). It covers the behavior of each model family and knobs. However, it might be overwhelming for an agent to parse efficiently, slightly reducing completeness.

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

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

With 100% schema description coverage, the baseline is 3. The main description does not repeat parameter details, but the schema descriptions are already good. The description adds context about tradeable-edge filters (e.g., 'Set to 5000 to drop thin-book opportunities') which adds marginal value.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb and resource, and distinguishes from siblings like 'polymarket_arbitrage' by focusing on Pipeworx-driven edge detection.

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 targets the use case 'what should I bet on today' and explains that agents can 'discover opportunities without paging hundreds of markets.' It provides guidance on knobs for filtering, but does not explicitly state when not to use it or compare to alternative 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it explains the source (daily snapshots from polymarket_edges), the 60-day TTL bound on history, and that decay is computed from daily closes not intraday. 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 reasonably concise given the complexity. It front-loads the purpose, then explains the response structure, and ends with limits. Some sentences could be more terse, but overall each sentence serves a purpose.

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

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

Given no output schema, the description comprehensively explains the return structure (tracked[], expired[], snapshot_dates[]) with details on each field, covers limits (60-day TTL, decay from daily closes), and describes both parameters. This is 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?

The input schema already covers both parameters with clear descriptions (days lookback, window family). The description repeats the default for window but adds the detail 'snapshot family'. With 100% schema coverage, the description adds minimal extra meaning beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verb+resource (edge persistence and decay telemetry) and distinguishes from siblings like polymarket_edges by focusing on historical time-series rather than current edges.

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

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

The description explains when to use the tool (to understand edge age and trend) and contrasts a fresh wide edge vs. an old one, implying when the historical context matters. However, it does not explicitly state when not to use it or name alternative tools, which would improve clarity.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent with description. The description adds behavioral details like walking the order book ladder, returning fill details and verdicts, and warning about thin legs.

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

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

The description is well-structured with clear sections but is somewhat verbose. However, every part adds value, so it's acceptable.

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

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

Given complexity (two modes, many return fields) and no output schema, the description is very complete, listing all return fields and explaining verdicts and risks.

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

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

Schema description coverage is 100%. The description explains parameter usage in context: single-market vs basket, default values, and meaning of size_usd for buys vs sells, adding significant meaning.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific outputs for 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 says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns about partial basket fills converting arb into unhedged directional position.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint. Description adds extensive context: responses include leg-by-leg prices, spread calculations, safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons. No contradictions; description layers helpful detail 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?

Well-organized with clear sections but somewhat verbose; repeats topic shortcuts already in schema. Front-loaded key ideas. Could be slightly trimmed without losing information.

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

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

Despite no output schema, the description explains return values comprehensively: leg prices, spreads, safety fields. Covers edge cases (compatibility_warnings, temporal alignment) and potential pitfalls. All necessary context for correct usage is present.

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

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

Schema has 100% description coverage for three parameters. Description elaborates on modes: topic shortcuts are listed, explicit override behavior explained. Examples provided. Adds significant meaning beyond schema, clarifying how parameters interact.

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

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

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket. Two modes (topic and explicit) are described. While it doesn't explicitly differentiate from sibling polymarket_arbitrage, the specific resource and scope are unique and well-defined.

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 guidance on when spreads are meaningful (compatibility_warning conditions, temporal alignment). Warns that pre-mapped topics may not always be tradable. Does not explicitly contrast with alternative tools like polymarket_arbitrage, but gives sufficient context for interpretation.

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 and idempotentHint. Description adds behavioral details: two modes (value retrieval vs list), scoping, and pairing with other tools. No contradiction. Minor additional 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?

Very concise: two sentences plus a short paragraph. Front-loaded with the main action. Every sentence serves a purpose with no fluff.

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

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

Given no output schema, the description gives concrete examples and explains the two modes. It's mostly complete for a simple retrieval tool, though return format details are minimal.

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 schema already describes the parameter. Description adds context about omitting key to list all keys and gives examples, but does not add significant new meaning beyond what schema provides.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if key is omitted. It distinguishes from siblings (remember, forget) and provides concrete examples of use cases (ticker, address, notes).

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

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

Explicitly states when to use (to look up stored context), and pairs with remember and forget as alternatives. Also notes scoping to identifier, providing clear guidance on context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description complements these by explaining that the tool returns raw event payloads, supports mark_read to track read status, and accesses a persisted feed. This adds contextual behavior without contradicting the annotations.

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

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

The description is concise, with every sentence earning its place. The first sentence states the core action, and the second extends with return details, filtering, and alternative access. No fluff or redundancy.

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

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

Given the tool has 5 optional parameters and no output schema, the description covers the essential functionality: what is returned, how to filter, and the mark_read behavior. It is nearly complete, though it could mention pagination behavior beyond the 'limit' parameter.

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 parameters with descriptions, so baseline is 3. The description adds value by providing an example for the 'type' parameter ('sec_8k') and explaining the side effect of 'mark_read' (flagging events as read). This enhances the semantic understanding beyond the schema alone.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource combination. It further details the return fields and filtering options, making the purpose unmistakable. It implicitly distinguishes from sibling tools like 'events' or 'recent_changes' by narrowing the scope to subscription-feed alerts.

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

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

The description offers usage guidance by noting 'Polls work fine' and providing an alternative access method for scripts/dashboards. However, it does not explicitly contrast with sibling tools like 'events' or 'list_subscriptions', which would further help the agent decide when to use this tool.

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

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

The description discloses key behavioral traits beyond annotations: it fans out to SEC EDGAR, GDELT/GNews, and USPTO sources, explains fallback logic and soft-failure conditions, and describes the return structure (changes[], total_changes, citation URIs). This adds significant context to the readOnlyHint and idempotentHint 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, dense paragraph with no wasted sentences. It front-loads the purpose with user-centric examples, explains internal behavior, parameter details, return format, and an alternative—all efficiently organized.

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 covers the return structure, source fallback, failure handling, and parameter semantics. It provides enough detail for an agent to use the tool effectively without needing additional 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?

With 100% schema coverage, baseline is 3, but the description adds value by providing concrete examples (e.g., '7d', '30d') and clarifying the 'since' parameter's relative shorthand format, which enhances understanding beyond the schema's standard description.

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

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

The description clearly defines the tool's purpose with example queries ('What's new with X') and explicitly states it returns a change feed for a company in the last N days/weeks/months via a single parallel call. It distinguishes itself from sibling tool '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?

The description provides explicit guidance on when to use this tool (for dynamic changes over a window) and when to use 'entity_profile' instead (for static profile). It explains fallback between GDELT and GNews, but does not include explicit 'do not use' scenarios, though the alternative is clear.

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

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

Annotations (idempotentHint=true, destructiveHint=false) are complemented by description adding scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions.

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 wasted words, purpose first, then usage, then behavior. Efficient and clear.

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?

Tool is simple (2 required params, no output schema). Description covers purpose, usage, behavior, and persistence, which is complete for this tool type.

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 formatting examples and broadens value scope (findings, addresses, preferences, notes), adding value beyond schema.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific examples (resolved ticker, address, preference). Distinguishes from siblings 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 says when to use ('discover something worth carrying forward') and pairs with recall/forget. Lacks explicit 'when not to use' but provides sufficient context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it cascades through multiple internal endpoints (replacing 2-3 manual lookups), and it provides specific return fields per type. No contradictions.

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

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

The description is moderately long but every sentence is informative—examples, use-case framing, supported types, internal behavior, and return values are all included. Well front-loaded with query patterns. Minor redundancy (SUPPORTED TYPES repeats) but overall efficient.

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

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

Despite lacking an output schema, the description fully documents the return fields for each entity type, including citation URIs. It explains internal cascading behavior and justifies its value (replaces manual lookups). For a lookup tool with 2 simple params and no nested objects, this is exhaustive.

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 params described in schema). Description adds real meaning beyond schema: concrete examples of valid inputs (AAPL, 0000320193, 'ozempic', 'metformin') and clarifies auto-disambiguation. This helps an agent form correct queries.

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

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

The description uses specific verbs ('resolve') and resources ('name to canonical identifier'), includes concrete examples (ticker, CIK, RxCUI), and clearly differentiates from siblings by framing it as the first step for name-to-ID conversion. The purpose is unmistakable.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID.' The supported types section clarifies when to use it for company vs. drug lookups. Could be stronger by explicitly stating when not to use (e.g., if you already have an ID), but the context and sibling list imply that.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining that the tool probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density. It does not detail auth requirements beyond the models parameter, but the annotations provide sufficient safety 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: two sentences that front-load the main action and then provide use case and output details. Every sentence is informative with no redundancy.

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

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

Given the tool's moderate complexity, full schema coverage, and no output schema, the description provides sufficient information for an agent: it explains the process (probing with ai_visibility_check), the output structure (ranked list with score, confidence, signal density), and a concrete use case. No gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that the first entity in the 'entities' array is treated as the 'subject' for narrative and the rest as competitors. This is useful additional context.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using 'compare' as the specific verb and specifying the resource as 'AI visibility'. It distinguishes from siblings like ai_visibility_check by mentioning side-by-side comparison and ranking.

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

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

The description gives a clear use case ('competitive AI-marketing audits') and an example question, but does not explicitly state when not to use this tool or mention alternative tools. However, the context is implied well.

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 safe/idempotent behaviors. Description adds crucial context: partial failures, bundlephobia measurement delay (5-30s), and graceful degradation with sources_failed list.

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?

Packs extensive info into a few sentences, but the dense paragraph structure could be more readable. Still efficient and front-loaded.

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

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

Despite no output schema, description fully details return fields, error behavior, and ecosystem scope. Completes the agent's understanding.

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

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

Schema covers both parameters fully, but description adds valuable detail: scoped packages accepted for 'package', and 'version' defaults to latest. This goes 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's a composite check for adding an npm package, covering safety, popularity, and size. It distinguishes itself from sibling tools as the only one focused on package evaluation.

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 (agent asks about safety/popularity/size) and when not (non-NPM ecosystems). Provides alternatives for other ecosystems.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful behavioral context: it returns limited fields (uid, slug, title) and notes that most agendas are French, which is not in annotations. No contradictions.

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

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

The description is concise—three sentences, front-loaded with the core purpose. Every sentence adds value: what it does, what it returns, and a practical note. 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 search tool with no output schema, the description adequately states return fields and usage (pass uid to events). It does not describe error conditions or pagination, but given the tool's simplicity and high annotation coverage, it is sufficiently complete.

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

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

Schema coverage is 100%; all three parameters have clear descriptions. The description does not add additional meaning beyond the schema. It reinforces the purpose of the 'query' parameter with examples but adds no new semantic detail for parameters.

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

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

The description clearly states the tool finds OpenAgenda agendas by keyword, lists the returned fields (uid, slug, title), and explains how to use the result (pass uid to events tool). It distinguishes from sibling tools like 'events' and 'search_within' by specifying it's for agendas.

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

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

The description gives concrete keyword examples and directs the user to pass the uid to the events tool, providing clear usage context. However, it does not explicitly state when NOT to use this tool or mention alternatives among the long sibling list.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' Also mentions return of passages with offsets and similarity scores. No contradictions.

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

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

Two paragraphs; front-loaded with core purpose ('Semantic search INSIDE a fetched record'), followed by when-to-use and technical details. Every sentence adds value without redundancy. Lean and comprehensive.

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

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

Despite no output schema, the tool description explains return fields (passages with character offsets and similarity scores), the embedding model and window size, and the character cap. Given high annotation coverage, the description is complete for understanding behavior and usage.

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

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

Schema coverage is 100%. Description adds value beyond schema: explains text as 'already pulled,' provides natural-language query examples, and mentions the character cap. Schema already includes default for limit. Description enriches understanding but does not repeat 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 'Semantic search INSIDE a fetched record,' specifies the verb 'search' and resource, and provides concrete examples like SEC 10-K body, article, and long tool result. It distinguishes from siblings by mentioning 'Pairs with ask_pipeworx_grounded' and explicitly contrasts with fetching the whole document.

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: 'Use when the record is too big to cram into the prompt.' Provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' Implies when not to use (small records).

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?

Annotation idempotentHint=true contradicts the description's implication that each call creates a new subscription (returns new subscription id). The description does not mention idempotency or deduplication, leading to inconsistency. Score 1 due to 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 purpose, requirements, types, delivery. Some redundancy (e.g., delivery details repeated) but overall efficient. A few sentences could be trimmed without losing value.

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

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

Covers return value (subscription id), type definitions, delivery constraints. Minor gaps: no mention of subscription lifetime or how to manage via siblings, but acceptable given complexity and 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%, but description adds rich context: type-specific parameter examples (e.g., items codes for sec_8k), delivery options with format and limitations (e.g., webhook signing, auto-disable). Elevates 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 'Create a proactive monitoring subscription to a live-data event stream', identifying the verb (Create) and resource (subscription). It distinguishes from siblings like list_subscriptions (listing) and unsubscribe (removal). Supported types and delivery channels further clarify scope.

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

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

Provides explicit context: requires Pipeworx OAuth account, lists supported types with parameter examples, delivery options with caps and auto-disable. Does not explicitly contrast with siblings, but sibling list is available separately.

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

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

Annotations declare readonly, open-world, idempotent, and non-destructive. The description adds that it returns example questions with exact tool/argument shape from a live catalog. No contradictions; additional behavioral context is helpful.

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 slightly verbose but packs useful information. It front-loads alternative user queries and is well-structured. Could trim a few words, 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?

Given no output schema, the description thoroughly explains the output format (category-bucketed examples with exact tool+argument shape) and connects to sibling meta-tools. It is complete for an onboarding tool.

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

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

Schema covers the optional topic parameter with description. The description adds value by listing example values (e.g., 'finance', 'pharma') and explaining that omitting gives a full spread. This goes beyond the schema.

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

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

The description clearly states that the tool returns category-bucketed example questions for onboarding, with specific categories and optional topic focusing. It distinguishes itself from siblings like discover_tools by positioning as the first use entry point.

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

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

It provides explicit guidance: call with no arguments for full spread, pass topic to focus, and use as the first tool when unaware of Pipeworx's capabilities or to learn meta-tools. It does not explicitly list when not to use, but the guidance is strong enough.

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

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

Adds ownership enforcement and deactivation behavior beyond annotations. Aligns with destructiveHint=false and idempotentHint=true. Provides useful context.

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

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

Two sentences, minimal waste, front-loaded with action. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, and behavioral nuance completely.

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

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

Schema coverage is 100%; description mentions 'by id' but does not add new details beyond schema. Baseline score applies.

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

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

Clear verb 'Cancel' and resource 'subscription' with specific scope 'by id'. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement ('only cancel your own') and behavioral constraint ('deactivated, not deleted'). Does not explicitly mention when to use or alternatives, 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?

Description aligns with annotations (readOnly, idempotent, non-destructive) and adds detail on return values (verdict, actual value, citation, delta). No contradictions.

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

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

Description is thorough but slightly verbose. Front-loaded with key phrases and examples; each sentence adds value but could be trimmed.

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

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

Comprehensive for a single-parameter tool with no output schema; explains return values, domain limitations, and efficiency gains over alternatives.

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?

Single parameter 'claim' with 100% schema description coverage; description adds natural-language examples and clarifies it expects a factual statement. Adequate context beyond schema.

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

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

Description clearly states it verifies natural-language factual claims against authoritative sources, with specific examples and domain scope (company-financial claims). Distinguishes from siblings by mentioning 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?

Explicit instruction to use when checking factual correctness of user statements. Domain restriction to company-financial claims is implied, but no explicit when-not-to-use.

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