Avoindata Fi

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond annotations: it specifies the scoring range (0-100), the return structure (per-model details including raw_response), and the cost implications for Anthropic. 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 three sentences, front-loaded with the primary action, and each sentence adds essential information without redundancy. 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?

For a tool with 4 parameters and no output schema, the description adequately covers usage, parameters, and return format. It mentions per-model fields and combined view, which satisfies the need for understanding the output. No significant gaps.

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

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

Schema coverage is 100%, so the description adds marginal value. It reinforces the purpose of each parameter (entity, models, _apiKey, context) but does not provide significant additional detail beyond the schema descriptions. 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 probes LLMs for visibility of a business/brand/product/topic, returns scores 0-100 per model, and distinguishes itself from siblings by focusing on AI visibility audits and competitive monitoring.

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 context for when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model and optional Anthropic with BYO key. It does not explicitly state when not to use or mention alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about routing to 4,482 tools, returning pipeworx:// citation URIs, and working on all tiers. No contradictions. 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?

The description is relatively long but every sentence adds value. It is front-loaded with critical usage advice, then provides examples and alternatives. Could be slightly more concise but not wasteful.

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

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

Given the complexity of the tool (many sources, aliases, alternatives), the description is thorough. It explains purpose, usage, output format (structured citations), and comparisons with siblings. No output schema, but description implies return structure.

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 parameters described. The description provides example queries and mentions aliases, enhancing understanding. Baseline 3, plus extra examples justify a 4.

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

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

The description clearly states the tool routes questions to authoritative sources and returns structured citations. It uses specific verbs like 'routes' and 'returns' and explicitly contrasts with web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit when-to-use and when-not-to-use guidance. It directs to 'START HERE for most questions' and lists example queries. It also specifies alternatives for hallucination resistance (ask_pipeworx_grounded) and broad multi-part questions (deep_research).

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 readOnly and idempotent hints. The description adds valuable context: the tool extracts answers using only the tool result, lists exact return fields including refusal reasons, and notes the extra LLM call cost.

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

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

The description is front-loaded with key information and uses bullet-like structure. It is somewhat long but every sentence serves a purpose, with no redundancy.

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

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

Despite lacking an output schema, the description fully documents the return format (answer, evidence, confidence, etc.) and lists all possible refusal reasons. It also cost-compares with the sibling tool and covers failure modes.

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 confirms multiple aliases for the question parameter, but this adds minimal value beyond the schema's existing parameter 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling 'ask_pipeworx' by explaining the same routing but with a grounded extraction step.

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 when answers will be quoted, cited, or acted on in high-stakes domains (financial, legal, medical), and recommends preferring 'ask_pipeworx' for casual lookups due to extra cost.

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 disclosure numerous behavioral traits beyond the annotations: fan-out patterns, response shapes (market, analysis, evidence keys), resolver contract (confidence, score, alternatives, suggestions), parent event extractor, news fallback fields, safety shortcuts (low_confidence_match, market_closed_or_inactive), liquidity warnings, and resolution-rule risk parsing. No contradiction with annotations.

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

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

The description is very long (~500 words) but well-structured with sections and front-loaded purpose. While detailed, some content (e.g., extensive fan-out examples) could be more concise. Every sentence adds value, but verbosity reduces efficiency.

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 all response fields (market, analysis, evidence, resolver contract, parent event, news, safety, resolution-rule risk). It covers all necessary information for an agent to correctly interpret the output.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context for the 'market' parameter (slug, URL, question) and explains 'depth' and 'include_raw' effects, but these are largely redundant with the schema descriptions. No new parameter-level semantics beyond what schema already 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's purpose: researching a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, fanning out to data packs, and returning an evidence packet with comparison. It distinguishes from sibling tools like polymarket_edges by specifying use cases like 'should I bet on X'.

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

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

The description explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of fan-outs for different bet types. However, it does not explicitly state when not to use this tool or suggest alternatives from the sibling list.

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

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

The description adds significant context beyond annotations: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), notes handling of off-calendar fiscal years, states results are sorted by primary metric, and mentions citation URIs. All these details are valuable for understanding tool behavior and are consistent with annotations (readOnly, openWorld, idempotent).

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 concise, front-loading example queries for quick comprehension. While it covers necessary details, a few sentences could be tightened without losing meaning. Overall, it earns its length, but a slightly more streamlined version would score 5.

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 description must explain return values. It mentions 'paired data + pipeworx:// citation URIs per entity', which is helpful but somewhat vague. It could better describe the response format. However, given the tool's simplicity (comparison with sorting), the description covers most behavioral aspects adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of 'type' with specific data sources (e.g., 10-K revenue for company, adverse-event counts for drug) and provides examples for 'values' (tickers/CIKs vs drug names). This extra context enhances parameter understanding beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one call, using example queries like 'Compare X and Y' or 'rank these companies'. It distinguishes itself from siblings by noting it replaces 8–15 sequential lookups, making the purpose unambiguous and specific.

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 to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides example queries and contexts where the tool should be used, and implies not to use for single entities or different types. This clear guidance helps the agent select the correct tool.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds context by stating what the tool returns (full metadata with resources and resource_ids), but does not introduce new behavioral traits beyond what annotations provide.

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

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

The description is a single sentence with no unnecessary words. It is front-loaded with the verb and clearly communicates the tool's purpose and scope.

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 one parameter and no output schema, the description adequately covers the input source and output content. It mentions the inclusion of resources and resource_ids, providing sufficient completeness for an agent to understand the tool's 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?

The schema already describes the 'id' parameter with 100% coverage. The description adds value by clarifying that the parameter can be either an id or a name and that it comes from search_datasets, which is not explicit 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 verb 'Show', the resource 'full metadata for one Finland Open Data dataset', and the scope 'by id or name (from search_datasets)'. It specifies that the output includes all resources and resource_ids, distinguishing it from sibling tools like search_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 references 'from search_datasets,' implying a workflow where search_datasets is used first to obtain the id/name. This provides implicit guidance on when to use this tool. However, it does not explicitly state when not to use it or mention alternative tools for listing vs. details.

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. Description adds valuable context: decomposes questions into facets, routes to 4,482 tools in parallel, returns findings packet with verbatim evidence, confidence, source, citations, and gaps. Also mentions 15-60s response time.

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

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

The description is detailed but well-structured: starts with access requirement, then core functionality, usage guidance, output format, and performance. While not extremely concise, every sentence provides distinct value without redundancy.

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

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

Despite no output schema, the description fully explains the return format (findings packet with evidence, confidence, source, citation, gaps). It also covers limitations (not for breaking news, mostly empty gaps for non-catalog topics), gives example questions, and sets response time expectations.

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

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

Schema coverage is 100% for both parameters (question and depth). The description adds meaning by stating question should be broad/multi-part and that depth controls the number of facets (quick=3, standard=5, thorough=8). This goes beyond the enum labels.

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 Pipeworx's 1129 STRUCTURED data sources' and distinguishes it from open-web search. It also differentiates itself from sibling tool 'ask_pipeworx' by noting deep_research is for broad/multi-part questions over structured 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?

Explicitly states account requirement and that deeper depth tiers need paid plans. Provides clear alternatives: use ask_pipeworx if not signed in, or for single lookups and breaking news. Also advises against using for current news topics.

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

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

Annotations already cover readOnly, idempotent, and non-destructive nature. The description adds that it returns top-N relevant tools with full schemas and examples, ready to call. There's no contradiction; it supplements annotations with useful 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?

Two sentences, well-structured with front-loaded purpose and use cases. Contains no fluff, though slightly long. Each sentence earns its place. Minor deduction for length, but still 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 role as a discovery hub with many parameters and no output schema, the description fully covers what it does and why. Schema coverage and annotations fill gaps, making this complete for an agent to understand.

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?

All 6 parameters have schema descriptions (100% coverage). The description adds meaning by explaining the query field with aliases and examples, and the limit parameter's default and max. It goes beyond schema by showing usage patterns.

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 finds tools by describing a task or data, listing many domains. It distinguishes itself from sibling tools by emphasizing it returns ready-to-call tool definitions with schemas, which is specific and actionable.

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...' and 'Call this FIRST when you have many tools...'. This provides clear context and when not to use (if you already know the tool), and implies alternatives like direct tool calls.

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 behavior. The description adds value by detailing parallel fan-out across multiple sources, expected return fields, and a known limitation (USPTO sunset May 2025 with soft-fail). 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?

Front-loaded with example queries and core purpose. Each sentence provides useful detail, though the description is somewhat lengthy. Could be slightly more concise, but structure is logical 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?

Given the tool's complexity (multiple sources, fallbacks, constraints) and no output schema, the description thoroughly explains what is returned (cik, filings with URIs, fundamentals, patents, news, LEI) and mentions limitations and fallback behavior. Complete for an agent to understand 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 covers both parameters with descriptions. The description adds further context: only 'company' type supported, value must be ticker or padded CIK, and explicitly states names not accepted. 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 the tool provides a 'full cross-source profile of a US public company' with numerous example queries. It distinguishes from siblings like resolve_entity and deep_research by focusing on a holistic, parallel lookup.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack lookups' for a holistic view, and warns that names are not supported, directing to use resolve_entity first. Provides clear input format instructions.

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 destructiveHint=true; description adds context about use cases but no new behavioral details 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 concise sentences, front-loaded with purpose, no wasted words.

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

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

For a simple deletion tool with one parameter and annotations, description covers purpose, usage, and sibling relationships 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?

Only one parameter with schema description; schema coverage is 100%, so description adds no 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?

Clear verb 'Delete' and resource 'memory by key', with explicit pairing to siblings 'remember' and 'recall', distinguishing its role.

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 specific when-to-use scenarios (stale context, task done, clear sensitive data) but no explicit when-not-to or alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description confirms a non-destructive read operation (fetches page, extracts info). No contradictions. The description adds that output is a single text blob, which is useful context beyond the annotations.

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

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

The description is a single, well-structured paragraph that front-loads the main action and includes all necessary details without superfluous words. 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 sufficiently explains the output ('single text blob ready to drop at site-root/llms.txt') and standard format. With two simple parameters and clear annotations, the description is complete.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the url parameter as 'Full URL of the site to summarize' and providing defaults and max for 'max_links'. 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 generates a llms.txt file for any URL, specifying the actions (fetches, extracts, emits) and the output format. It distinguishes from sibling tools like ai_visibility_check and deep_research, which have different purposes.

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

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

The description lists three concrete use cases (client site indexing, own project drafting, competitor auditing), providing clear guidance on when to use. It does not explicitly mention when not to use or alternatives, but the use cases are sufficient for selection.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds specific return fields and the optional parameter, enhancing transparency without contradicting annotations.

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

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

Two concise sentences with front-loaded purpose and immediate return fields. 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?

Covers purpose, return fields, and usage scenario effectively. However, it does not mention pagination or ordering, which could be relevant for a list tool. Overall, fairly complete for its simplicity.

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, with a description. The tool description does not add new parameter information beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'subscriptions', and scope 'caller's active subscriptions'. It also lists the return fields, distinguishing it from sibling tools 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?

Explicitly tells when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. This provides clear context, though it doesn't mention when not to use it.

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

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

The annotations (readOnlyHint=false, destructiveHint=false) are consistent. The description adds valuable behavioral context: rate-limited to 5 per identifier per day, free with no quota impact, and that the team reads digests daily. 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, with 5 sentences each providing essential information. It is front-loaded with the primary purpose and uses efficient structure without redundancy.

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

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

For a simple feedback tool without an output schema, the description fully covers input requirements, constraints (rate limits, quota), and usage guidelines. It is contextually complete for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, with each parameter having a description. The description reinforces the 'type' enum meanings and adds usage guidance (be specific, don't paste prompts) beyond the schema. It provides extra context for formulating feedback.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about broken, missing, or needed things. It uses specific verbs ('tell') and resource ('Pipeworx team'), and is unique among siblings.

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 (bug, feature/data_gap, praise) and provides guidelines like describing in terms of tools/packs and avoiding pasting the end-user's prompt. It could be improved by explicitly stating when not to use, but the use cases are 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 read-only, non-destructive, idempotent behavior. Description adds useful context: aggregated signal, no PII, caching behavior (5min-1h). 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?

Front-loaded with main purpose, then usage examples. Slightly verbose with bullet-style list, but each sentence adds value. 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?

No output schema, but description explains return fields (top tools, packs, volume). Covers behavior and caching. Parameter is simple. Complete enough for an agent to understand.

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

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

Schema coverage is 100% with parameter descriptions. Description adds interpretation: shorter windows for what's hot, longer for steady-state. This enriches beyond the enum labels.

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 specifies verb 'returns' and resource 'top tools, top packs, total call volume'. It distinguishes from siblings by focusing on aggregated usage trends rather than individual tool details.

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 usage scenarios, but does not mention when not to use or point to alternative sibling tools. Scenarios are clear and directly address common use cases.

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 provides extensive behavioral context: monotonicity checks, partition-sum checks with threshold, similarity filter, placeholder filter, fill check against live CLOB depth. Annotations (readOnlyHint, etc.) are consistent and the description adds significant detail 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 thorough but quite lengthy, with detailed technical explanations (e.g., 'theoretical_edge_pp_at_book vs realizable_edge_pp'). While justified by complexity, it is not concise. Structure is front-loaded with requirements and mode distinction.

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, but the description covers return values (opportunities array with fields) and explains the fill check and partition check outputs. All aspects of tool behavior and results are addressed.

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

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

Schema coverage is 100% with both parameters described. The description adds substantial value with examples, mode behavior, and constraints (e.g., full URLs accepted for event). Exceeds 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 states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases, and differentiates from sibling tools like polymarket_fill_risk by mentioning custom sizing there.

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 that one of event or topic is required, and calls with no args fail. Recommends event for specific markets and topic for cross-event scanning. Explains cross-event catches patterns single-event misses. Does not explicitly list when not to use, but context is clear.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description fully aligns, describing scanning and returning opportunities without mutation. It adds rich behavioral details: caching (1h KV), response structure (by_segment, diagnostics), and edge calculation specifics, going far beyond the annotations.

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

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

The description is lengthy but densely packed with valuable information, front-loaded with the main purpose. Every section adds context, though some redundancy (e.g., repeating 'tradeable-edge knobs') could be trimmed. For a complex tool, the length is justified, so it earns a 4.

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 having no output schema, the description thoroughly explains the response structure: three segments under by_segment, Fed candidates, diagnostics, and field meanings (edge_pp_net, kelly_fraction, etc.). It covers parameter interactions and caching, making it complete for agent invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds high-level context for parameters like min_liquidity and max_spread_pp as 'tradeable-edge knobs' but does not significantly enhance schema descriptions for individual parameters, which are already adequately detailed.

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

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

The description explicitly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The verb 'scan' and 'return' are specific, and the resource 'Polymarket markets' is clear. It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on Pipeworx-driven disagreement 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 provides clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It mentions knobs for filtering and notes that Fed bets are excluded from ranking. However, it does not explicitly state when not to use or compare directly to sibling tools, leaving some ambiguity.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds critical behavioral context: data comes from daily snapshots, snapshots are written on cache-miss, decay is from daily closes (not intraday), and history is bounded by a 60-day TTL. 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 thorough but not verbose; it front-loads the purpose, explains output details, and ends with limits. Every sentence adds value, though it could be slightly tighter.

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

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

Given no output schema, the description fully explains return values (tracked, expired, snapshot_dates) and their meaning. It also covers limitations (TTL, start date, decay source). This is complete for a moderately complex data 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 the description reinforces defaults (days=14, window='1wk') and adds constraints (days clamped 2-30). This adds slight value 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 uses specific verbs ('answers how long has this edge existed and is it shrinking?') and clearly distinguishes it from the sibling tool 'polymarket_edges' by focusing on persistence and decay. It lays out the output structure (tracked[], expired[], snapshot_dates[]) concisely.

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

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

The description implies when to use this tool (for historical edge persistence analysis) by contrasting fresh wide edges with old ones. While it does not explicitly state when not to use it, the differentiation from other tools is clear enough for an AI agent to decide.

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 true and destructiveHint false. The description adds behavioral context such as walking the ladder, returning verdicts (clean|degraded|cannot_fill), and warning about partial basket fills causing directional risk. No contradictions; the description enhances understanding of the tool's behavior beyond the annotations.

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

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

The description is well-structured: a clear one-liner, then flags (REQUIRES), followed by distinct mode explanations, and a usage sentence. It is detailed but not verbose. Every sentence adds value, though the length could be slightly reduced without losing clarity. Minor room for improvement.

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

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

Given the complexity (two modes, 4 parameters, no output schema, and related sibling tools), the description covers all essential aspects: it explains what each mode returns (fields like capture_ratio, thin_legs, forced_directional_risk), why it matters (partial fill risk), and the verdict system. This is sufficient for an agent to understand 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%, but the description adds significant meaning: explains the difference between market and event modes, the interpretation of size_usd in each mode (max spend vs. settlement notional), default side behavior (auto), and clamps (10–1,000,000). This goes well beyond the schema definitions.

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

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

The description immediately states it's a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly defining its function. It distinguishes between single-market and basket modes, listing specific outputs like top_of_book, vwap_fill_price, slippage_pp, and verdicts. This differentiates it from 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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why (theoretical overround on thin books is not capturable, partial fills create directional risk). Provides clear context without naming alternatives, as the instruction is to use this tool before specific 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?

Describes two modes, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype counters) and their meanings. Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds substantial context beyond annotations without contradiction.

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

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

Long but dense and front-loaded with purpose, modes, and safety fields. Every sentence adds value, though could benefit from bullet points for readability. Still earns a 4 for efficiency.

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 response structure comprehensively: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment flags, and skipped counters. Covers all necessary information for an agent to interpret results.

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

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

Schema has 100% description coverage for all 3 parameters, and description adds extra context about the two modes and how parameters override topic-mapped sides. Examples provided further clarify 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 clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' with specific verb 'calculate spread' and resource 'two prediction markets'. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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: to compare prices across venues, and warns when not to use: when compatibility_warning indicates non-equivalent bet shapes or temporal misalignment. Also notes that most pre-mapped topics are not yet tradeable, setting proper expectations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context beyond these: the tool is specific to Finland Open Data and CKAN DataStore, and only works on DataStore-enabled resources. This provides behavioral constraints not captured by 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 long with no extraneous information. Each sentence serves a purpose: the first states the verb and resource, the second adds a crucial constraint. It is well-structured 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?

The tool has no output schema, and the description does not explain the return format (e.g., row structure, metadata). For a query tool that returns rows, this is a gap. The description does convey the source system and limitation, which is partial completeness.

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

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

Schema coverage is 100% with parameter descriptions. The tool description reiterates the optional parameters (q, limit, offset) but does not add significant semantic meaning beyond the schema. It does clarify that resource_id comes from dataset/search_datasets, which is a minor addition.

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 ('Pull rows'), the resource ('tabular Finland Open Data resource (CKAN DataStore)'), and the key identifier ('resource_id'). This verb-resource combination is specific and distinguishes it from sibling tools like 'search_datasets' which searches for datasets, not individual resource rows.

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 a prerequisite ('only resources with the DataStore enabled are queryable'), which is helpful but does not provide explicit guidance on when to use this tool versus alternatives like 'dataset' or 'search_within'. It lacks 'when to use/when not to use' 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?

Description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint). Adds behavioral context: scoping, listing behavior on omitted key, pairing with remember/forget.

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 with clear structure: function first, then usage context. No unnecessary information.

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

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

Given one optional parameter, no output schema, and comprehensive annotations, the description fully explains behavior, scoping, and sibling relationships.

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

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

Schema coverage is 100% with description explaining 'omit to list all keys'. Description does not add meaning beyond schema; baseline score of 3.

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

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

Description clearly states the tool retrieves a value via key or lists all keys. It distinguishes itself from sibling tools 'remember' and 'forget' by explicitly naming them.

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

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

Provides clear context for when to use: to look up stored context without re-deriving. Mentions scoping by identifier. Lacks explicit 'when not to use', but sufficient for a simple tool.

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

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

Annotations already indicate read-only, but description adds that mark_read:true flags events as read, affecting subsequent calls – a state-modifying side effect the agent should know. Also notes the feed is persisted and polling is safe, beyond annotation hints.

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

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

Single paragraph, front-loaded with purpose, then return content, filter options, side-effect behavior, and alternative access. Every sentence adds value; no redundancy or 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?

For a tool with 5 parameters and no output schema, the description explains what is returned (source, citation_uri, payload), how filters work, the effect of mark_read, and alternative access. Agent can use it correctly without ambiguity.

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

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

Schema covers 100% of parameters, but description adds real-world examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains mark_read/unread_only behavior, enhancing meaning beyond 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?

Starts with 'Pull fired events from your subscription feed' – clear verb+resource. Differentiates from sibling tools like list_subscriptions by focusing on event retrieval, not subscription management. Specifies return fields (source, citation_uri, payload) and filtering options.

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 polling works fine and provides an alternative REST endpoint for scripts/dashboards, giving context for when to use this tool. Does not list exclusions but implies use for programmatic access vs. direct API.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: it fans out to multiple APIs in parallel, explains the GDELT→GNews fallback mechanism, notes the USPTO API sunset causing a soft-fail, and describes the return structure (changes grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

The description is densely packed with valuable information and front-loads the purpose with example queries. Every sentence serves a purpose. However, it could be slightly more structured (e.g., bullet points for sources or parameters) to improve scanability, though it remains highly 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 tool's complexity (multiple sources, fallback, soft-fail, no output schema), the description is remarkably complete. It covers all major behaviors, explains the return format (changes[] grouped by source, total_changes count, pipeworx:// URIs), and references the alternative tool. Without an output schema, the description fully compensates by describing the output structure.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond parameter descriptions. It explains that `since` accepts ISO dates or relative shorthand, provides examples ('2026-04-01', '7d', '30d', '1y'), and recommends typical values. For `value`, it clarifies that tickers or CIK numbers are acceptable. This is a model of 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?

The description immediately opens with example queries like 'What's new with X' and 'latest on Y', making the tool's purpose unmistakable. It specifies that it returns a change feed for a company in a given window, lists the data sources (SEC EDGAR, GDELT/GNews, USPTO), and clearly distinguishes itself from the sibling tool entity_profile. This is a specific verb+resource with excellent 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?

The description provides explicit when-to-use guidance through example queries and also states when not to use it: 'Use entity_profile instead when you want the static profile...'. It gives concrete advice on parameter values, such as using '30d' or '1m' for typical monitoring. This fully addresses when to use this tool vs. 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 description adds detail beyond annotations, such as the key-value pair storage scope, persistence for authenticated vs. anonymous users (24 hours), and pairing with recall/forget. Annotations indicate idempotentHint=true and destructiveHint=false, which are consistent and supplemented.

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

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

The description is four sentences with clear structure: purpose, usage guidance, technical details, and pairing info. No redundant information.

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

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

For a simple two-parameter tool with no output schema and adequate annotations, the description provides complete context: purpose, when to use, storage behavior, and related tools.

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 good descriptions for both key and value. The description mentions 'key-value pair' but does not significantly extend schema details. 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 'Save data the agent will need to reuse later', specifying the verb 'save' and resource 'data'. It distinguishes from sibling tools like recall and forget by mentioning them as complementary 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 states when to use the tool: 'when you discover something worth carrying forward'. It provides context about persistence and scoping but does not explicitly mention when not to use it, though sibling tools imply 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 description adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint, etc.). It reveals that 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups,' and explains auto-disambiguation for company names. This enriches the agent's understanding of internal processing without contradicting any annotations.

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

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

The description is front-loaded with the core purpose and usage examples, making it easy to scan. It is organized into clear sections (purpose, supported types). However, it is somewhat verbose with the cascade mention and repeated citation details; a slight trim could improve conciseness 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 fully explains return values for both entity types, including citation URIs. It covers the tool's internal cascading behavior and auto-disambiguation. Given the complexity of two entity types with different output structures, the description provides all necessary contextual information 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?

With 100% schema coverage, the description still adds substantial meaning to both parameters. For 'type', it enumerates supported values ('company', 'drug') and details the return components (ticker+CIK+name+citation for company; RxCUI+ingredient+brand+citation for drug). For 'value', it provides concrete input examples (AAPL, 0000320193, 'ozempic') and clarifies accepted formats, far exceeding the schema's bare 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 states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete query examples ('What's the ticker for…', 'find the CIK for…') and explicitly differentiates from sibling tools by instructing 'Use FIRST whenever you have a name but need an ID.' This leaves no ambiguity about what the tool does.

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 strong usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types (company, drug) and what each returns. However, it does not explicitly state when NOT to use the tool (e.g., if you already have an ID) or compare directly to sibling tools like entity_profile or compare_entities, missing an opportunity to fully delineate 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals it internally calls ai_visibility_check, treats the first entity as the subject, and returns a ranked list with score, confidence, and signal density. This adds significant behavioral context beyond what annotations provide.

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

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

Three efficient sentences: first states core function, second explains mechanism, third provides use case. Front-loaded and every sentence adds value without redundancy.

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

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

Despite no output schema, the description specifies the return format (ranked list with score, confidence, signal density). It covers purpose, inputs, outputs, and a use case. Slightly more detail on the ranking algorithm could improve completeness, but it's already strong.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that the first entity is treated as the subject for narrative and that context disambiguates common names. This extra semantic context justifies a higher score.

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, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes this tool as a competitive audit tool, different from general entity comparison tools like compare_entities.

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

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

The description explicitly says it's 'useful for competitive AI-marketing audits' and provides a concrete example question. While it doesn't explicitly exclude alternatives, the context implies when to use. Missing explicit mention of compare_entities as an alternative for general comparison, but still offers clear guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, not destructive. The description adds beyond that: partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, 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?

The description is relatively long but every sentence adds value: composite purpose, services, usage, limitations, fallback, timing. Front-loaded with core purpose. Could be slightly shorter but maintains clarity.

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

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

Given complexity (multi-source, no output schema), description covers return format (summary block with fields, advisories, links, alternatives), partial failures, and limitations. Sufficient for agent to understand what to expect.

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

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

Schema coverage is 100% with both params described. The description adds value beyond schema: accepts scoped packages, defaults version to latest. This enhances understanding beyond raw 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 is a composite check for adding npm packages, fanning out across deps.dev and bundlephobia. It specifies the resource (npm package) and scope (version) and distinguishes from siblings like deps.dev direct fallback.

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

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

Explicit usage guidance: 'Use whenever an agent asks is X safe / popular / small' and 'what does adding lodash cost me'. Also specifies exclusions (NPM only; PyPI etc. use deps.dev directly) and mentions graceful degradation with timing.

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, etc.), description clarifies return fields and cross-reference to query_resource tool. 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, 26 words, front-loaded purpose, 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?

Adequate for a simple search tool with 3 optional params and no output schema. Could hint at pagination, but not necessary.

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 3 params with descriptions; description adds the source context but no new param details. Baseline 3 due to 100% 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?

Clearly states verb 'Search', resource 'Finland Open Data' datasets by keyword, and return fields including resource_id for cross-tool use. Distinct from sibling tools like query_resource.

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?

Describes keyword search and blank/* behavior, but no explicit context on when to use vs alternatives like query_resource or search_within.

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 richly details behavioral traits beyond annotations: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, has a 200K char cap with truncation and flagging. This adds significant context beyond the read-only and idempotent 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?

Description is concise, front-loads core purpose, then efficiently adds technical details and usage guidance. Every sentence earns its place with no redundancy.

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

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

Despite no output schema, the description fully explains what the tool returns (passages, offsets, scores) and covers all critical operational details (model, window size, char cap). It is complete 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 covers parameters 100%, but description adds practical context: examples for 'text' (SEC 10-K, article), natural-language query examples, and implicit 'limit' as 'top-N'. This adds value beyond 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 semantic search inside a fetched record, using a verb ('search') and specific resource ('record'). It distinguishes from siblings by explicitly pairing with ask_pipeworx_grounded and describing the niche use case of large records.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt', providing clear guidance on when to use. It also mentions pairing with ask_pipeworx_grounded, offering an alternative approach.

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: webhook auto-disable after 10 consecutive failures, phone verification requirement, 10/day SMS cap, and that the feed is always on. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, 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?

The description is a single paragraph but front-loads the purpose and then uses structured inline lists. Every sentence adds value; no extraneous text. It is efficient 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?

For a tool with 3 parameters (2 required) and no output schema, the description covers creation behavior, return value (subscription id), constraints, examples, and delivery details. It is complete and leaves no major gaps.

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

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

Schema coverage is 100%, but the description adds detailed type-specific formats and examples (e.g., sec_8k items, polymarket_edge topic, delivery webhook mechanics). It enriches the parameter meaning 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 'Create a proactive monitoring subscription to a live-data event stream', specifying the action, resource, and target. It also lists supported subscription types, distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

It specifies a prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'. It provides examples for each type and delivery options, and mentions pulling via recent_alerts as an alternative. However, it does not explicitly state when not to use this tool compared to specific siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, not destructive. Description adds context: it returns example questions from a live catalog and teaches meta-tool usage. 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, examples, and usage instructions. Slightly long but 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?

Fully explains what the tool does, what it returns, when to use, and how to customize. No gaps given the tool's simple interface.

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 already listing topic options and omission behavior. Description slightly rephrases but adds no new semantic value beyond the schema.

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

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

The description explicitly states it is the onboarding entry point for asking what Pipeworx can do, returning category-bucketed example questions with tool shapes. It clearly distinguishes from sibling tools by targeting users who don't yet know Pipeworx's capabilities.

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

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

Provides explicit guidance to 'use this FIRST when you do not yet know what Pipeworx can do' and to learn how to call meta-tools. Specifies calling with no arguments for full spread or passing a topic for focus.

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 reveals that the operation is non-destructive (deactivates, not deletes) and enforces ownership, which adds value beyond annotations. While annotations indicate idempotentHint=true, the description doesn't explicitly mention idempotency, but the deactivation behavior implies it.

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 that front-load the action ('Cancel a subscription by id') followed by important constraints. No wasted words.

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

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

For a simple one-parameter tool with no output schema, the description covers the essential behavioral details: ownership enforcement, deactivation vs deletion, and impact on historical data. Fully adequate.

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

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

Schema coverage is 100%, so baseline 3. The description restates that the 'id' parameter is a subscription UUID from 'subscribe', which is already in the schema description. No additional semantic detail provided.

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 cancels a subscription by ID. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation 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 ownership enforcement ('you can only cancel your own subscriptions'), providing clear when-to-use guidance. Also explains that the row is deactivated not deleted, implying historical data remains accessible via 'recent_alerts'.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are all consistent. The description adds valuable behavioral context: returns a verdict with citation and delta, v1 scope limited to company-financial claims, and that it replaces multiple sequential calls. 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 well-structured, starting with examples, then usage instruction, then feature list, and limitations. It is somewhat verbose but every sentence adds value, and front-loading improves 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 details the return elements (verdict, structured form, citation, delta) and notes the current scope limitation. It covers essential aspects for a single-parameter, well-annotated tool, though it could mention error handling for out-of-scope claims.

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

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

Schema coverage is 100% with a clear description for the single 'claim' parameter. The tool description adds extra context with examples and usage hints ('e.g., "Apple's FY2024 revenue was $400 billion"'), which enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: fact-checking natural-language claims against authoritative sources, specifically company-financial claims. It provides example queries ('Is it true that…') and specifies the domain (via SEC EDGAR + XBRL), making the purpose unmistakable.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported claim type (company-financial) and what it replaces, providing clear context for when to invoke it, though it does not list alternatives.

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