Lemmy

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by explaining that the default model is free, Anthropic probing requires a BYO key with direct billing, and the output structure. No contradictory statements.

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-loading the core action and output. Every sentence serves a purpose: action, parameter details, and use cases. No redundant or vague wording.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, for a read-only probed tool), the description is complete. It explains the return format (per-model + combined), the conditions for using Anthropic, typical use cases, and parameter roles. No missing essential context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by specifying the default model (Workers AI Llama-3.3-70b free), that _apiKey is passed through to Anthropic, and that context helps disambiguation. This extra context 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 the tool's action (probe LLMs, score visibility 0-100 per model) and resource (business/brand/product/topic). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on per-model visibility scoring and returning structured results.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not mention when not to use it or compare it directly to sibling tools. Clear context, but no exclusions or alternatives given.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive hints. The description adds valuable context: it routes to 3,745 tools, fills arguments, and returns structured answers with stable citation URIs. It does not contradict annotations and provides behavioral insights beyond them, though it could mention potential latency or limitations.

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

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

The description is front-loaded with key instruction 'PREFER OVER WEB SEARCH'. It includes examples and is well-structured, but slightly verbose with the list of domains and example queries. Still, it is efficient and each sentence adds value.

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

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

Given the tool's complexity (router to many sources) and no output schema, the description adequately explains its behavior, including citation URIs. It covers when to use, how it works, and what to expect. It is complete enough for an AI agent to decide when to invoke.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides usage examples and clarifies that the question is in natural language, which adds value beyond the schema's alias list. The examples help the agent understand the expected input format.

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 routes questions to a large set of tools for authoritative structured data with citations, distinguishing it from web search by explicitly preferring over it. The verb 'ask' and resource 'Pipeworx' are specific, and it differentiates from sibling tools like 'ask_pipeworx_grounded' by emphasizing its routing capability.

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 to prefer over web search for factual questions about real-world entities, listing specific domains (SEC filings, FDA data, etc.) and example queries. It also conveys when to use the tool (e.g., 'what is', 'look up') and implicitly excludes non-factual or creative tasks, though no explicit 'when not to use' is given.

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, openWorldHint, idempotentHint, and non-destructive. The description adds key behavioral details: same routing as ask_pipeworx, extraction only from tool result, refusal mechanism, and return structure. This significantly enriches the agent's understanding 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 a single paragraph with a clear front-loaded purpose statement. It includes some technical details (3,745 tools, 884 sources) that may not be essential for selection but do not significantly harm conciseness. Slightly verbose but still effective.

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

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

Given the tool's complexity (effectively one parameter, no output schema), the description provides a complete picture: it explains the return format, refusal reasons, and when to use. Annotations cover safety and read-only behavior. No gaps remain.

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

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

Schema coverage is 100% with descriptions for each parameter, but they are identical aliases for 'question'. The description does not add per-parameter semantics beyond the schema, which already explains the parameter is a natural language question. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies that it extracts answers using only the tool result and distinguishes from the sibling ask_pipeworx by noting the extra LLM call cost and preference for casual lookups.

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

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

Explicit guidance on when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also states when to prefer the alternative: 'Prefer ask_pipeworx for casual lookups.' Provides refusal reasons for clarity.

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

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

The description extensively discloses behavioral traits beyond the annotations (which already mark it as read-only/idempotent): safety short-circuits for low-confidence matches, closed market handling, wide-spread warnings, resolution-rule risk parsing, parent event extraction, news fallback behavior, and response shape details. No contradiction with annotations.

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

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

The description is lengthy but highly informative; every section serves a purpose. It front-loads the main verb and resource, then systematically covers classifiers, fan-out examples, response shapes, resolver contract, parent event, news fields, and safety. Could benefit from clearer section breaks, but overall earns its length.

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

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

Given the tool's complexity (3 parameters, 1 required, no output schema), the description thoroughly covers input, behavior, edge cases (closed markets, low-confidence matches, wide spreads, resolution risk), and response structure (market, analysis, evidence, resolver info). No output schema exists, so the description compensates fully, making the tool complete for agent invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining parameter behavior in context (e.g., `include_raw` false keeps responses under 20KB, `depth` quick vs thorough fan-out) and provides examples for `market` input formats, exceeding baseline without being redundant.

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

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

The description clearly states the action ('Research a Polymarket bet'), the object ('Polymarket bet'), and the method ('pulling the relevant Pipeworx data for it in one call'). It specifies three input formats and provides example use cases ('should I bet on X', 'what does the data say about Y'), distinguishing it from sibling tools like polymarket_edges by emphasizing evidence packets and market-vs-model comparison.

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

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

The description explicitly states when to use the tool ('Use for...') and provides numerous examples of classifier categories and fan-out patterns. However, it does not explicitly state when not to use it or directly contrast with siblings. The guidance is clear but not exhaustive in terms of exclusions.

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. Description adds that it returns specific fields and is for reading, but does not disclose additional behavioral details beyond what annotations provide.

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

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

Two concise sentences with no wasted words, front-loaded with the action and resource, then details and use case.

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 0% parameter description coverage and 8 optional parameters, the description is insufficient for agents to correctly invoke the tool without additional schema inspection. Output schema exists but doesn't mitigate lack of parameter guidance.

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 0%, yet description fails to explain any of the 8 parameters (page, sort, limit, post_id, instance, community, max_depth, parent_id). Only mentions 'post or thread' broadly, leaving agents without guidance on parameter usage.

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

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

Description clearly states the tool lists Lemmy comments under a post or thread, specifies returned fields (author, body, score, parent, posted date), and distinguishes from siblings like 'post' or 'posts' by targeting comments specifically.

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 indicates use case ('read discussion threads') and provides context ('federated Reddit-alternative communities'), but lacks explicit when-not-to-use or alternative tool mentions.

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 no behavioral context beyond annotations. 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 very short (two words), which is concise but under-specified. It could include a bit more detail without being 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 5 undocumented parameters and no parameter guidance in the description, the tool's overall completeness is low. The presence of an output schema does not compensate for the lack of parameter context.

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

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

Schema description coverage is 0%. The description does not explain any of the 5 parameters, which the rubric requires when coverage is low. The description fails to add 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 'List communities' clearly states the verb and resource, but does not distinguish from the sibling tool 'community' which likely returns a single community. The purpose is still clear.

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?

No usage guidelines provided. The description does not indicate when to use this tool over alternatives like 'community' or other list tools.

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

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

Annotations already declare readOnlyHint and other safety traits. Description adds no behavioral details beyond annotations, such as error behavior or required permissions.

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

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

Extremely concise but lacks substance. While short, it does not earn its place as it provides minimal useful information.

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

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

Given the tool's simplicity and existing output schema, the description is still too brief. It does not clarify what 'metadata' includes or how to distinguish from similar tools.

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

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

Schema coverage is 0%, and description 'Community metadata.' does not explain any parameter. The parameters 'instance' and 'name_or_id' are left completely undocumented.

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 'Community metadata.' is vague; it does not specify an action verb or what exactly the tool does. It restates the name and adds 'metadata' but lacks clarity on the operation (e.g., 'get metadata for a specific community').

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?

No guidance on when to use this tool versus siblings like 'communities' (list) or 'entity_profile'. The description fails to provide 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?

Description adds significant behavioral context beyond annotations: specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and output including citation URIs. Annotations (readOnly, idempotent) are consistent and description complements them.

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

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

Description is fairly long but front-loaded with trigger phrases and essential info. Every sentence serves a purpose (usage, data sources, output format). Could be slightly more concise, but efficiency is high given the richness.

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 multi-type comparison tool with no output schema, the description fully explains inputs, data sources, sorting, and output format (paired data + citation URIs). Covers all aspects an agent needs to know for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining what each type pulls (financials vs drug data) and providing examples for values. The schema already gives detailed parameter descriptions, so the added value is moderate but not groundbreaking.

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

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

Description uses specific verbs like 'compare' and 'rank' and names the resource (entities) with clear scope (2–5 companies or drugs). It explicitly contrasts with sequential single-entity lookups, distinguishing it from sibling tools like entity_profile.

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

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

Provides explicit trigger examples ('compare X and Y', 'which is bigger') and instructs to prefer over sequential lookups. Implicitly tells when not to use (single entity) by stating it replaces 8–15 sequential lookups.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), description adds critical behaviors: never invents (explicit gaps[]), returns verbatim evidence with confidence, source, fetched_at, and stable citations. Also discloses parallel execution and expected duration (15-60s). 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 appropriately sized for a complex tool, front-loaded with the core value proposition. Every sentence adds substantive information (parallelism, citation format, prerequisites, time estimate). No fluff or repetition.

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

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

For a tool with no output schema, the description fully explains return format: structured findings packet with verbatim evidence, gaps, confidence, sources, and citations. Also covers prerequisites, depth options, time expectation, and provides sibling comparison. Complete given tool 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?

Despite 100% schema coverage, description enriches both parameters: for 'depth', explains the number of facets per level and paid requirement; for 'question', clarifies that broad/multi-part is intended. This adds practical meaning beyond enum values and type.

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

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

The description states exactly what the tool does: 'Grounded multi-source research in ONE call' with detailed breakdown of decomposition, parallel routing, and extraction. It clearly distinguishes from sibling 'ask_pipeworx' by specifying use for broad/multi-part questions vs single lookups.

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

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

Explicitly provides when to use (broad/multi-part questions) and when not to (use ask_pipeworx for single lookups). Also mentions prerequisites (Pipeworx account, sign in via GitHub) and that 'thorough' depth requires a paid plan, giving clear usage boundaries.

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 useful context by stating that each result includes full input schemas with curated examples and is 'ready to call directly, no second schema lookup needed.' This informs agent behavior beyond what annotations capture.

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 short, front-loaded, and every sentence adds value. It starts with the core purpose, then lists example use cases, explains what is returned, and provides usage advice. No superfluous 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?

Despite lacking an output schema, the description fully explains what the tool returns: names, descriptions, full input schemas with curated examples, and that results are directly callable. This is complete for a discovery tool with no output schema needed.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds examples and notes about aliases but does not add significant semantic detail beyond what the schema provides. 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 uses a specific verb-resource combination: 'Find tools by describing the data or task.' It lists a wide range of domains (SEC filings, FDA drugs, etc.) and differentiates the tool from siblings by stating it returns top-N tools with full schemas, making it clear this is a tool discovery utility.

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 is provided: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This directly tells the agent when to use this tool versus alternatives like search or other specific 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 a safe, non-destructive, idempotent read operation. The description adds valuable context: it fans out across multiple sources, mentions soft-failures (patents API sunset), and lists specific return fields. 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 but slightly verbose. However, it front-loads the purpose with examples and every sentence adds value. Could be trimmed slightly without losing clarity, but overall effective.

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

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

With no output schema, the description thoroughly explains the return information, including specific data points like recent filings with URIs, fundamentals, patents, news, and LEI. It covers what the user can expect, making it complete for an information 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%, but the description adds meaning beyond the schema by explaining that 'type' is limited to 'company' and 'value' accepts ticker or zero-padded CIK, with rationale for excluding names. This helps correct tool invocation.

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

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

The description uses specific verbs like 'profile' and lists common queries, clearly stating it provides a full cross-source profile of US public companies. It distinguishes itself from sibling tools like resolve_entity by specifying that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and warns that names are not supported, directing users to use resolve_entity first. This provides clear when-to-use and alternatives.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, covering safety and idempotency. The description adds context on when to use but does not detail edge cases like missing key behavior. However, annotations carry the transparency burden here.

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 with no wasted words. The verb and resource are front-loaded. Every sentence earns its place: purpose, usage, and pairing with siblings.

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

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

Given the tool's simplicity (one param, no output schema), the description covers purpose, usage, and sibling relationships adequately. Minor omissions like error handling or return behavior are acceptable at this 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?

Schema coverage is 100% with the schema describing 'key' as 'Memory key to delete'. The description adds only the phrase 'previously stored' which is implied. Baseline 3 is appropriate as description adds minimal semantic 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 deletes a previously stored memory by key, using a specific verb and resource. It distinguishes from siblings by mentioning 'remember' and 'recall' as paired operations, implicitly differentiating deletion from storage and retrieval.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also provides alternatives by pairing with 'remember' and 'recall'.

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable context by detailing the internal behavior (fetches the page, extracts fields) and the output format, which goes beyond what annotations provide. 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 concise (3-4 sentences) and front-loaded with the core action. Every sentence adds value: first sentence states purpose, second describes process, third gives output details, fourth lists use cases. No wasted words.

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

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

Given the low complexity (2 parameters, no output schema, no nested objects), the description is complete. It explains input, process, output format, and use cases. The annotations cover safety, so the description doesn't need to reiterate those. Sufficient for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100% (both parameters are documented in the schema). The description reiterates the URL parameter's purpose but adds no new semantic detail beyond 'Full URL'. The max_links parameter is mentioned in schema with defaults, but description doesn't elaborate further. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description uses a specific verb ('Generate') and clearly states the resource ('production-ready llms.txt file for any URL'). It explains the action (fetches page, extracts info) and the output format. It distinguishes itself from sibling tools by focusing solely on llms.txt generation, while siblings like scan_competitor_ai_presence are broader.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor AI visibility. It provides clear context for when to use the tool, though it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that only active subscriptions are listed by default and enumerates the return fields, providing useful behavioral context beyond annotations.

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

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

Two sentences efficiently cover the action, output, and usage guidance. No unnecessary words or repetition.

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

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

Given the tool's simplicity (one optional parameter, no output schema but fields listed in description), the description is complete. It explains what the tool does, what it returns, and when to use it.

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

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

Schema coverage is 100% and the schema already describes the include_inactive parameter. The description adds context about default behavior (active only) but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields. It distinguishes from sibling tools like subscribe and unsubscribe by indicating it's for reviewing existing subscriptions.

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

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

The description provides explicit use cases: review before adding more subscriptions or find an id to cancel. It implicitly contrasts with subscribe and unsubscribe but does not name alternatives or explicitly state when not to use.

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

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

Annotations provide no behavioral hints (all false), but description adds that it is rate-limited (5 per identifier per day) and free (doesn't count against quota). This extra context helps agent understand constraints beyond what annotations convey.

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 compact and front-loaded: purpose first, then usage scenarios, then constraints. Every sentence adds essential 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?

For a simple feedback tool, the description covers all relevant aspects: purpose, when to use, parameter guidance, constraints (rate limit, quota), and expected content. No output schema needed; return behavior is implicitly feedback submission. Complete for agent decision-making.

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

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

Schema already covers parameters with descriptions (100% coverage). Description adds value by clarifying message format (be specific, 1-2 sentences, 2000 chars max) and reinforcing type definitions in context of use cases, which aids correct parameter usage.

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

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

The description clearly states the tool sends feedback about Pipeworx tools, specifying categories (bug, feature, data_gap, praise). It distinguishes from sibling tools by focusing on reporting issues or missing functionality, not querying or manipulating 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?

Provides explicit when-to-use scenarios: bug for wrong data, feature/data_gap for missing tools, praise for positive experiences. Also gives 'don't' instruction (avoid pasting end-user prompt) and notes team reads daily, helping agent decide appropriateness.

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

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

Annotations already indicate safe, non-destructive traits. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, and caching window (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 concise and well-structured: first sentence states the core function, second explains use cases with bullets, and third adds technical context. 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?

With one optional parameter, no output schema, and comprehensive annotations, the description covers input, output, caching, and privacy. No gaps remain.

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

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

The single parameter 'window' is documented in the schema with enum values. The description adds meaning about the effect of short vs long windows (hot vs steady-state), enhancing 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 returns top tools, top packs, and call volume over a window. It uses specific verbs and resource, distinguishing it from sibling tools like ask_pipeworx or discover_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?

Three explicit use cases are listed, providing clear context on when to use this tool. It could have mentioned alternatives for broader discovery, but the sibling list and context make it clear enough.

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

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

The description fully discloses behavioral traits beyond annotations: the analysis logic (monotonicity, partition check), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and the fill check with realizable edge. It explicitly warns that if realizable_edge_pp <= 0, the trade should not be executed. This aligns with the readOnlyHint and openWorldHint annotations.

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

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

The description is lengthy but well-structured with sections for event mode, topic mode, semantic anchor, partition filter, response, and fill check. Every sentence adds essential information, though some redundancy exists (e.g., repeated mention of 'REQUIRES'). It is front-loaded with the requirement, aiding quick consumption.

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

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

Despite no output schema, the description thoroughly explains the response format (opportunities[], partition_check fields, fill check details). It covers edge cases like missing args, low Jaccard similarity, and placeholder fractions. For a complex tool, this provides sufficient context for proper invocation and interpretation.

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 significant value by explaining the semantics of each parameter: `event` takes a slug or URL for single-event mode, `topic` takes a seed question for cross-event mode. It includes examples and constraints like REQUIRES one. This goes beyond the schema descriptions.

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

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

The description explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event mode and topic mode, providing specific examples like 'fed-decision-may-2026' and 'Fed rate decision'. This clearly distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description clearly states that one of `event` or `topic` is required, and explains what happens if called with no args. It provides explicit guidance on when to use each mode: event for a specific market, topic for cross-event scanning. It also mentions `polymarket_fill_risk` for custom sizing, offering an 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 indicate safe read-only operation. The description adds extensive behavioral details: caching (1h), response structure (by_segment, fed_candidates, diagnostics), model families, and why certain segments may be empty. This goes well beyond annotations.

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

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

Although long, every sentence adds unique value. The description is front-loaded with purpose, then breaks down model families and parameter details. It is structured logically 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 no output schema, the description thoroughly explains the response structure, including segments, diagnostics, and why empty segments occur. It also covers caching and parameter interdependencies.

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%, setting a baseline of 3. The description greatly enhances each parameter with practical context, e.g., explaining slippage assumptions, tradeable-edge filters, and how knobs affect results. This adds significant value.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb 'scan', the resource 'Polymarket markets', and distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on Pipeworx disagreement.

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

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

The description explicitly frames the tool for 'what should I bet on today' and notes that it avoids paging through hundreds of markets. It explains tradeable-edge knobs for filtering. However, it does not directly name sibling alternatives for when not to use this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds critical context: daily snapshots, 60-day TTL, decay from daily closes (not intraday), and response structure. 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 dense but well-structured, front-loading the purpose and then detailing response fields. It is somewhat long but each sentence adds value, justifying its length.

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

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

Given no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and constraints (TTL, source). It provides enough context for an agent to understand what the tool returns and its limitations.

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

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

Schema coverage is 100%. Description reiterates defaults and examples for 'days' and 'window', adding minor context (e.g., 'max 30' for days). It does not add significant meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It distinguishes itself from siblings like polymarket_edges by focusing on historical trends rather than current edges. The verb 'track' and resource 'edge persistence' are specific.

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

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

The description implies usage by stating it answers 'how long has this edge existed and is it shrinking?', and differentiates fresh vs old edges. However, it does not explicitly compare to sibling tools or provide when-not-to-use scenarios, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the check against live CLOB order-book depth, return fields (top_of_book, vwap_fill_price, etc.), and warns about partial basket fills causing directional risk. This goes beyond annotations without contradicting them.

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

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

The description is dense but well-structured with mode headers and a clear flow. It front-loads the purpose and lists return fields. While comprehensive, it could be slightly more concise, but every sentence serves a purpose. Still, a minor reduction would improve readability.

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

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

For a complex tool with two modes and no output schema, the description thoroughly explains inputs, outputs, and edge cases (e.g., thin legs, partial fills). It provides all necessary information for an AI agent to select and invoke the tool correctly, addressing both single-market and basket scenarios.

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

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

Schema description coverage is 100%, but the description adds significant meaning: explains how size_usd is interpreted differently in single-market vs basket modes, clarifies default side logic for baskets ('auto — sell if partition sum > 1, buy if < 1'), and mentions clamping constraints. This adds value beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' distinguishing between single-market and basket modes. This differentiates it from siblings like polymarket_arbitrage and polymarket_edges, which are about identifying arbitrage and edges, respectively.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books not capturable, partial fills create directional risk). Also specifies when to use each mode and default parameter values.

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

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

The annotations (readOnlyHint, idempotentHint, etc.) already indicate a safe read operation. The description goes far beyond by detailing response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), and edge cases like non-equivalent bet shapes or temporal gaps. It front-loads that most pre-mapped topics are not tradeable, managing expectations. 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 clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses bold formatting for emphasis. Every sentence provides distinct value, but the length could be slightly reduced without losing information. It is front-loaded with the core concept.

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

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

Despite no output schema, the description thoroughly explains the response structure and all relevant safety fields. It covers temporal alignment, skipped leg types, and compatibility warnings. Given the tool's complexity, the description is remarkably complete, leaving little ambiguity for an AI agent.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds significant value by explaining the topic enumeration (10 pre-mapped strings), the override behavior of explicit parameters, and giving examples. This extra context helps the agent understand parameter relationships 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: computing cross-venue spreads between Kalshi and Polymarket. It specifies two distinct modes (topic shortcuts and explicit event pairing) and explains the core concept of comparing prices across venues. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, which could cause confusion for an AI agent deciding which tool to use.

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 guidance on when to use each mode (topic for pre-mapped macros, explicit for custom pairings) and warns that most pre-mapped topics currently return a compatibility_warning, indicating they may not be tradeable. It also explains safety fields and conditions for meaningful spreads. However, it does not compare directly to alternatives in the sibling list, leaving the agent to infer when to choose this tool over others.

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 openWorldHint as true, and destructiveHint as false. The description adds no behavioral context beyond what the annotations provide, such as authentication needs, result format, or error handling.

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

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

The description is extremely concise with a single sentence, front-loading the core purpose. However, it may be too brief to be fully useful, but it earns its place without redundancy.

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

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

Given the presence of an output schema, the description need not detail return values. However, it fails to explain the optional 'instance' parameter or any side effects, leaving gaps for an AI agent to understand the tool fully.

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 0%, so the description must compensate for parameter documentation. It only mentions 'by id' for the id parameter but ignores the 'instance' parameter entirely. The name 'instance' is not explained.

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 'Single post by id.' clearly states the tool retrieves a single post by its identifier. It uses a specific verb and resource, distinguishing itself from siblings like 'posts' (plural) and 'comments'.

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?

No guidance is provided on when to use this tool versus alternatives such as 'posts' or 'search'. There are no conditions, prerequisites, or exclusions mentioned.

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

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

Description adds return value details (title, body, author, upvotes, comment count) and platform context beyond annotations. Annotations already declare readOnly and idempotent, so description complements 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?

Concise and front-loaded; 30 words cover purpose, sorting, output, and context with no extraneous information.

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

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

Given output schema exists, description adequately covers what the tool does and returns. Platform context is helpful. Slightly lacks detail on pagination (page, limit) but overall sufficient for a simple listing 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 50% with 3 undescribed parameters (page, limit, instance). Description mentions sort options and community/feed but adds little beyond schema for described parameters. Does not fully compensate for missing 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?

Clearly states the action (list) and resource (Lemmy posts), distinguishes from siblings like 'post' and 'comments', and provides platform context (federated Reddit-alternative).

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?

Says 'Use for federated open-source discussion forum content', implying when to use. Does not explicitly state when not to use or alternatives, but context from sibling tool names provides enough guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds scoping info (by identifier) which is valuable beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with action, no unnecessary words. Every sentence adds value.

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

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

Description covers purpose, usage, scoping, and pairing. Lacks specifics on return format (e.g., JSON structure) but output schema is absent, so a minor gap.

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

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

Schema coverage is 100%, baseline 3. Description adds semantic clarity: omitting key lists all keys, which goes beyond just 'retrieve a value'.

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

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

The description clearly states the tool's verb (retrieve/list), resource (saved keys/values), and explicitly distinguishes from siblings 'remember' and 'forget'.

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

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

Provides explicit when-to-use examples (look up context like ticker, address, notes) and implies alternatives (save with remember, delete with forget).

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: fields returned, effect of mark_read (flags events read), and polling suitability. No contradiction with annotations.

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

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

The description is concise yet information-dense, front-loading the core purpose. Every sentence adds value—fields, filtering, mark_read, polling, alternative endpoint.

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 output schema, the description explains return fields (source, citation_uri, raw payload) and covers all parameters. It provides guidance on polling and alternative access, 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%, but the description adds meaning: provides example for type ('sec_8k'), clarifies ISO timestamp for since, specifies limit range (1-200) and default (50), and explains mark_read behavior.

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 pulls fired events from the subscription feed, returns recent alerts with specific fields, and supports filtering. It distinguishes itself from siblings like 'list_subscriptions' by focusing on recent events and providing polling context.

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

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

The description explains when to use the tool (to get recent alerts), how to filter by type and since, and how to use mark_read. It also mentions the same feed is available via an alternative endpoint for scripts, but lacks explicit exclusions or comparisons to 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds details about fan-out to multiple sources, GDELT preferred with GNews fallback on rate limit/5xx, USPTO soft-fail due to API sunset, and return structure with grouped changes and citation URIs. No contradictions.

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

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

The description is a single dense paragraph that front-loads the main purpose and examples. Every sentence contributes value, though the length could be slightly trimmed. Overall efficient and 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 (multiple sources, fallback, soft-fail) and absence of output schema, the description is very complete. It explains the fan-out logic, fallback behavior, soft-fail condition, and return format (grouped changes, total count, citation URIs). 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%, so baseline 3. The description adds meaning beyond schema: examples for 'since' value, suggestion to use '30d' for typical monitoring, clarification that 'type' is only 'company' currently, and explanation that 'value' accepts ticker or CIK.

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 a change feed for a company in the last N days, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from the sibling tool 'entity_profile' by noting when to use each.

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

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

The description includes example queries ('What's new with X', 'latest on Y'), specifies window options (ISO date or relative shorthand), explains fallback behavior (GDELT→GNews) and soft-fail for USPTO, and explicitly directs to use 'entity_profile' for static profile regardless of window.

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 idempotent (true), but description adds key details: key-value scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. 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?

Four efficient sentences: purpose, usage guidelines, technical details, companion tool reference. No fluff.

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

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

Given two simple parameters and no output schema, the description fully covers purpose, usage, examples, retention, and companion tools. 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 descriptions alone cover the parameters fully (key and value with examples). Description adds context on how to use keys (e.g., subject_property) but doesn't significantly extend 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 'Save data the agent will need to reuse later' with specific verb and resource. Distinguishes from siblings by mentioning companion tools recall and forget.

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

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

Explicitly explains when to use (discovering something worth carrying forward) and provides examples. Directs to pair with recall and forget for retrieval and deletion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: it explains that the tool 'cascades through several lookup endpoints internally' and that it replaces multiple manual lookups. It also describes the output format including citation URIs, which is not covered by annotations.

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

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

The description is moderately-sized but well-structured: example queries in quotes, then purpose statement, then usage guidance, then details per type. Every sentence adds value. It is front-loaded with the core purpose and example. Could be slightly more concise, but overall efficient.

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

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

For a tool with no output schema, the description adequately covers return values per type, including citation URIs. It explains the cascading nature and that it replaces manual lookups. It does not cover error cases or edge cases, but for a relatively straightforward lookup tool, it is comprehensive enough.

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%, providing baseline 3. The description adds significant meaning: for the 'type' parameter, it details return fields (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug). For 'value', it clarifies accepted input formats (ticker, CIK, or name for company; brand or generic name for drug) and notes auto-disambiguation. This exceeds the schema descriptions.

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

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

The description starts with concrete example queries ('What's the ticker for...'), then explicitly states the purpose: 'resolve a user-spoken NAME to the canonical/official identifier'. It also distinguishes the tool from siblings by noting that other tools require these IDs as input and advising to 'Use FIRST whenever you have a name but need an ID'. The supported types and their returns are clearly detailed.

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

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

The description gives clear usage guidance: 'Use FIRST whenever you have a name but need an ID.' It implies not to use when you already have the ID. It explains what each entity type returns and mentions that it replaces 2-3 manual lookups. However, it does not explicitly state 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, 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 three sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words.

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

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

The description explains the process (probing, ranking) and output format (ranked list with score, confidence, signal density). Without an output schema, this is sufficient. Could mention error handling or limits on entity count, but acceptable.

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

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

Schema coverage is 100% and each parameter has a description. The description adds additional meaning: first entity is treated as 'subject' for narrative, and context disambiguates common names. This goes beyond schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking by score. It distinguishes from siblings like ai_visibility_check and compare_entities by focusing on competitive audits.

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 a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use or mention alternatives, leaving some ambiguity.

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

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

Discloses multiple behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, sources_failed will list timeouts. Annotations already declare readOnlyHint and idempotentHint, and description adds context about timeout handling and fallback behavior.

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

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

Description is front-loaded with the core purpose and details, no wasted words. Each sentence adds value: composite check, sources, usage guidance, ecosystem limitation, partial failure handling. Efficient and 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 (composite call, multiple sources, partial failures, version defaults, ecosystem limitation), the description covers all essential aspects. Despite no output schema, it details the return structure (summary block, per-advisory, links, alternative versions). Complete for effective use.

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

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

Schema coverage is 100% with clear descriptions for 'package' (npm name with scoped packages) and 'version' (specific or defaults to latest). Description reinforces that version is optional and ecosystem is NPM only, but adds minimal new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a composite check for evaluating whether to add an npm package, covering license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. It specifies the verb 'scan' and resource 'dependency', and distinguishes from sibling tools like 'scan_competitor_ai_presence'.

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

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

Explicitly states when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear guidance on alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds no behavioral context beyond 'search', which is consistent but lacking details like rate limits or result structure.

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

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

The description is extremely concise (two words) but under-specifies the tool's functionality. It sacrifices completeness for brevity, lacking necessary 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?

With 7 parameters, low schema coverage, and an output schema not described, the description is insufficient. It fails to explain return values or the behavior of optional parameters.

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

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

Schema description coverage is low (29%) with only type_ and listing_type documented. The description 'Full search.' does not clarify the meaning or usage of any parameters.

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

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

Description 'Full search.' is vague. It indicates a search function but doesn't specify what entities or resources are searched. Sibling tools like 'search_within' and 'site' suggest there are more specialized search tools, but this description doesn't differentiate.

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?

No guidance on when to use this tool versus alternatives like 'search_within' or 'site'. No mention of prerequisites or 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 well beyond annotations by disclosing the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character limit (200K with truncation flag), and that returned passages include offsets and similarity scores. No contradiction with annotations.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value. It covers usage, technical details, and edge behavior without superfluous content.

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

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

Despite no output schema, the description explains the return format (passages with character offsets and similarity scores), behavior for large inputs (truncation with flag), and pairing with sibling. This is fully complete for a search tool with three parameters.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by specifying the query format with examples and clarifying the limit range (1-20, default 5), which is not in the schema. However, it does not add substantial new meaning beyond schema.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record' and distinguishes it from siblings by mentioning it pairs with ask_pipeworx_grounded. The verb and resource are specific and unambiguous.

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

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

The description explicitly states when to use ('when the record is too big to cram into the prompt') and explains the benefit (saves context, returns only relevant passages). It also mentions a complementary sibling tool (ask_pipeworx_grounded), but does not provide 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), destructiveHint (false), openWorldHint (true), and idempotentHint (true). The description adds no additional behavioral context, such as what metadata is returned or any side effects, but 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 extremely short (two words), which is concise but under-specified. It sacrifices completeness for brevity, leaving important details unmentioned.

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

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

The description lacks details about return values (despite output schema existing), parameter meaning, and usage context. It is insufficient for an agent to correctly invoke this tool given the available metadata and sibling tools.

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

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

Schema description coverage is 0%. The description 'Instance metadata.' does not explain the 'instance' parameter's purpose, format, or constraints. With no parameter documentation in either schema or description, the agent has no guidance on how to use the parameter.

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

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

The description 'Instance metadata.' gives a general idea but lacks a verb (e.g., 'get' or 'retrieve') and does not distinguish from siblings like 'community' or 'post'. The purpose is vaguely clear but not specific.

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

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

No usage guidance provided. The description does not specify when to use this tool over alternatives such as 'community' or 'post', nor does it mention any prerequisites or context.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds behavioral context like requiring verified phone for SMS, 10/day cap, and auto-disable of webhooks after 10 failures. However, it does not clarify idempotency, which contradicts the idempotentHint annotation.

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

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

The description is detailed and front-loaded with the main action, but it is somewhat lengthy. Every sentence adds value, and examples are well-structured, though bullet points could improve readability.

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

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

Given no output schema, the description mentions the return of a subscription ID. It covers types, parameters, delivery, account requirements, and constraints. Missing details on idempotency and error scenarios but overall comprehensive.

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

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

Schema coverage is 100%, and the description adds significant value beyond the schema by providing concrete examples for each subscription type, detailed delivery channel options, and constraints (e.g., phone verification, SMS cap).

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 subscription to a live-data event stream and returns a new subscription ID. It provides specific examples of supported types, distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description explains when to use the tool (creating proactive subscriptions) and lists prerequisites (Pipeworx OAuth account). However, it does not explicitly state alternatives or when not to use it, though sibling names imply distinct purposes.

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 that it returns live catalog examples with exact tool+argument shape, and mentions it is the onboarding entry point. No contradiction with annotations, and adds behavioral context.

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

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

Description is front-loaded with common queries, then explains purpose, output, and parameter usage. While thorough and well-structured, it is slightly verbose but every sentence contributes value.

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

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

Given the tool's role as an onboarding entry point, the description fully covers what it does, how to use it, what output to expect (category-bucketed examples with tool+argument shape), and when to invoke it. No output schema exists, but the description compensates adequately.

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

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

Schema coverage is 100% for one optional parameter. Description enhances schema by listing valid focus areas (finance, pharma, etc.) and clarifying that omission yields cross-category spread. This adds practical guidance beyond the schema's generic 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?

Description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions. It specifies the verb (suggest_questions), resource (Pipeworx capabilities), and distinguishes it from siblings by noting it should be used first when learning about Pipeworx.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also describes optional topic parameter to focus. No explicit when-not, but the context implies alternatives like direct tool calls.

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

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

The description goes beyond annotations by disclosing ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('The row is deactivated (not deleted) so its historical events stay available'). These details add significant value, as annotations only indicate idempotence and non-destructiveness. 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 highly concise: two sentences covering purpose, ownership, and behavior. Every word is meaningful, with no redundancy or irrelevant details. It is front-loaded with the core action.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description is complete. It explains the effect (deactivation), ownership constraint, and links to related tool 'recent_alerts'. An AI agent has enough context to invoke it correctly.

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

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

The input schema already provides full coverage (100%) for the sole parameter 'id', describing it as a UUID from subscribe. The description does not add new semantic information about the parameter; it merely states 'by id', which is redundant. Thus baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and the verb (cancel/unsubscribe). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by its focus on cancellation. The additional detail about deactivation vs deletion further clarifies the tool's behavior.

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

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

The description implies usage for canceling a subscription, and the context of sibling tools (subscribe, list_subscriptions) makes the use case clear. However, it does not explicitly state when to use this tool over alternatives or provide exclusions. Still, it provides sufficient context for an AI agent to infer appropriate use.

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

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

Discloses output format (verdict, extracted structure, actual value with citation, percent delta) and efficiency benefits. Annotations (readOnly, openWorld, idempotent, non-destructive) are consistent, with description adding rich behavioral context beyond annotations.

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

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

Single paragraph with multiple sentences, front-loaded with trigger phrases. Information-dense but clear. Minor lack of structural formatting (e.g., bullet points) but still efficient.

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

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

Despite no output schema, description fully explains return values and domain constraints. Covers usage, limitations, and expected output, making it self-contained for agent decision-making.

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

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

Only one parameter 'claim' with 100% schema coverage. Schema already provides example, but description adds natural-language triggers and reiterates domain scope, enhancing usability.

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 validates natural-language claims against authoritative sources, with specific examples and domain scope (company-financial). It distinguishes from siblings by specifying the use case and replacing multiple sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check factual correctness.' It also clarifies limitations: 'v1 supports company-financial claims for public US companies,' implying non-use for other domains.

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