Tweedekamer Nl

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds valuable context: probing LLMs, returning scores with confidence/signals/raw_response, and the default free model vs. BYO key for Anthropic with direct payment. It does not contradict annotations and provides meaningful behavioral detail beyond the structured fields.

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 4 well-structured sentences with zero wasted words. The first sentence states the core function, the second covers configuration details, the third lists return fields, and the fourth gives use cases. It is front-loaded and every sentence earns its place.

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

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

Given the tool's complexity (multiple models, optional key, per-model and combined output) and no output schema, the description adequately explains the return structure and all key behavioral aspects. It covers purpose, parameters, usage context, and output format, making it complete for an AI agent to decide when and how to invoke.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying the entity parameter with examples and scope, specifying the exact supported models and default behavior for `models`, explaining the `_apiKey` requirement and pass-through, and providing guidance on disambiguation for `context`. These additions go beyond the schema's basic descriptions.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs for a business/brand/product/topic) and output (visibility score 0-100 per model). It distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on visibility measurement for any entity, not just queries or competitor scans.

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

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

The description explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also mentions when to use the optional `_apiKey` (for Anthropic probes with BYO key). However, it does not explicitly state when not to use this tool or offer direct comparisons to sibling tools like 'scan_competitor_ai_presence'.

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 as true, and destructiveHint as false. The description adds significant value by explaining that the tool routes to internal tools, fills arguments, and returns structured answers with pipeworx:// citation URIs. This explains what happens behind the scenes beyond the annotations. No contradictions.

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

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

The description is well-structured with the key point 'PREFER OVER WEB SEARCH' at the beginning, followed by a list of domains, usage examples, and what the tool does. It is not overly verbose and each sentence adds value, though it could be slightly more concise.

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 (3,804 tools, 907 sources, many domains), the description is comprehensive. It explains the routing mechanism, the output format (structured answers with citations), and gives concrete examples. Without an output schema, this description provides sufficient context for an AI 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?

Input schema has 6 parameters, all aliases for 'question'. Schema coverage is 100% as all are described as aliases. The description adds further meaning by explaining what kind of question to ask (factual, real-world entities, events, numbers) and provides multiple examples. This goes beyond the simple 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 the tool's purpose: routes questions to the correct tool among 3,804 tools across 907 sources, fills arguments, and returns structured answers with citation URIs. It also distinguishes itself from web search by explicitly saying 'PREFER OVER WEB SEARCH' and lists numerous specific use cases.

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

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

The description provides explicit guidance on when to use the tool: for questions about current or historical data from specific domains (SEC filings, FDA drugs, etc.) and even gives example queries. It says 'Use whenever the user asks... even if web search could also answer it,' making the usage context very clear. It also implicitly excludes non-factual or non-structured queries.

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

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

Adds significant behavioral context beyond annotations: describes hallucination resistance, extraction logic, structured return types with refusal reasons. No contradiction with annotations.

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

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

The description is well-structured with front-loaded key information. It is slightly verbose but each sentence contributes useful detail.

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 (6 parameters, no output schema), the description covers return values, failure modes, and usage context adequately. Minor gaps (e.g., exact parameter aliasing details) do not hinder understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'fills arguments' but adds no specifics about the parameter beyond what the schema provides.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads', specifies the routing logic, and distinguishes it from the sibling 'ask_pipeworx' by noting the extra LLM call. The purpose is specific and unambiguous.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), providing clear alternatives.

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

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

The description goes far beyond annotations, detailing fan-out patterns, response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, wide spreads, and resolution-rule risk. 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 very long and detailed, with structured sections. While well-organized, it is verbose and could be more concise. The purpose is front-loaded, but many sentences are example-heavy.

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 (3 params, no output schema), the description covers all necessary aspects: input formats, behavior, return structure, edge cases, safety, resolution risk. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining response shapes (which fields appear in 'market', 'analysis', 'evidence') and providing examples of fan-out per category. This is above baseline but not exhaustive for each parameter.

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

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

The description clearly states the tool's purpose: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). The purpose is specific and distinct from siblings like 'ask_pipeworx' or 'validate_claim'.

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

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

Explicit use cases are given: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It also provides guidance on when results are unreliable (low-confidence matches, closed markets, wide spreads) and includes resolution-rule risk warnings.

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, etc.), the description discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting behavior, and return format including citation URIs. This fully informs the agent of behavior beyond annotations.

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

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

The description is front-loaded with core purpose and examples, but contains some redundancy (repeating 'X vs Y' variations). Every sentence contributes value, but could be slightly more concise without losing information.

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

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

Given no output schema, the description comprehensively explains what data is returned (specific financial metrics for companies, adverse event counts for drugs), sorting, and citation URIs. It covers all necessary context for correct tool use.

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

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

Schema provides basic descriptions, but the description adds significant meaning: for 'type' it connects values to specific data sources; for 'values' it specifies expected formats (tickers/CIKs for companies, drug names for drugs). It also clarifies that results are sorted by a primary metric, which is not in schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific verbs like 'compare', 'versus', 'rank'. It distinguishes from siblings by explicitly preferring over sequential lookups and provides concrete examples of use cases.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear guidance on when to use. It also outlines types (company/drug) and provides example queries, leaving no ambiguity about appropriate usage contexts.

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 behavior beyond annotations: decomposition, parallel processing, structured findings with evidence, gaps, never invented, prerequisites (account, payment), expected time. No contradiction with annotations.

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

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

Front-loaded with key action, then explains mechanism and requirements. Information-dense but each sentence adds value; slightly verbose but justified by complexity.

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

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

For a complex tool, the description covers what it does, how, output format (findings, gaps), prerequisites, and estimated time. Lacks output schema but compensates with description. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds value by explaining depth values correspond to number of facets and that question can be broad/multi-part. This adds meaning beyond schema.

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

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

The description specifies a clear purpose: 'Grounded multi-source research in ONE call' with decomposition into sub-questions and parallel routing. It distinguishes from sibling ask_pipeworx and gives concrete use cases.

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 for broad or multi-part questions' and when not: 'use ask_pipeworx for single lookups'. Provides examples. 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 readOnlyHint=true and idempotentHint=true. The description adds behavioral context beyond annotations: it states the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly.' This adds clarity about output format 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?

The description is a single paragraph of three sentences, front-loading purpose and usage. Every sentence adds essential info: what the tool does, when to use it, and what the output contains. No redundant or filler text.

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

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

Given the tool's complexity (6 parameters, 100% schema coverage, no output schema), the description adequately covers the tool's purpose, usage guidance, and output nature. Minor gaps exist (e.g., no mention of pagination or error handling), but the essential information for agent decision-making is present.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by listing multiple aliases for the query parameter (q, task, search, description) and providing natural language examples (e.g., 'analyze housing market trends'). This helps agents understand parameter flexibility beyond schema annotations.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the output (top-N relevant tools with schemas) and distinguishes from sibling tools by positioning it as a discovery mechanism for browsing the available toolset.

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

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

The description explicitly advises when to use the tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lists example use cases (SEC filings, FDA drugs, etc.) and implies when not to use (when a specific tool is known).

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

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

Annotations already indicate safe, read-only, idempotent. Description adds valuable behavioral details: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific fields and URIs; patents soft-fails after May 2025; fallback from GDELT to GNews. 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?

Description is detailed and front-loaded with examples and usage. It is slightly verbose but every sentence adds value for a complex tool. Minor room for trimming, but structure is clear.

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

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

No output schema, but description exhaustively lists return fields and sources. Covers capabilities, limitations (names unsupported), and fallbacks. For a multi-source tool, it is highly 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 description adds meaning: type='company' only, value accepts ticker or zero-padded CIK (not names). This goes beyond schema by clarifying the acceptable formats and the need to use 'resolve_entity' for names.

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 profiles US public companies, with specific verbs like 'profile', 'brief me on', 'company profile for'. It distinguishes from siblings like 'resolve_entity' and 'compare_entities' by being a holistic multi-source 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 says to prefer over chaining single-pack lookups for holistic views, and specifies that names are not supported – use 'resolve_entity' first. This provides clear when-to-use and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description confirms destructiveness with 'Delete' and adds context about clearing sensitive data, but does not significantly expand beyond annotations.

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

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

Three sentences: the first clearly states the action, the second gives usage context, and the third links to related tools. No unnecessary words, well-structured and front-loaded.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, usage, and relationships to siblings completely. The annotations provide additional safety context, making it 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?

The schema already describes the 'key' parameter with 100% coverage. The description mentions 'by key' but does not add new semantic meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key', which is a specific verb and resource. It also distinguishes itself from siblings by referencing 'remember' and 'recall', indicating the tool's role in memory management.

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 use cases: when context is stale, the task is done, or to clear sensitive data. It also suggests pairing with related tools. It does not specify when not to use it, but the guidance is clear enough.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds beyond that by detailing the steps (fetches page, extracts title/description/links, emits markdown) and output format. No contradiction. Score 4.

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

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

Three concise sentences, front-loaded with purpose. Every sentence adds value without fluff. Excellent structure. 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?

Despite no output schema, the description sufficiently describes the output (single text blob, standard llms.txt format). All parameters are covered, annotations are present. Complete for a simple generation tool. Score 5.

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 description adds minimal extra semantic meaning beyond schema, only mentioning link extraction which relates to max_links. Baseline 3 is appropriate. Score 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?

The description clearly states the action (generate llms.txt), the resource (any URL), and the purpose (AI crawlers indexing). It distinguishes the tool from siblings by its unique function, though it does not explicitly differentiate. Score 4.

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 use cases: getting a client's site indexed, drafting for own project, or auditing competitors. However, it does not mention when not to use it or provide alternatives among siblings. Score 4.

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, fully specifying the safety profile. The description adds context about fetching by GUID and optional OData features, but does not reveal additional behavioral traits (e.g., rate limits, pagination, auth).

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds value. No redundancy or extraneous details.

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

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

Given the tool's simplicity (fetch by ID), the description covers input requirements and optional parameters. No output schema, but the behavior is well-defined. Could mention return format but not critical for a fetch operation.

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

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

Schema coverage is 100% with detailed descriptions for all 4 parameters. The description repeats some schema info (e.g., common entity names, id format) and adds an example, but does not add substantial meaning beyond the schema.

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

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

The description explicitly states 'Fetch one Tweede Kamer record by its GUID id,' which clearly defines the action (fetch) and resource (record). It distinguishes from sibling tools like query_entity or search_people that serve different purposes (listing or searching).

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 instructions: 'Pass the entity name and the record Id' with an example GUID. It also mentions optional $select and $expand. However, it does not explicitly contrast with alternatives or state when not to use this tool.

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

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

The description adds value beyond annotations by detailing the return fields (id, type, params, etc.). Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description reinforces this with 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 two well-structured sentences. The first sentence states purpose and return fields, the second provides usage context. No extraneous information, every word earns its place.

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

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

For a simple read-only list tool with one optional parameter and no nested objects, the description is complete. It covers purpose, return fields, and usage context. The lack of an output schema is mitigated by listing the fields in the description.

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

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

The input schema has 100% description coverage for the single parameter 'include_inactive'. The description does not add additional parameter semantics beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It lists the return fields (id, type, params, created_at, last_fired_at, fire_count), distinguishing it from sibling tools like 'subscribe' and 'unsubscribe' that modify subscriptions.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool, though it doesn't explicitly state when not to use it or mention alternatives beyond the implied 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?

The description discloses key behavioral traits not present in annotations: rate limiting, free usage, non-quota nature, and that the team reads digests daily. Annotations are all false, so the description fully informs the agent about side effects and constraints. 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 three well-structured sentences: first states purpose, second gives usage scenarios and constraints, third adds behavioral details. Every sentence earns its place with no fluff. Front-loaded with the core action.

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

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

Given the tool's simplicity (3 params, 1 nested, 1 enum), the description covers purpose, usage, rate limits, and instructions. No output schema is present, but for a feedback submission tool, return values are not critical. The description is fully sufficient 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 description coverage is 100%, but the description adds value by explaining the enum values in the type parameter and setting a max length for message (2000 chars). It also clarifies the optional context parameter's structure. While schema already documents parameters, the description enriches understanding without being redundant.

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 for sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than queries. The verb 'Tell' and resource 'Pipeworx team' are specific and unambiguous.

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

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

Explicitly specifies when to use the tool (for bug, feature, data_gap, praise, other) and what not to do (don't paste end-user prompt). Includes rate limit (5 per identifier per day) and clarifies it's free and doesn't count against quota. This provides complete usage guidance.

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

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

The description adds significant behavioral context beyond annotations: explains data source (CF analytics-engine), privacy (no PII), data structure (pack, tool, count), and caching (5min-1h). Fully consistent with annotations.

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

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

The description is concise (5 sentences), front-loaded with the core purpose, uses bullet points for use cases, and contains no filler. Every sentence is 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?

Given no output schema, the description adequately explains what is returned (top tools, top packs, total call volume). While format details are missing, the tool's simplicity and the rich annotations compensate. Slight room for improvement.

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 repeats the schema's parameter explanation almost verbatim, adding no new semantic information beyond what is already provided 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 what the tool does: return top tools, top packs, and total call volume over a recent window. It distinguishes itself from siblings by focusing on trending activity and use cases.

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 use cases (discovering hot data sources, confirming canonical choice, aligning use case) but does not explicitly state when not to use or list alternatives. Still clear context for usage.

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

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

Annotations mark the tool as readOnlyHint, idempotentHint, and not destructive. The description goes beyond annotations by explaining the internal algorithms (monotonicity violations, partition checks, fill checks, similarity thresholds). It discloses edge cases like skipped_low_similarity and placeholder filtering. 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 thorough but verbose, containing multiple paragraphs with technical details (Jaccard threshold, partition filter, fill checks). It could be more concise by front-loading the key usage guideline and relegating some algorithmic details to a separate section. However, it is well-organized with clear mode distinctions and examples.

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 arbitrage detection, the description is remarkably complete. It covers both modes, the algorithm steps, response structure, and error conditions (e.g., skipped_low_similarity, placeholders_filtered). It explains the fill check and when the signal is not tradeable. Since there is no output schema, the description adequately documents return values and their meaning.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic'. The description adds significant meaning: it explains that 'event' expects a slug (with examples), that 'topic' is a seed question for cross-event scanning, and details the underlying behavior like walking child markets or searching related events. This goes far beyond the schema's simple descriptions.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between single-event and cross-event modes, and differentiates from siblings like polymarket_fill_risk. The verb 'Find' and specific resource 'arbitrage opportunities on Polymarket' make it unambiguous.

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

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

The description explicitly states that an agent must provide exactly one of 'event' or 'topic', and warns that calling with no arguments fails. It gives clear guidance on when to use each mode: 'event' for a specific market, 'topic' for cross-event scanning. It also mentions a fill check that tells agents when not to trade, and references polymarket_fill_risk for custom sizing.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds extensive behavioral details: model families, edge calculations, caching (1h), diagnostics, and explains why Fed bets are excluded. Nothing contradicts annotations; this enhances transparency significantly.

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 dense but well-structured: starts with purpose, then model families, output structure, knobs. Each sentence adds value; however, length could be trimmed slightly without losing essential details. Organized for 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?

No output schema, but description fully covers return values: by_segment segments, edge parameters (edge_pp_net, kelly_fraction), market fields, 24h-move warning, diagnostics, and Fed bets handling. Parameter descriptions are complete. Agents have sufficient information to invoke and interpret results.

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

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

Schema coverage is 100% (all parameters described). Description adds value by explaining purpose of each knob (e.g., min_liquidity, max_spread_pp, min_partition_leg_kelly), providing defaults and reasoning (e.g., slippage: zero fees but bid/ask eats 20-50bp). This improves agent's understanding beyond schema.

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

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

Description specifies a clear verb-resource pair ('scan top Polymarket markets') and the unique function ('return opportunities where Pipeworx data disagrees with market price'). It distinguishes itself from siblings like polymarket_arbitrage (cross-platform arbitrage) and polymarket_kalshi_spread by focusing on Pipeworx data disagreement.

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 built for 'what should I bet on today' and enables discovery without paging hundreds of markets. Provides context on when to use, including default knobs and filters. However, does not explicitly state when not to use or suggest alternative tools for different 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?

Beyond annotations (readOnly, idempotent), the description discloses data source, snapshot gaps, limits (60-day TTL), decay computation method (daily closes only), and response structure (tracked, expired, snapshot_dates). No contradictions with annotations.

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

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

The description is long but well-organized with ARGS and RESPONSE sections. It front-loads the key question. Some details like 'median lifespan is your competition clock' could be trimmed, but overall it's appropriately detailed for the complexity.

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

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

Despite no output schema, the description fully declares the response structure (tracked, expired, snapshot_dates) and explains limits. For a read-only, idempotent tool, this is comprehensive 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 already covers both parameters with descriptions including defaults and valid values. The description merely restates schema info without adding new meaning, meeting baseline for 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?

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes from siblings like polymarket_edges by focusing on historical analysis rather than raw current edges.

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

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

The description implies when to use this tool by noting that a fresh wide edge differs from a 3-week-old one, suggesting it's for assessing edge stability. However, it does not explicitly list when not to use or compare with alternatives, 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?

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description does not contradict. The description adds detailed behavioral context: it walks the ladder, returns specific fields, and warns about risks like partial basket fills converting an arb into an unhedged directional position.

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

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

The description is relatively long but well-structured, with clear sections separated by line breaks and bold for emphasis. It front-loads the summary and then details modes and outputs. Some redundancy could be trimmed, but given complexity, it's justified.

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

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

The description fully covers the tool's functionality: two operation modes, all output fields (top_of_book, vwap_fill_price, slippage_pp, etc.), verdict values, and risk warnings. Without an output schema, this provides complete information for an agent.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds significant meaning beyond the schema: it explains the difference between single-market and basket modes, the auto logic for side in basket mode, and the interpretation of size_usd in each mode. This adds value.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between two modes (single-market and basket) and explicitly names outputs like top_of_book, vwap_fill_price, verdict, etc. This distinguishes it from siblings like polymarket_arbitrage.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable, partial fills create directional risk). This is exceptional.

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

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

The description discloses behavior beyond annotations: it details safety fields (`compatibility_warning`, `temporal_alignment`, `skipped_cross_type/subtype`), explains edge cases (e.g., matched_pairs:0 scenarios), and notes that spreads are 'mathematically meaningless across the temporal gap' when alignment is false. Annotations already indicate read-only, open-world, and idempotent, and the description complements these without contradiction.

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

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

The description is verbose but efficient, packing substantial detail into a coherent paragraph. It is front-loaded with the core purpose and uses dot points for modes and safety fields. Minor redundancy ('Real cross-venue spreads are rarer...' repeats earlier warning) prevents a score of 5, but it remains well-structured for the complexity.

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

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

Given no output schema, the description fully compensates by explaining the response structure (leg-by-leg prices, matched spreads, safety fields) and the meaning of each safety field. It covers parameter interactions, edge cases, and temporal alignment, leaving no significant gaps for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds critical context: it explains the interaction between `topic` and the explicit override parameters, lists the 10 macro shortcuts for `topic`, and clarifies that the tool requires either `topic` or both explicit parameters. This goes beyond the schema's individual 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 the tool computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage (which likely handles intra-venue spreads) by specifying the cross-venue nature and the two modes of operation.

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 describes two modes (`topic` for pre-mapped shortcuts and explicit parameters for custom pairs), warns that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable,' guiding the agent on when to expect meaningful results. It also explains when not to use the tool via compatibility_warning and temporal_alignment fields.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. Description adds OData specifics, pagination recommendation, and Dutch language context, enhancing transparency beyond annotations.

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

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

Single paragraph, front-loaded with main action, includes inline examples, no wasted words.

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

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

Given 8 parameters and no output schema, description covers all parameter usage, OData passthrough, return structure under `value`, and language context. Sufficient for correct tool invocation.

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

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

Schema covers 100% of parameters. Description adds OData syntax examples, common entity names, and usage recommendations (e.g., always set $top), improving practical understanding.

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

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

The description clearly states the tool queries an OData v4 entity set with full passthrough, names specific entities like Persoon and Fractie, and distinguishes it from siblings like get_entity_by_id.

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

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

Provides explicit usage instructions: use $filter, $select, $orderby, $expand, always set $top. Implies when not to use (for single entity use get_entity_by_id). Lacks explicit when-not but overall strong.

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

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

Annotations indicate readOnly and idempotent. Description adds detail on scoping (anonymous IP, BYO key, account ID) and listing behavior. No contradiction.

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

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

Three concise sentences: core function, usage guidance, and additional context. No wasted words.

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

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

Given single optional parameter and no output schema, description covers use cases, scoping, and ties to sibling tools. Complete for a read-only retrieval tool.

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

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

Schema covers parameter semantics fully (100% coverage). Description reinforces the meaning but does not add new details 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 retrieves a value saved via remember or lists all keys. It distinguishes itself from sibling tools like remember and forget.

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

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

Provides clear context for when to use: to look up stored context without recomputing. Mentions scoping and pairing with remember/forget. No explicit when-not-to-use but clear enough.

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

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

Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. The description adds transparency about the return fields (source, citation_uri, raw payload) and especially about mark_read's side effect of flagging events as read, which is behavior beyond the annotations. No contradictions aside from the mark_read side effect conflicting with readOnlyHint (flagged separately).

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, front-loaded with the purpose, then details return fields, filtering options, and a note about alternative access. Every sentence contributes without redundancy.

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

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

Given the 5 parameters (all with schema descriptions) and no output schema, the description adequately covers return fields and side effects. It could mention pagination or empty results behavior, but overall it is sufficient for an alert-reading tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing an example for type ('sec_8k') and clarifying that mark_read causes the next call to show only newer events, which goes beyond the schema's 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 opens with 'Pull fired events from your subscription feed,' a clear verb+resource combination. It distinguishes from sibling tools like 'list_subscriptions' and 'recent_changes' by focusing specifically on alerts from a subscription feed.

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 context, noting that polls work fine and that the same feed is accessible via a direct URL for scripts and dashboards. However, it does not explicitly state when not to use this tool or mention alternative tools like 'list_subscriptions'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it fans out to multiple sources, explains fallback logic (GDELT→GNews), and notes the USPTO soft-fail. No contradiction with annotations.

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

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

The description is relatively long but well-structured, with examples before technical details. Every sentence adds value, though some could be slightly tighter. It is front-loaded with query patterns, which is good for agent scanning.

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 the lack of an output schema, the description covers the tool's complexity: multiple data sources, fallback behavior, parameter formats, and the return structure (changes grouped by source, total_changes count, citation URIs). For a complex tool, this is thorough.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema: it provides usage examples for `since` (ISO date vs relative shorthand), recommends '30d' as a default, and clarifies that `value` accepts ticker or CIK. This extra context justifies a score above baseline 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?

The description provides a clear verb+resource: returns a change feed for a company. It includes multiple query examples and explicitly distinguishes from the sibling tool 'entity_profile', making the purpose unambiguous.

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

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

The description explicitly states when to use this tool (for 'what's new' queries) and when to use the alternative 'entity_profile' (for static profile). It also explains acceptable `since` formats and defaults, guiding the agent effectively.

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

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

Adds context beyond annotations: authenticated vs anonymous persistence, 24-hour expiry, key-value scoping. 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?

Concise, front-loaded, 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?

Covers purpose, usage, parameters, scope, persistence. Adequate for a simple write tool with no output schema.

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

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

Schema coverage 100% with clear descriptions. Description adds example key format but not much extra beyond schema.

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

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

Clearly states saving data for reuse later, with scope and pairing with recall/forget. Distinguishes from 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?

Explicitly says when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget, and differentiates session persistence.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: internal cascading through multiple endpoints, replacing 2-3 manual lookups, and details of returned fields per entity type (ticker, CIK, RxCUI, citation URIs). No contradictions.

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

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

The description is a single, well-structured paragraph that starts with example queries, provides usage instruction, and details returned data per type. Every sentence adds value; no fluff or repetition.

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

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

For a tool with 2 parameters and no output schema, the description thoroughly covers purpose, usage, parameter details, and return values (including citation URIs). It equips the agent with all necessary information to invoke and interpret results correctly.

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

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

Schema description coverage is 100%. The description enriches parameter semantics with concrete examples for 'value' (AAPL, 0000320193, ozempic) and clarifies accepted input formats for each 'type'. This goes beyond the schema's enum and string 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 resolves user-spoken names to canonical identifiers, with specific examples (ticker, CIK, RxCUI). It distinguishes itself from sibling tools by positioning as the first step when an ID is needed, and it enumerates supported entity types with detailed return fields.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID.' This provides clear guidance on when to invoke the tool. The description also implies it replaces multiple manual lookups, helping the agent prioritize it over alternatives.

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

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

The description adds valuable behavioral detail beyond annotations: it probes each entity with ai_visibility_check, ranks results by score, and surfaces most/least recognized. It also mentions output fields (score, confidence, signal density). No contradiction with annotations.

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

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

The description is concise (3 sentences), front-loaded with the main action, and each sentence adds distinct value. No wasted words.

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

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

Given the tool's complexity (4 parameters, no output schema), the description adequately explains what the tool does and what the output looks like (ranked list with score, confidence, signal density). It covers all necessary aspects 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 coverage is 100%, so baseline is 3. The description adds extra meaning: first entity is treated as 'subject' for narrative, and context is for disambiguation. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It uses a specific verb ('compare') and explains the resource ('AI visibility'), distinguishing it from the sibling 'ai_visibility_check' which handles single 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 provides clear context for when to use ('competitive AI-marketing audits') and implies not to use it for single entity checks (since it contrasts with ai_visibility_check). However, it does not explicitly list when not to use or compare to all 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 declare readOnly, idempotent, not destructive. Description adds fan-out behavior, graceful degradation, and timing for bundlephobia first measurement. Does not mention rate limits or auth.

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 and details. Slightly long but every sentence adds value. Could be more concise but acceptable.

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

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

Covers output format, failure modes, and default behavior. No output schema, but description lists returned fields. Missing error handling details beyond sources_failed, but sufficient for the complexity.

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

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

Schema coverage is 100% and descriptions are clear. The description does not add significant new information about parameters beyond what schema provides, just mentions version defaults.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from siblings by being specific to npm and composite.

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

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

Explicitly says when to use it: when an agent asks about safety, popularity, size, or cost. Also clarifies NPM-only scope and mentions fallback for other ecosystems. Partial failures and timing details are provided.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. Description adds valuable context: case-insensitive substring matching against specific name fields, and the returned data fields (id, name parts, role, party label). 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 efficient sentences: first states purpose, second details matching behavior and output. No redundant or irrelevant content.

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 3 parameters with full schema coverage, annotations present, and no output schema, the description sufficiently covers what the tool does, how to use it, and what it returns. No gaps.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds meaning beyond schema by explaining the matching logic (case-insensitive substring) and the specific fields searched (surname, first name). Also clarifies return fields.

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?

Explicitly identifies the tool as a convenience search over Tweede Kamer members/people by name, using specific verb (search) and resource (people). Distinguishes from siblings like 'search_within' and 'query_entity' by focusing on person name matching.

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

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

Implies usage for finding people by name but does not explicitly state when to use this tool versus alternatives like 'search_within' or 'query_entity'. No exclusion criteria or alternative names provided.

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

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

Annotations provide safety profile (readOnly, idempotent, non-destructive). Description adds technical details: embeddings model, window size, character cap with truncation flag, and offset return. No contradictions.

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

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

Three sentences plus technical details, front-loaded with purpose. Every 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?

All 3 parameters explained, annotations cover safety, description covers limitations and pairing. Comprehensive for a search tool without output schema.

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

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

Schema coverage is 100%, but description adds examples for query, default/max for limit, and explains text processing logic (windows, truncation). Significantly enriches parameter meaning.

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

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

The description clearly states the tool does semantic search inside a fetched record, returning top passages with offsets and scores. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and handling 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?

Explicitly says to use when the record is too big for the prompt, and pairs with another tool. Does not state when not to use, but provides clear context for appropriate use.

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

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

Annotations indicate mutation and idempotency. The description adds details: returns new ID, requires OAuth, type-specific params, delivery limits (SMS cap, webhook auto-disable), consistent with annotations.

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

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

The description is verbose but well-structured, covering purpose, requirements, types, and delivery in a logical order. Minor redundancy could be trimmed.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers return value, success conditions, and detailed behaviors. Lacks explicit response shape but mentions one-time secret for webhook.

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?

Even with 100% schema coverage, the description enriches parameters with examples, constraints (e.g., SMS phone must be verified, webhook secret one-time), and type-specific details 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 states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It clearly distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description includes prerequisites (OAuth account required) and examples for supported types and delivery options, but does not explicitly contrast with sibling tools or state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that results are drawn from the live catalog and include exact tool+argument shapes, which adds useful behavioral context beyond annotations.

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

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

The description is thorough but front-loaded with common queries. Every sentence adds value, though it could be slightly more concise. The structure effectively communicates purpose, output, and usage.

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

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

Despite no output schema, the description explains the return format (category-bucketed examples with tool+argument shapes) and covers parameters, usage, and output. It is fully complete for a one-optional-parameter tool.

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

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

Schema coverage is 100% with a concise parameter description. The description enriches it by listing example focus areas (finance, pharma, etc.) and explaining the behavior of omitting topic, providing additional meaning beyond the schema.

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

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

The description clearly states it returns category-bucketed example questions with tool+argument shapes, serving as an onboarding entry point. It distinguishes from siblings by mentioning meta-tools like ask_pipeworx, entity_profile, and 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to call with/without arguments. Provides clear context for when to use versus 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 (idempotentHint=true, destructiveHint=false), the description adds critical behavioral details: the row is deactivated not deleted, and historical events remain available via 'recent_alerts'. This fully informs the agent of side effects.

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

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

The description is two sentences with no wasted words. The action and key constraints are front-loaded, making it easy for an agent to quickly understand the tool's purpose and behavior.

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

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

For a simple tool with one parameter and no output schema, the description fully covers the function, ownership rules, and side effects. It relates to sibling tools like 'recent_alerts', providing sufficient context for 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% and the parameter 'id' is well-documented in the schema. The description adds context about ownership but does not provide additional semantic meaning beyond what the schema already captures, so a baseline score is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions' by specifying 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?

It provides clear context that only the owner can cancel their own subscriptions, which guides appropriate use. However, it does not explicitly state when not to use this tool or mention alternatives, leaving some ambiguity for edge 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 rich behavioral context beyond the annotations: it specifies the return format (verdict, structured form, actual value with citation, percent delta) and the domain limitation (company-financial claims only). This adds value over the readOnlyHint, openWorldHint, and idempotentHint annotations. 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 extremely concise at 3-4 sentences, front-loaded with example queries to quickly convey purpose. Every sentence adds value: examples, usage guidance, domain specification, and return format. No wasted words.

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

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

Given the tool's moderate complexity (claim verification with one parameter) and no output schema, the description fully explains what the tool does, when to use it, its domain limitations, and what it returns (verdict, structured form, actual value, citation, delta). 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?

With only one parameter and 100% schema description coverage, the baseline is 3. The description adds example inputs ('Apple's FY2024 revenue was $400 billion') which clarifies the format, but does not add much beyond what the 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: natural-language claim verification against authoritative sources, with specific examples like 'Is it true that...' and 'fact check'. It also specifies the domain (company-financial claims for public US companies via SEC EDGAR + XBRL), which distinguishes it from sibling tools like bet_research or 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 'Use whenever the agent needs to check whether something a user said is factually correct' and provides example phrases that trigger usage. It also mentions that it replaces 4-6 sequential calls, giving context for efficiency. However, it does not explicitly state when not to use it or list alternative tools for other types of claims.

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