Brreg No

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false, which are consistent with the description's 'probe' and 'returns' language. The description adds key behavioral context: default model is free, Anthropic requires BYO API key with cost implications, and the return structure includes per-model scores. No contradictions. Missing details on rate limits or error handling, but adequate.

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

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

Three concise sentences with no wasted words. First sentence states core purpose and output. Second details defaults and key parameter. Third mentions use cases. Information 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 4 parameters, no output schema, and annotations covering safety, the description explains return shape (per-model score, confidence, signals, raw response + combined view) and usage constraints. It doesn't cover error scenarios (e.g., missing API key for Anthropic), but the overall intent and data flow are clear. Adequately complete for a probe 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 meaningful examples for entity ('Pipeworx', 'OpenInvoice'), clarifies default model behavior, explains the pass-through nature of `_apiKey`, and provides a disambiguation example for context. This adds value beyond the schema descriptions.

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

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

Description clearly states the tool probes LLMs for knowledge about a business/topic and scores visibility (0-100). The verb 'probe' and resource 'LLMs knowledge' are specific, and the outcome is quantified. It distinguishes from sibling tools like ask_pipeworx (single model Q&A) and scan_competitor_ai_presence (likely different scope).

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

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

Description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies when to use the `_apiKey` parameter (needed for Anthropic). No explicit exclusions or alternatives are given, but the sibling tool names provide implicit context. Clear enough for an agent to determine applicability.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds context: it routes to 3774 tools, fills arguments, and returns structured answers with citation URIs, providing useful behavioral detail beyond annotations.

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

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

Two well-structured paragraphs: first sentence is a bold preference statement, then a list of domains, then usage cues and examples. Every sentence is informative without redundancy.

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

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

For a query tool with no output schema, the description mentions structured answers with citation URIs, which is adequate. It also explains routing and provides examples. Slightly lacking in error handling or output format details, but sufficient for agent use.

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

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

Schema has 6 parameters (all aliases for 'question') with 100% description coverage. The description adds value by explaining what kinds of questions to ask and providing usage examples, enhancing semantics beyond the schema.

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

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

The description clearly states that the tool is for factual questions about structured data, listing many domains (SEC filings, FDA, etc.) and distinguishing itself from web search. It uses specific verbs like 'ask' and resource 'pipeworx', and provides examples.

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 'PREFER OVER WEB SEARCH' and gives detailed when-to-use cues (e.g., 'what is', 'look up') and examples. It implicitly excludes unstructured or non-authoritative queries, and the preference over web search is clear.

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

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

Extends annotations with detailed refusal reasons, return format, and behavior (only uses tool result). No contradiction with annotations; provides rich behavioral context beyond readOnlyHint and idempotentHint.

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

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

Description is well-structured, front-loads purpose and use case, then details mechanism and return format. Slightly verbose but every sentence adds value; could be slightly shorter.

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

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

Despite no output schema, description fully specifies return format, refusal reasons, and behavior. Parameters are fully covered by schema. All necessary context for a complex tool is present.

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

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

Schema coverage is 100% with all parameters as aliases for 'question'. Description does not add additional meaning beyond what schema already provides, so baseline 3 is appropriate.

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

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

Description clearly states it's a hallucination-resistant answer mode for high-stakes reads, specifies it extracts answer only from tool result, and distinguishes from sibling ask_pipeworx by noting extra extraction step.

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

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

Explicit when to use (high-stakes, quoted/cited/acted on answers) and when not to (prefer ask_pipeworx for casual lookups). Also explains cost tradeoff of extra LLM call.

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

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

The description provides extensive behavioral details beyond the annotations (which indicate read-only, idempotent, non-destructive). It explains resolution, classification, fan-out, response shapes, safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. 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 front-loaded with the core purpose but is very lengthy with many details and examples. While each sentence adds value, the verbosity could be trimmed without losing clarity. Still, it is well-structured.

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

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

Given the tool's complexity (3 parameters, no output schema), the description comprehensively covers all aspects: input forms, classifiers, fan-out examples, response shapes, safety, and edge cases. An agent can use it correctly with full context.

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

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

Despite 100% schema coverage, the description adds significant meaning: it provides examples for `market` (slug, URL, question text), explains `depth` (quick vs thorough), and details `include_raw` (summary vs full payloads). It enriches understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb 'research' and the resource 'Polymarket bet via Pipeworx data,' and distinguishes it from sibling tools like ask_pipeworx and deep_research by focusing on a single bet with integrated data.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly mention when not to use it or provide direct alternatives, though siblings imply context.

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

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

The description goes beyond annotations by detailing data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and output format (paired data + citation URIs). It confirms read-only, idempotent behavior. No contradiction with annotations.

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

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

The description is dense and informative, starting with user-facing example phrases, then core functionality, then data details. Every sentence adds value, though the 'Replaces 8–15 sequential lookups' could be integrated into the usage guideline for slightly tighter structure.

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

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

With no output schema, the description explains return format (paired data + citation URIs) and data per type. It covers important edge cases like off-calendar fiscal years. Minor missing detail: whether revenue is in millions/billions or raw numbers, but overall sufficient 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?

Although schema coverage is 100%, the description adds rich semantic context: it specifies exactly what data each 'type' pulls (company vs drug), the acceptable values (tickers/CIKs, drug names), and the sorting behavior. This significantly aids parameter understanding beyond enum/type descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, listing specific data points per type (e.g., revenue, debt for companies; adverse events for drugs). It uses explicit trigger phrases like 'Compare X and Y' and distinguishes itself by replacing sequential lookups, making purpose very specific and distinct 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?

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' and gives example user intents. It defines the valid entity types and count range. No explicit when-not-to-use, but the context is clear enough for an AI agent to decide.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description adds key behaviors: returns verbatim evidence with gaps[], never invents, requires Pipeworx account, depth 'thorough' requires paid plan, and expected 15-60s wait. 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?

Four sentences, each earning its place: main purpose, how it works, usage guidance with alternative, and prerequisites/time estimate. No fluff, front-loaded with key action.

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

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

For a tool with no output schema, description comprehensively explains return format (findings packet with evidence, source, gaps[]), prerequisites (account), depth options, and time expectation. Covers all essential context an agent needs.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning: explains depth values (quick=3, standard=5, thorough=8) and notes paid plan for thorough, and clarifies question should be broad/multi-part as decomposition is the point.

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

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

Description clearly states it performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to tools in parallel. It distinguishes from sibling tools like ask_pipeworx, making the purpose unmistakable.

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

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

Explicitly says use for broad/multi-part questions and recommends ask_pipeworx for single lookups. Also mentions account requirements and depth plan limitations, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate read-only and idempotent behavior. The description adds valuable context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output's structure and operational advantage 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 two sentences, front-loaded with the verb 'Find' and a domain list. Every sentence adds value, no fluff. The structure is logical: purpose, usage, output benefits.

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

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

Given no output schema, the description sufficiently explains return value (top-N tools with schemas). It covers purpose, usage scenarios, parameter semantics, and output structure. Examples in the input schema also aid understanding. No gaps for a discovery tool.

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

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

Schema coverage is 100%, but the description adds semantic value by explaining that the main parameter 'query' accepts a 'Natural language description of what you want to do' and provides examples. It also clarifies that aliases (task, q, search, description) are accepted, though these are already in the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, financials, etc.), making the scope concrete. This distinguishes it from sibling tools like search_entities or get_entity, which operate on data rather than discovering tools.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set.' It also lists use cases ('when you need to browse, search, look up, or discover'). However, it does not explicitly state when NOT to use it (e.g., when you already know the exact tool), though this is implied.

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 the fan-out across multiple sources, specific return fields, limitations (patents API sunset), and fallback behavior (GDELT→GNews). No contradiction with readOnly annotation, and adds significant value beyond annotations.

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

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

The description is detailed but not overly verbose. Every sentence adds value. Front-loaded with example queries. Could be slightly more concise, but appropriate for the complexity.

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

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

Given the tool's complexity, no output schema, and multiple data sources, the description covers all essential information: input format, return fields, limitations (patents, names), and fallbacks. Fully informs the agent's decision and usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: clarifies that value can be ticker or CIK (zero-padded), explains the type enum's future expansion, and warns that names are not supported. Enhances schema 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's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It uses specific verbs ('profile', 'fans out') and resources (SEC EDGAR, XBRL, etc.) and distinguishes from sibling tools like resolve_entity 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 to prefer this over chaining multiple lookups for a holistic view, and advises using resolve_entity if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description consistently states deletion, adding no contradiction, though it adds little beyond annotations.

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

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

Two sentences, no redundancy, efficiently communicates purpose 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?

For a simple one-parameter tool with no output schema, the description fully covers what the tool does and when to use it, including sibling relationships.

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

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

Schema coverage is 100% with parameter description already provided. Description adds no new parameter details beyond 'by key', but context about pairing with siblings is helpful but not directly parameter-related.

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

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

Description clearly states it deletes a stored memory by key, distinguishing it from sibling tools like remember and recall.

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

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

Provides specific use cases (stale context, task done, clearing sensitive data) and suggests pairing with remember and recall. No explicit when-not, but sufficient for a simple tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This enhances transparency without contradicting annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by process and use cases. Every sentence adds value with no redundancy or fluff.

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

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

Despite no output schema, the description explains the output format: 'standard llms.txt markdown format' and 'single text blob ready to drop at site-root/llms.txt'. It covers what the tool does, how it works, use cases, and output. For a simple tool with two parameters and good annotations, this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new meaning beyond the schema for the two parameters. It mentions extraction of title/description/key links, but that's about output, not parameter semantics.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and the target 'any URL'. It explains the tool's purpose: to help AI crawlers index a site cleanly. This distinguishes it from siblings like ai_visibility_check or scan_competitor_ai_presence, which have different functions.

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

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

The description lists three explicit use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. This provides clear context for when to use the tool. It does not explicitly exclude cases or mention alternatives, but the use cases are sufficiently specific.

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. The description adds value by detailing the return structure (array with fields for income statement, assets, equity, etc.) and providing an example, which is beyond what annotations offer.

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 plus an example, efficiently conveying purpose, return structure, and usage. No unnecessary words.

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

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

Given the simple tool with one required parameter, read-only annotations, no output schema, the description sufficiently explains the return format and provides a usage example, making it complete for an agent to use.

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

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

Schema coverage is 100% for the single parameter 'orgnr', with a description. The description adds an example call, reinforcing usage but not adding significant new 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 provides 'Annual financial statements' for an entity using a 9-digit org number. The verb 'get' and resource are explicit, and the tool is distinct from sibling tools that search 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 implies when to use (when needing financial statements by org number) but does not explicitly state when not to use it or mention alternatives. No exclusions or alternative tool references 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 readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds no behavioral contradictions and provides some additional context about returned fields, but does not disclose further behavioral traits beyond the annotations.

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

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

The description is a single, efficient sentence with an example and relevant field listing. 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 one parameter, high schema coverage, and comprehensive annotations, the description is sufficient for an agent to correctly invoke the tool. It lists return fields, which compensates for the lack of an output schema.

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

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

Schema coverage is 100% with one parameter described. The description adds an example value and lists expected fields in the response, providing meaning beyond the bare 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 the full record of one entity using a 9-digit org number, with an example and list of returned fields. It distinguishes from siblings like search_entities which are for 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 implies usage when you have an exact org number and need full details, but it does not explicitly state when not to use or mention alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a clear safety profile. The description adds context about the types of roles returned (e.g., styre, daglig leder) but does not disclose behavioral traits beyond what annotations provide. It does not contradict annotations.

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

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

The description is two sentences: the first lists the purpose and examples, the second gives the format. It is concise, front-loaded, and contains no unnecessary words.

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

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

Given the simplicity of the tool (one required parameter, no output schema), the description sufficiently explains what the tool returns with concrete examples. It could add details about the output format but is complete enough for a lookup 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?

The input schema describes 'orgnr' as a 9-digit string with an example. The description repeats this information without adding deeper semantics. Since schema coverage is 100%, the description does not need to compensate, but it adds minimal 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 gets roles for an entity by 9-digit org number, with specific examples of roles (board members, CEO, chair, auditor, etc.). It distinguishes from siblings like 'get_accounts' or 'get_entity' which serve different purposes.

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

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

The description specifies the required input format (9-digit org number) and provides an example, giving clear context for when to use the tool. However, it does not explicitly mention when not to use it or list alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool's safety is covered. The description adds that it returns the 'full record', but does not elaborate on additional behavioral constraints.

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

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

The description is a single sentence with a concrete example, front-loaded with the key action. No extraneous 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?

For a simple retrieval tool with one parameter, comprehensive annotations, and no output schema, the description is complete enough to guide 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 description coverage is 100% with clear parameter documentation. The description provides an example but does not add new meaning beyond the schema.

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

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

The description clearly states the tool returns the full record for one sub-entity by its 9-digit organization number, with an example. This distinguishes it from siblings like 'get_entity' (main entities) and 'search_sub_entities' (search).

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

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

The description specifies using a 9-digit org number, providing clear context for when to call this tool. It does not explicitly state when not to use or list alternatives, but the sibling set implies search for non-exact matches.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the specific fields returned and the optional parameter behavior, which complements annotations well.

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

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

Two concise sentences front-load purpose and fields, followed by usage guidance; 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 comprehensive annotations, a single simple parameter fully documented in schema, and the inclusion of return fields in the description, the tool definition is complete for its complexity.

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

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

Schema coverage is 100% with a clear description for the only parameter (include_inactive). Description adds no extra parameter details beyond what the schema provides, meeting baseline.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies returned fields, and distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises when to use the tool (to review before adding more or to find an id to cancel), providing good contextual guidance even without explicit 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 (which are all false), the description adds important behavioral context: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also discloses that feedback is reviewed daily and influences roadmap. There is no contradiction with annotations.

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

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

The description is well-structured with clear sections: purpose, usage cases, tips, and constraints. It is slightly long but each sentence adds value. It front-loads the core purpose and then provides details, making it easy to scan.

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

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

For a simple feedback submission tool, the description provides complete information: what to submit, when to use each type, how to structure the message, rate limits, and impact. No output schema is needed, and the description is self-sufficient.

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

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

The input schema covers all parameters with descriptions (100% coverage). The description adds value by providing guidance on how to write the message: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This extra instruction enhances the parameter semantics 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 the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It breaks down the purpose into specific categories (bug, feature/data_gap, praise), making it clear what the tool does. Sibling tools do not include any feedback-related tool, so differentiation is not required.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also tells what not to do: 'don't paste the end-user's prompt.' Additionally, it mentions rate limits and quota, giving clear context for appropriate usage.

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

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

Annotations already mark it read-only, idempotent, non-destructive. The description adds valuable context: self-aggregating from CF analytics, no PII, cached 5min-1h. No contradictions.

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

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

The description is multiple sentences but compact and well-structured. It front-loads the key output statement then lists use cases. Slightly verbose but efficient overall.

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 tool with one optional parameter and no output schema, the description fully covers return values (top tools, packs, volume), caching behavior, and data privacy. No gaps for the complexity level.

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

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

The schema covers the single parameter with enum and description. The description adds semantic value by explaining window trade-offs (shorter windows show hot trends, longer show steady-state demand), enriching the enum 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 what the tool does: returns top tools, packs, and call volume over a window. It distinguishes itself from siblings like discover_tools by focusing on trending/hot data rather than general discovery.

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

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

The description lists three specific use cases (discovering hot data sources, confirming canonical tool, aligning use case). However, it does not explicitly mention when not to use or contrast with alternatives like discover_tools.

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

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

Annotations (readOnlyHint, idempotentHint, non-destructive) are consistent. Description adds significant behavioral detail: REQUIRES one argument, explains the partition check (sum ≈1, deviations >3pp trigger signal), semantic anchor for cross-event pairs, placeholder filter, fill check comparing theoretical vs realizable edge. No contradictions.

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

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

Description is well-structured with labeled sections (REQUIRES, event, topic, semantic anchor, etc.) and front-loaded with the requirement. It is verbose but each sentence is informative for a complex tool. Minor redundancy (e.g., 'call with no args fails' appears both as note and in description).

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 key aspects: modes, filters (Jaccard, placeholder), response structure (opportunities, partition_check, fill check). No output schema, but response fields are described. Mentions related tool for custom sizing. Could include more detail on exact output format but sufficient for an AI agent.

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

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

Both parameters (event, topic) have schema descriptions (100% coverage). The description adds context: event accepts Polymarket slugs or URLs, topic takes a seed question for cross-event scanning. It clarifies exclusive-or requirement and provides examples, adding value beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, with specific modes (event, topic) and a verb ('Find'). It distinguishes from siblings like polymarket_fill_risk (pricing) and polymarket_edges (edge analysis) by focusing on arbitrage detection.

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

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

Explicit guidance on when to use event mode vs topic mode, including a recommendation ('event recommended for a specific market'). Provides exclusions: calling with no args fails, and cross-event pairs require ≥0.30 Jaccard similarity. References sibling tool polymarket_fill_risk for custom sizing, indicating when to defer.

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, non-destructive), the description discloses cache duration (1h), output structure (by_segment with three segments), edge calculation details, and diagnostics. 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 well-structured with sections and front-loaded purpose, but it is lengthy (nearly 400 words). Some details could be condensed without losing clarity, making it slightly verbose.

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

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

Given the complexity (9 parameters, no output schema), the description fully explains response segments (model_driven, structural_arbitrage, concentrated_longshot), diagnostics for empty outputs, caching, and knob effects. It leaves no major gaps for an agent to misuse the tool.

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

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

While the input schema covers all 9 parameters (100% coverage), the description adds practical guidance, e.g., for min_liquidity: 'Set to 5000 to drop thin-book opportunities' and for min_partition_leg_kelly: explains its role. This adds meaningful context beyond parameter 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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' providing a specific verb and resource. It is distinct from siblings like polymarket_arbitrage by focusing on Pipeworx-based edge detection rather than pure 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 implies usage for discovering betting opportunities ('what should I bet on today') but does not explicitly mention when to avoid this tool or compare it with alternatives like polymarket_arbitrage. No exclusions or conditions 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?

Describes data source (daily snapshots), limits (60-day TTL), computation (decay from daily closes), and output structure. No contradiction with annotations (readOnlyHint=true, etc.). Exceeds annotation coverage.

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 core purpose, then details output structure. Informative but slightly verbose; still efficient for the information conveyed.

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

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

Comprehensively covers behavior, output fields, data source, and limitations. Compensates for lack of output schema. Handles both parameters with defaults. Well-rounded for a telemetry 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 already describes parameters with types and defaults (100% coverage). Description adds slight context (e.g., 'default 14, max 30' for days) but does not significantly enhance 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?

Clearly states the tool provides edge persistence and decay telemetry from daily snapshots. Answers specific question about edge duration and distinguishes between fresh and old edges, differentiating from sibling tool polymarket_edges.

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

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

Explains usage context: assessing edge persistence over time, with example of fresh vs. old edges. Does not explicitly state when not to use or mention alternatives, but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral details: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical vs realizable sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. Warns of risk of unhedged directional positions on partial fills. No contradictions.

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

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

Well-structured: purpose sentence, then REQUIRES, then bulleted mode explanations, then usage guidance. Each sentence adds value. Slightly verbose in the basket return description, but appropriate for complexity. Front-loaded with key information.

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

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

Despite no output schema, description fully documents all return fields and their semantics for both modes. Covers edge cases (thin legs, forced directional risk) and provides intuitive explanation of basket mechanics. Complements sibling tool context by specifying pre-usage requirement.

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

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

Schema coverage is 100% with good descriptions, but description adds critical context: explains dual-mode requirement (one of market or event), clarifies side meaning in both modes (including auto-detection for basket), and elaborates on size_usd interpretation (max spend vs target proceeds for single-market, settlement notional for basket). Far exceeds baseline.

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

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

Description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth, with specific verb 'check' and resource 'Polymarket fill risk'. It distinguishes two modes (single-market and basket) and prefaces usage against sibling tools 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?

Explicitly states when to use this tool: before acting on polymarket_arbitrage sell/buy-every-leg signals or polymarket_edges trades above ~$500. Explains why (theoretical overround not capturable on thin books, partial basket fills create unhedged directional positions).

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral detail: response includes leg-by-leg prices, spreads, safety fields, temporal alignment, and skip counters. It explains when spreads are meaningless (e.g., temporal gap, non-equivalent bet shapes). 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 structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the main purpose. However, it is fairly long and contains some repetition (e.g., 'pre-mapped' mentioned multiple times). Slightly more conciseness would improve.

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 (3 parameters, no output schema), the description thoroughly covers modes, response format, safety fields, and caveats like temporal alignment and skip counters. It provides enough context for an agent to understand when spreads are meaningful and how to interpret results.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining topics, how explicit tickers override, and the purpose of each parameter. It also provides examples in the schema. This goes beyond the schema alone.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, distinguishing it from siblings like 'polymarket_arbitrage' by specifying it compares the same resolving question across two venues. The verb 'cross-venue spread' and the explanation of two modes provide precise purpose.

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

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

The description explains two modes (topic shortcuts and explicit tickers) and warns that many pre-mapped topics return compatibility_warning, indicating they are not tradeable. It says 'pre-mapped ≠ tradeable', giving caveats. However, it doesn't explicitly tell when not to use this tool (e.g., for single-venue analysis) or suggest alternative tools.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining behavior when key is omitted (list all keys), scoping by identifier, and the pairing pattern. No contradictions.

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

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

The description is concise yet comprehensive, starting with core functionality, then usage, scope, and pairing. Every sentence adds value without unnecessary words. Well-structured for quick comprehension.

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 could specify return format, but for a simple retrieval tool with one parameter and low complexity, it is sufficiently complete. Annotations cover safety, and the description includes scoping.

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

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

Schema coverage is 100% with one parameter 'key'. The description adds meaning by stating 'omit to list all keys', which clarifies the parameter's optional behavior beyond the schema's description. No further detail needed.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys if omitted. It distinguishes from sibling tools 'remember' and 'forget' by specifying the retrieval action, 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 advises use for looking up stored context without re-deriving from scratch, and notes pairing with 'remember' and 'forget'. It does not explicitly state when not to use, but the context is clear given the scope and sibling tools.

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

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

Annotations already mark readOnlyHint=true, but the description discloses an optional mutation (mark_read:true) that marks events as read, contradicting the annotation. Despite this, the description honestly explains the side effect and return fields (source, citation_uri, raw payload), adding value beyond annotations. The transparency is good, but the contradiction with annotations slightly reduces the score.

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 of five sentences that front-loads the main purpose. Every sentence adds value: stating the action, detailing return fields, listing filters, explaining a flag, and noting polling/alternative access. No unnecessary words.

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

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

Given 5 parameters, no output schema, and informative annotations, the description thoroughly covers what the tool returns, how to filter, the side effect of mark_read, and polling suitability. It also references an alternative API, making it complete for a 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 coverage is 100% with basic descriptions, but the tool's description adds meaningful context for parameters: it gives an example for 'type' ('sec_8k'), explains the effect of 'mark_read' on future calls, and clarifies 'unread_only' behavior. This goes beyond the schema, earning a 4.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It distinguishes itself from siblings by specifying that it returns the most recent alerts with specific fields and mentioning an alternative GET endpoint, making the purpose distinct and unambiguous.

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

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

The description provides context on when to use the tool (to get recent alerts) and offers an alternative via a GET endpoint for scripts/dashboards. It implicitly guides usage with filtering options and polling advice, but does not explicitly state when not to use it or compare to other tools, which is acceptable given the sibling tool set.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: parallel fan-out across multiple sources, fallback from GDELT to GNews when rate-limited or 5xx, and soft-fail for patents. It explains the return structure (changes[] grouped by source, total_changes, citation URIs). While authentication and error details aren't covered, the description complements annotations well.

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

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

The description is a single paragraph but front-loads the core purpose and usage examples. Every sentence adds value: usage patterns, source details, fallback, and alternative tool reference. It could be slightly more scannable with bullet points, but it is concise and avoids redundancy.

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

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

Given the tool's complexity (multiple data sources, fallback, soft-fail, no output schema), the description covers most essential aspects: what it does, which sources, how parameters work, what is returned, and when to use an alternative. It does not specify error handling or pagination behavior, but these are minor gaps for a monitoring-oriented 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?

Input schema coverage is 100%, with detailed descriptions for all parameters. The tool's description adds minimal new information for parameters beyond the schema; it reuses examples from the schema (e.g., '7d', '30d') but does not introduce new semantic distinctions. Since the schema already handles parameter semantics, the description's incremental value is moderate.

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: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the exact resources queried (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes itself from the sibling tool 'entity_profile': 'Use entity_profile instead when you want the static profile...' This makes the purpose highly specific and differentiated.

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

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

The description provides explicit usage examples (e.g., 'What's new with X', 'latest on Y') and explains when to use the tool vs. alternatives: 'Use entity_profile instead when you want the static profile...' It also details fallback logic (GDELT→GNews) and a known limitation (PatentsView API sunset). No ambiguity remains.

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 behavioral context beyond annotations: scoped by identifier, authenticated persistent, anonymous 24h retention. Annotations indicate idempotent (overwriting same key), which is consistent. 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?

Concise four-sentence structure, front-loaded with purpose, then usage and behavior. Every sentence adds value without redundancy.

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

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

Given simple key-value tool with high schema coverage and good annotations, the description covers use cases, persistence duration, and integration with sibling tools (recall, forget). 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 coverage is 100% with clear descriptions for key and value. Description adds general context but does not enrich parameter meaning beyond what schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with concrete examples (ticker, address, preference). It distinguishes from sibling tools like recall and forget by mentioning them explicitly.

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 strong guidance: 'Use when you discover something worth carrying forward' and mentions pairing with recall/forget. Also explains scoping and persistence differences based on authentication. Lacks explicit 'when not to use' but overall clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds valuable behavioral context: each call cascades through several lookup endpoints, and it details what is returned for each type (e.g., ticker, CIK, citation URI for companies; RxCUI, ingredient, brand for drugs). No contradictions.

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

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

The description is well-structured, starting with example queries, then usage directive, then detailed type explanations. Every sentence contributes value. Slightly verbose but not excessive; could be tightened slightly.

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 two entity types and no output schema, the description is thorough: it explains return values including citation URIs, input variants, and internal cascading. It does not cover error cases or limits, but overall completeness is high for a lookup 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%, but the description adds significant meaning: it explains accepted input formats for each type (e.g., ticker, CIK, or name for company; brand or generic for drug) and provides examples. This enriches understanding beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers with concrete examples like 'What's the ticker for…' and 'find the CIK for…'. It specifies supported types (company, drug) and distinguishes itself from sibling tools by noting it replaces 2-3 manual lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It implies when not to use (if ID is already known), but does not name alternatives among siblings, though context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, treats the first entity as subject, and returns score, confidence, and signal density. No contradictions.

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

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

The description is two sentences: the first states the core functionality, the second adds use case and output summary. It is front-loaded, concise, and 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?

Without an output schema, the description explains return values (ranked list with score, confidence, signal density). It also mentions the subject treatment and constraint (2-8 entities). While it omits error handling, the tool is straightforward and the description is reasonably 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%, so baseline is 3. The description adds meaning beyond schema by stating the first entity is treated as the 'subject' for narrative, which is not in the schema. This extra semantic detail justifies a 4.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities. The verb 'compare' and resource 'AI visibility' are specific, and the competitive audit use case differentiates it.

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 frames the tool for competitive AI-marketing audits with an example question, implying when to use it. It does not explicitly state when not to use it, but the context of comparing multiple entities vs. a single check is clear enough for an agent to decide.

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

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

Annotations already declare safe read-only behavior (readOnlyHint, idempotentHint, not destructive). The description adds significant detail beyond annotations: partial failure degradation, bundlephobia timing (5-30s first measurement), and that sources_failed lists timeouts. No contradiction with annotations.

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

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

The description is informative and front-loaded with the main purpose and usage. While lengthy, every sentence adds value. Minor redundancy in listing output fields could be trimmed, but overall well-structured.

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

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

Despite lacking an output schema, the description details the return structure (summary block fields, per-advisory, links, alternatives). It covers edge cases like partial failures and new version timing, and ecosystem limitations, making the tool behavior fully predictable.

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 clear descriptions for both parameters. The description adds nuance: scoped packages '@types/node' accepted explicitly and default version behavior. This adds value beyond the schema's 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 starts with a clear composite purpose: 'should I add this npm package to my project' check. It names specific data sources (deps.dev, bundlephobia) and explicitly states the npm ecosystem scope, distinguishing it from sibling tools that don't perform this composite check.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clarifies when NOT to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear boundary and alternative.

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 and idempotentHint. Description adds value by explaining output structure (_embedded.enheter) and field meanings, 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?

Efficient 3-sentence description that starts with action, explains output, maps fields, and gives 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?

Covers purpose, parameters, examples, and output structure. Lacks mention of edge cases (e.g., no results) but sufficient for effective use given annotations.

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

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

All 5 parameters have schema descriptions (100% coverage). Description adds examples and clarifies Norwegian field meanings, providing additional semantic 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 it searches Norwegian companies by name and filters, with specific field mappings. It distinguishes from siblings like get_entity 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?

Provides concrete examples of usage but does not explicitly mention when not to use or alternative tools. The context is clear for typical search scenarios.

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

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

Annotations already cover read-only and idempotent behavior; description adds that results appear under '_embedded.underenheter' and gives a concrete filter example, providing useful 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?

Two sentences plus example, front-loaded with the action, no unnecessary words.

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

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

Covers core filtering and result structure, but does not mention pagination or municipality filter; still adequate 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 covers all parameters with descriptions. Description repeats mention of two parameters and gives example, but adds little beyond schema for a high-coverage baseline.

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

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

Description clearly states 'Search sub-entities/branches' with a specific noun and verb, includes an example, and distinguishes from sibling tools like search_entities and get_sub_entity.

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

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

Description explains filtering by overordnetEnhet and navn with an example, but does not provide explicit when-to-use or when-not-to-use guidance compared to 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K) with truncation and flagging, and that passages have offsets. This goes well beyond annotations and is highly transparent.

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 efficiently structured: a bolded first sentence conveys the core action, followed by brief explanations of use case, pairing, and technical details. Every sentence serves a purpose without redundancy, making it easy to scan and understand.

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

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

Despite lacking an output schema, the description explains what the tool returns (top-N passages with offsets and similarity scores). It covers inputs, behavior (truncation/flagging), and pairing with another tool. Given the annotations already signaling safety and idempotency, the description is fully complete for an agent to select and invoke the tool correctly.

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

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

Input schema has 100% coverage with descriptions for all three parameters. The description adds example queries (e.g., 'supply-chain risk') and reinforces the text size limit. While schema already covers the basics, the examples help an agent understand the query style, adding modest value beyond schema.

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

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

The description clearly defines the tool as 'semantic search INSIDE a fetched record', specifying the verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and implying a different use case than other search tools like search_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 states when to use the tool: 'Use when the record is too big to cram into the prompt'. It also explains benefits (saves context, returns relevant passages with offsets) and pairs it with another tool. While it doesn't explicitly list when not to use, the context is clear.

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

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

The description explains the creation behavior, return of subscription id, account requirements, and delivery constraints (e.g., SMS cap, phone verification). Annotations indicate no destruction or read-only, which aligns. Could mention if subscriptions are appended or overwritten.

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

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

The description is information-dense but front-loaded with the core purpose and return value. Every sentence adds value, but it is somewhat lengthy. Could be slightly more structured.

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

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

Given the tool's complexity (multiple subscription types, nested delivery objects, webhook signing), the description is thorough—covers return value, account requirements, limits, and type-specific details. No output schema, so the return value is adequately described.

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

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

Schema coverage is 100%, so baseline 3. The description adds real-world examples, type-specific param structures, and delivery channel requirements, providing meaningful context beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, distinguishing it from sibling tools like list_subscriptions and unsubscribe. It uses specific verbs and resources.

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 on when to use the tool (proactive monitoring), prerequisites (Pipeworx OAuth account), and supported types/delivery channels. It indirectly distinguishes from siblings but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds onboarding context and output description but no new behavioral traits (e.g., no side effects beyond reading). 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 somewhat lengthy but well-structured, front-loaded with common user queries, and uses visual separation (dashes for categories). Every sentence adds value; could be slightly more compact without losing clarity.

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

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

Given a single optional parameter and no output schema, the description fully explains the return value (category-bucketed examples with tool+argument shapes), when to call (first, or to learn meta-tools), and how to customize (topic). No gaps identified.

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

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

Schema has 100% coverage for the single optional parameter. The description adds meaning by explaining the effect of passing a topic (focus area) and listing example values, which goes beyond the schema's terse 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 specifies the verb 'returns category-bucketed example questions' with exact tool+argument shapes, distinguishing it as an onboarding entry point. It clearly differentiates from sibling tools like ask_pipeworx or discover_tools by stating its purpose for initial orientation.

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: 'FIRST when you do not yet know what Pipeworx can do' and to learn meta-tool calls. Provides invocation guidance (no arguments vs. topic). Lacks explicit when-not-to-use or alternatives, but context is clear given sibling 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?

Discloses ownership enforcement and deactivation behavior (not deletion), which goes beyond annotations (which show destructiveHint=false). No contradiction.

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

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

Two sentences efficiently convey action, constraint, and effect with no wasted words.

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

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

For a simple one-parameter tool with no output schema, the description covers ownership, outcome, and ties to related tools (recent_alerts), making it complete.

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

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

Schema already fully describes the single parameter (id) with its type and origin. Description adds no further semantics, so baseline 3 is appropriate.

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

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

Clearly states the action: cancel a subscription by id. Distinguishes from subscribe and mentions deactivation vs deletion, making 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?

Explicitly states ownership enforcement: only own subscriptions can be canceled. Also explains that deactivation keeps history accessible via recent_alerts, giving usage context 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: returns specific verdicts, uses SEC EDGAR+XBRL, provides citation and percent delta. 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 somewhat lengthy but each sentence adds value: triggers, use case, domain, return values, efficiency benefit. It is front-loaded with triggers. No unnecessary words.

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

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

Given a single parameter, no output schema, and moderate complexity, the description adequately explains the claim domain, return structure (verdicts, citation, delta), and operational context (SEC EDGAR+XBRL). Annotations cover safety. Leaves no major gaps.

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

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

Schema coverage is 100% with a clear description of the 'claim' parameter. The tool description adds examples of natural-language queries, but the parameter description is already sufficient. Baseline of 3 is appropriate.

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

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

The description starts with natural-language triggers and explicitly states the use case: 'check whether something a user said is factually correct.' It specifies the domain (company-financial claims via SEC EDGAR+XBRL) and return structure, and distinguishes itself from siblings by noting it replaces 4-6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies the domain limitation (company-financial claims) but does not explicitly state when not to use it. However, the sibling context provides alternatives, and the description is clear on scope.

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