dnd5e

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

Annotations already cover safety (readOnly, idempotent). Description adds behavioral details: default vs. optional Anthropic model, return format with per-model fields, and direct payment for Anthropic.

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

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

Three sentences with no wasted words, front-loaded with purpose and key details, perfectly concise for the tool's complexity.

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

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

Given no output schema, description explains return format (per-model plus combined view) and optional API key behavior. Adequate for a 4-parameter tool with high schema coverage.

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

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

Schema covers all parameters with descriptions; description adds context like default model, free tier, and purpose of optional context parameter for disambiguation.

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

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

The description clearly states it probes LLMs for entity knowledge and scores visibility (0-100) per model, distinguishing it from sibling tools like ask_pipeworx by focusing on AI-marketing 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?

Explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Lacks explicit when-not-to-use or alternatives, but context with siblings implies differentiation.

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 convey readOnly, openWorld, and idempotent hints. The description adds behavioral details: it routes to 3,745 tools, fills arguments, and returns stable citation URIs. It does not cover potential failure modes or rate limits, but given annotation coverage, the added context is sufficient.

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

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

The description is somewhat long but front-loaded with key guidance. Every sentence serves a purpose: stating preference, listing use cases, providing examples. It could be slightly trimmed without loss, but overall it is well-structured.

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

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

Given the complexity (no output schema, many sources), the description adequately covers usage but lacks detail on return format beyond 'structured answer with citation URIs.' It does not address error handling or limitations, leaving some gaps for a tool of this scope.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value beyond the schema by providing multiple real-world examples and clarifying the scope of acceptable questions, which helps the agent form effective queries.

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

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

The description clearly states the tool's function: routes factual questions to a vast network of verified sources and returns structured answers with citations. It explicitly distinguishes itself from web search, aligning with the requirement for a specific verb+resource and differentiation from siblings.

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

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

The description provides explicit guidance on when to use this tool over alternatives, including 'PREFER OVER WEB SEARCH' and specific examples of query types (e.g., SEC filings, FDA data). It also lists example user queries, giving clear context for invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: it details the response structure (answer, evidence, confidence, source, etc.), lists possible refusal reasons, and mentions the extra cost of an LLM call. However, it does not specify rate limits or authentication needs, which are not required given annotations cover safety.

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 and front-loaded with the key concept. Each sentence serves a purpose, though it is somewhat long. It could be slightly more concise, but the information density justifies the 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 (routing across 3,745 tools and 884 sources), the description is remarkably complete. It explains the behavior, refusal reasons, and response format. No output schema exists, but the description adequately covers return values. The context signals indicate high schema coverage and no nested objects, so the description fills all 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?

The input schema has 100% coverage, so baseline is 3. The description does not add extra meaning beyond what the schema already provides for parameters. It simply mentions 'question' but does not elaborate on the aliases or provide additional constraints.

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

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

The description clearly states it is a hallucination-resistant answer mode for high-stakes reads, using the same routing as ask_pipeworx but extracting answers strictly from tool results. It explicitly distinguishes itself from the sibling ask_pipeworx by emphasizing evidence-based answers and refusal on insufficient data.

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

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

The description explicitly states when to use this tool (for answers that will be quoted, cited, or acted on, where facts must not be invented) and when to prefer the sibling ask_pipeworx (casual lookups). It also notes the cost trade-off (extra LLM call).

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

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

Annotations indicate readOnlyHint, idempotentHint, openWorldHint. The description extensively details behaviors: resolution, fan-out, evidence packet, response shapes, safety (low-confidence short-circuits, closed markets), parent event extraction, news fallback, spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

The description is very detailed but verbose. It uses section markers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) to structure, but the length may overwhelm agents. Could be more concise while retaining key information.

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

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

Given the tool's complexity (classifiers, fan-outs, multiple response fields) and absence of output schema, the description is remarkably complete. It covers resolution confidence, parent events, news fallback, safety, spread, cancellation rules, and more.

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%. The description adds meaning beyond schema: examples of market_input formats, explains depth options, and details include_raw behavior. It provides context for all three parameters.

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

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

The description starts by clearly stating the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and differentiates from siblings like polymarket_edges by focusing on a single bet research with data fan-out.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides context for when to use, though it does not explicitly list alternatives or when not to use it.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: results are sorted by primary metric for easy reading, returns paired data with pipeworx:// citation URIs, handles off-calendar fiscal years correctly, and replaces 8–15 sequential lookups. 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 a single dense paragraph, but every sentence serves a purpose: query examples, tool purpose, preference guidance, type-specific behavior, and output format. It is front-loaded with the most critical information. While it could be slightly more structured with bullet points, it remains concise and easily scannable.

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 (two entity types, multiple data sources, sorting, citations) and the lack of an output schema, the description covers the key aspects: when to use, input format, data sources, and return structure ('paired data + citation URIs'). It could mention potential error cases or rate limits, but with annotations providing idempotency and read-only guarantees, it is sufficiently complete 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%, so baseline is 3. The description adds value by specifying that 'values' for companies are tickers/CIKs (e.g., ['AAPL','MSFT']) and for drugs are names (e.g., ['ozempic','mounjaro']), and clarifies the count range (2–5). These details go beyond the schema's enum and generic descriptions, providing concrete examples that aid 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 opens with explicit query patterns ('Compare X and Y', 'X vs Y', etc.) and clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes itself from sequential single-pack lookups, which are handled by sibling tools like entity_profile. The verb 'compare' and resource 'entities' 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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear directive for when to use this tool. It also explains the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and gives examples of appropriate inputs, helping the agent decide between this and siblings like entity_profile.

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, openWorldHint, non-destructive. Description adds how it works: decomposition, parallel routing to 3,745 tools, verbatim evidence, gaps[], no invention, 15-60s. No contradiction.

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

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

The description is well-structured and front-loaded with purpose, then mechanics, usage, prerequisites, and expectations. It is concise for the complexity it covers, though slightly verbose in listing features.

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

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

Given no output schema, the description adequately describes the return (structured findings packet with evidence, confidence, gaps). Includes time expectation. Could specify more about output shape, but sufficient for an agent.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds minor context (quick=3, standard=5, thorough=8) which is already in the enum description, and mentions paid plan for thorough. Baseline 3 due to high schema coverage.

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

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

The description clearly states it does multi-source research by decomposing questions and routing to thousands of tools, and distinguishes itself from siblings like ask_pipeworx (single lookup). The verb 'research' and resource 'multi-source' 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?

Explicitly says when to use (broad/multi-part questions) and when not (single lookups -> ask_pipeworx). Also mentions prerequisites: Pipeworx account, sign-in via GitHub, and paid plan for thorough depth.

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 response format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This adds value beyond the annotations.

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

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

The description is 4 sentences, front-loads the purpose, and includes a dense list of domains. Every sentence adds value, 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?

Despite no output schema, the description fully explains what the tool returns: tool names, descriptions, and full input schemas with examples. This tells the agent exactly what to expect and that the results are ready to call, which is complete for the tool's purpose.

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 documents all parameters. The description does not add new parameter details but provides example values and explains that multiple aliases (q, task, search, description) are accepted. This is adequate but not exceptional.

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 'Find tools by describing the data or task.' It specifies the action (find/discover) and the resource (tools), and includes a long list of domains. It also distinguishes from sibling tools by advising to 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

Explicitly states 'Use when you need to browse, search, look up, or discover what tools exist for: [list]' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use and when-not-to-use guidance.

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

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

Description adds details beyond annotations: fans out across multiple sources, mentions patents API sunset (May 2025) and soft-fail behavior, describes fallback (GDELT→GNews). No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint.

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

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

Description is dense (170+ words) but front-loaded with example queries. Every sentence adds value, though could be formatted into bullet points for easier parsing. Still conveys all necessary information efficiently.

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, description thoroughly enumerates return fields (CIK, filings, fundamentals, patents, news, LEI) and covers edge cases (patents sunset, name restriction). Provides complete context for a complex tool.

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

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

Schema coverage is 100%, baseline 3. Description adds value by clarifying that type is limited to 'company' (with future plans), and value must be ticker or zero-padded CIK (names not supported). Provides actionable guidance 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 uses specific verbs ('Tell me about', 'research', 'brief me') and clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes from siblings by explicitly preferring over chaining single-pack lookups.

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

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

The description provides explicit when-to-use ('when user asks for holistic view'), when-not-to-use ('if only a name, use resolve_entity first'), and includes example inputs (ticker 'AAPL' or CIK '0000320193'). Clearly guides agent 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 already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing stale or sensitive data, but doesn't elaborate on behavior beyond deletion (e.g., missing key handling). This is sufficient for a simple deletion tool.

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

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

Three concise sentences: first states the action, second gives usage context, third relates to siblings. No wasted words, and the core purpose is front-loaded.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, usage, and sibling relationships. It could mention behavior on non-existent keys, but annotations hint at idempotency. Adequate for the complexity level.

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

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

Schema coverage is 100% with the parameter description 'Memory key to delete'. The description reiterates 'by key' but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate as the description provides no extra 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 'Delete a previously stored memory by key', specifying the verb (delete) and resource (memory by key). It also mentions pairing with remember and recall, which helps distinguish this deletion tool from its storage and retrieval siblings.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This provides clear context and indirectly implies when not to use (e.g., for storing or retrieving memories).

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

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

The description explains the process (fetches, extracts, emits) and output format (single text blob), adding context beyond annotations that already declare idempotent/read-only. 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 two sentences with a clear, front-loaded action statement. The 'Useful for:' section is structured and concise, with no wasted words. Every sentence adds value.

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

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

Given the tool simplicity (2 params, no output schema) and rich annotations, the description covers the essential behavior, output format, and purpose. Missing error handling or rate limits, but these are minor for this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats basic parameter purpose ('url', 'max_links') but does not add new details beyond the schema. No extra semantic enrichment.

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 ('Generate'), resource ('llms.txt file'), and scope ('for any URL'). It differentiates from sibling tools by specifying a unique output format and use case, with no ambiguity.

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

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

The description lists explicit use cases (indexing a client's site, drafting for your project, auditing competitors), providing clear context. It does not explicitly mention when not to use, but no sibling tool competes directly, so guidelines are adequate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about the returned data (feature progression, proficiency gains, subclass options) beyond the annotations. No contradictions.

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

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

Two sentences: first states purpose and output, second specifies input format. No unnecessary words, front-loaded with key information.

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

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

For a simple read tool with one parameter and an output schema, the description is adequate. It covers the main input and output categories. Missing explicit mention of D&D edition, but likely inferred.

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 'index' parameter. The description adds examples and notes that the index is lowercase, providing marginal additional 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 uses specific verbs ('Get') and lists exact resources ('features, hit dice, proficiencies, and advancement tables'). It clearly distinguishes from sibling tools like 'get_monster' or 'get_spell' by focusing on class-specific data.

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

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

The description implies usage when needing class details from D&D but does not explicitly state when to use this tool vs. alternatives. No when-not or comparison guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing safe read behavior. The description adds value by detailing the specific stats and data returned (AC, HP, abilities, etc.), which is beyond what annotations provide.

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

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

The description is two efficient sentences with no fluff. The first sentence front-loads the purpose, and the second gives examples and return details. Every sentence earns its place.

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

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

Given the presence of an output schema (not shown but indicated), the description does not need to detail the return format. It already lists key return contents (AC, HP, etc.), making it complete for a simple 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?

The schema covers the single parameter index with 100% description coverage. The description reinforces the format and provides examples (e.g., 'goblin', 'dragon-red-adult'), adding meaning beyond the schema alone.

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

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

The name, title, and description clearly state it retrieves monster stats (AC, HP, abilities, etc.) using a monster index. It is distinct from sibling tools like get_class and get_spell.

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 examples of indices and states what is returned, making usage clear. It does not explicitly state when not to use or list alternatives, but the context of sibling tools implies it is for monster stats specifically.

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 and idempotentHint, so the description adds context about returned fields but does not disclose additional behavioral traits beyond those already captured by annotations.

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

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

Two sentences, with the main action and key parameter guidance front-loaded. No unnecessary information.

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

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

For a simple lookup tool with one parameter, the description covers purpose, parameter usage, and return content. Output schema handles return details, so description is complete.

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

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

Schema description coverage is 100% and includes examples; the description's parameter examples are redundant with the schema's examples, providing no substantial added meaning.

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

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

The description clearly states the tool retrieves spell details, listing specific fields (damage, range, duration, components, effects), and the parameter examples differentiate it from sibling tools like 'list_spells'.

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

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

The description provides clear usage examples for the parameter (e.g., 'fireball'), but does not explicitly mention when not to use this tool or alternatives like 'list_spells' for listing all spells.

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 the tool as read-only, non-destructive, and idempotent. The description only adds that it returns 'spell indices, names, and levels', which is minimal additional behavioral context.

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

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

Two sentences, front-loaded with the main action, and no extraneous 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?

The description covers purpose and relationship to 'get_spell', and annotations provide safety context. However, the mismatch between description (search by name/level) and schema (no parameters) creates confusion, making it incomplete despite the presence of an output schema.

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

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

The input schema has no properties, yet the description mentions searching 'by name or level'. This is misleading as there are no parameters to accept such input. With 0 parameters and 100% schema coverage, the description should clarify that no filtering is supported, but it does the opposite.

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 ('Search D&D 5e spells'), the resource ('spells'), and the output ('spell indices, names, and levels'). It also distinguishes from the sibling tool 'get_spell', which fetches full details.

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

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

The description explicitly suggests using this tool in conjunction with 'get_spell' to fetch full details, providing a clear usage workflow. While it doesn't list when-not to use, the context is sufficient for an AI agent to decide.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it lists active subscriptions and details the returned fields. No contradictions, and the description enriches context by specifying what 'active' means and the effect of include_inactive.

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

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

Two sentences: first states purpose and output, second gives usage guidance. No fluff, 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?

Despite no output schema, description lists all returned fields. Parameter is fully described in schema. Usage context provided. Annotations confirm safety. Complete for a simple list tool.

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

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

Schema covers 100% of parameters with detailed description. The tool description does not add extra meaning beyond the schema for the include_inactive parameter. 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 ('List the caller's active subscriptions') and the fields returned. It distinguishes from sibling tools like subscribe and unsubscribe by indicating its purpose for reviewing before adding or canceling.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This indirectly advises against using for addition or cancellation, pointing to siblings.

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

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

Discloses rate limiting (5 per identifier per day), that it's free, and doesn't count against quota. Annotations show destructiveHint=false and readOnlyHint=false, but the description adds context beyond those. No contradiction.

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

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

The description is concise (a few sentences) and front-loads the purpose. Every sentence adds value: purpose, usage guidelines, behavioral notes, and parameter hints.

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 high schema coverage and the absence of output schema (feedback doesn't return structured data), the description is complete. It covers all necessary aspects for the agent to 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 coverage is 100%, and the description adds detailed explanations for the type enum and message format. The context parameter's description aligns with schema, and the description clarifies 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 uses specific verbs (send, tell) and clearly identifies the resource (Pipeworx team) and the types of feedback (bug, feature, data_gap, praise). It distinguishes itself from sibling tools, none of which are for feedback.

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

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

Provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and when-not (e.g., avoid pasting end-user prompts). Also states rate limits and free usage, which guide agent choice.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the data source (CF analytics-engine), aggregation (no PII), and caching behavior (5min-1h). No contradictions.

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

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

The description is concise and well-structured, with three bulleted use cases. Every sentence adds value, and there is no redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description provides all necessary context: what is returned, data source, caching, and privacy. It is complete.

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

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

Schema coverage is 100% with a description for the window parameter that already explains the trade-off between short and long windows. The tool description does not add further parameter-level detail, 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 returns 'top tools, top packs, and total call volume' over a window, which is a specific verb+resource. It distinguishes itself from siblings like 'discover_tools' by focusing on current trending data based on call volume.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming popular tool, seeing alignment) and differentiates between window lengths. However, it does not state when not to use this tool or mention alternatives, which prevents a 5.

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 read-only, idempotent, non-destructive. Description adds extensive behavioral details: processing steps (monotonicity, partition check, similarity filter, fill check), response structure, and error conditions, far exceeding 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?

Description is verbose with multiple paragraphs and algorithmic details, but well-structured with mode headers and clear sections. Could be more concise for easier parsing.

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 no output schema, the description covers inputs, processing, output fields, error handling, and even references post-processing tools, making it highly complete.

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

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

Schema descriptions are present but high-level (100% coverage). Description adds practical usage guidance like recommended mode for specific markets, URL acceptance, and seed question examples, significantly augmenting the schema.

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

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

Clear verb+resource: 'Find arbitrage opportunities on Polymarket'. Distinguishes two modes (event/topic) and is distinct from sibling tools like polymarket_edges.

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

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

Explicit requirement that one of event or topic must be provided, with recommendation for each mode. Lacks explicit when-not-to-use vs alternatives, but provides clear 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 extensively discloses behavioral traits beyond annotations, including caching (1h KV-level keyed on knobs), model family details (crypto_price, news_momentum, partition_overround, concentrated_longshot), response structure (by_segment, fed_note, diagnostics), and edge calculation specifics. No contradiction with annotations (readOnlyHint=true, idempotentHint=true).

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 and dense with technical details. While it is well-structured into sections (model families, response, knobs), it could be more concise by summarizing or trimming less critical specifics. It earns its length due to complexity but is not maximally efficient.

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

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

Given the tool's complexity (9 parameters, multiple model families, no output schema), the description is remarkably complete. It explains what each segment returns, diagnostics for empty results, caching behavior, and parameter effects. This fully compensates for the lack of an output schema.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds meaningful context beyond the schema, such as explaining why min_partition_leg_kelly is needed for partition arbs (basket trades don't compose to single-leg Kelly) and detailing the effect of slippage_pp. This adds value, resulting in above-baseline score.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly targets the use case 'what should I bet on today' and distinguishes itself from siblings like polymarket_arbitrage by focusing on edge detection with multiple model families.

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

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

The description provides clear context for when to use the tool (edge discovery) and includes knobs and filters (e.g., min_liquidity, max_spread_pp) that guide usage. However, it does not explicitly state when not to use it or mention alternative tools for different scenarios, though the sibling context implies differentiation.

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

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

The description adds significant transparency beyond annotations: it explains data limits (60-day TTL, snapshotting start), calculation method (daily closes, not intraday), and details the response structure (tracked, expired, snapshot_dates). Annotations already declare read-only and idempotent, but the description provides rich behavioral context.

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

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

The description is dense but well-organized: opens with purpose, then response breakdown, then limitations. Every sentence adds value, but it could be slightly more concise. Still efficient for the amount of information.

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

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

Given no output schema, the description compensates by detailing the return fields (tracked[], expired[], snapshot_dates[]). It covers data limitations and calculation. Lacks examples or precise format, but adequate for the tool's complexity.

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

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

Schema covers 100% of parameters with descriptions. The description reinforces defaults and constraints (max 30, default 14 for days; default '1wk' for window), adding value by clarifying clamping and snapshot family meaning. This marginally exceeds the baseline of 3.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates from related tools like 'polymarket_edges' by focusing on historical analysis.

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

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

The description implies when to use (to distinguish new vs. old edges) but does not explicitly state when not to use or compare with alternative tools. The sibling list includes similar tools, so more guidance would be beneficial.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it walks the order book ladder, returns specific metrics like slippage_pp and forced_directional_risk, and explains how baskets can strand positions. 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 long but well-structured with bold headings and clear separation of modes. Every sentence adds value, though some details could be integrated into schema. Front-loaded with requirement for market or event.

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

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

No output schema, but the description lists all return fields for both modes and explains the rationale for use. It covers the risk of partial basket fills. Lacks error handling or rate limit info, but sufficient for agent decision-making.

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

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

Schema coverage is 100%, but the description adds nuance: e.g., size_usd in basket is 'settlement notional — shares per leg, each paying $1', and side default logic is explained. This enriches understanding beyond the schema.

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

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

The description clearly states the tool checks realizable vs theoretical edge against live CLOB order book depth, distinguishing single-market and basket modes. It is unique among sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains the risk of partial fills and directional exposure.

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

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

Annotations already indicate safe read-only behavior. The description adds extensive behavioral details: compatibility warnings, temporal alignment, skipped cross types/subtypes, 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 well-structured with clear sections and front-loaded purpose. Some detail on skipped cross types may be excessive, but every sentence contributes unique information 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 no output schema, the description fully covers return values, safety fields, and edge cases (compatibility warnings, temporal alignment). It provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions. The description adds value by listing the exact topic shortcuts, providing examples, and explaining the override logic between topic and explicit parameters.

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

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

The description clearly defines the tool as computing cross-venue spreads between Kalshi and Polymarket, with two modes and explicit output details. It distinguishes from sibling tools like polymarket_arbitrage by focusing on multi-venue analysis.

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 topic shortcuts versus explicit parameters and warns that pre-mapped topics often yield warnings. However, it does not explicitly contrast with alternatives like polymarket_arbitrage or when to avoid the tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scope (anonymous IP, BYO key hash, account ID) and mentions pairing with remember/forget, providing 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?

Three sentences, no verbosity. First sentence states main action, subsequent ones add value (use cases, scoping, pairing). Every sentence earns its place.

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

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

For a simple retrieval tool with 1 optional param, annotations cover safety, description covers purpose, usage, scope, and sibling relationships. 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 covers 100% of 1 parameter. Description adds value by explaining omitted key lists all keys and gives examples (user_research_topic). Baseline 3, extra context justifies 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?

Description clearly states verb 'retrieve' or 'list', resource 'value previously saved via remember' or 'all saved keys', and distinguishes from siblings (remember, forget). Examples of use cases (ticker, address) solidify purpose.

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

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

Includes examples of when to use (look up context stored earlier) and scoping info (identifier-based). Lacks explicit 'when not to use', but pairing with remember/forget provides implicit alternatives.

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

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

Annotations already declare readOnly, destructive, and idempotent hints. Description adds useful context: explains the mark_read side effect (flags events as read), describes return fields, and confirms polling is safe. 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?

Four sentences, front-loaded with main action, each sentence adds distinct information. No wasted words; efficiently covers purpose, return fields, filtering, side effect, and alternative access.

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?

Good coverage of main use cases (filtering by type and since, mark_read behavior) and mentions return fields. However, missing explanation for the unread_only parameter, and no output schema is provided to supplement return value understanding.

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

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

Schema covers all 5 parameters (100% coverage). Description adds value by providing example for type ('sec_8k'), explaining since as ISO timestamp, and detailing the effect of mark_read. However, the unread_only parameter is not explicitly mentioned.

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 'Pull fired events from your subscription feed' and describes what each alert carries. Distinguishes from siblings like list_subscriptions and recent_changes by focusing on fired events from a subscription feed.

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

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

Gives context for when to use (pulling recent alerts) and mentions polling works fine, but does not explicitly state when not to use or name alternative tools. The hint about the same feed available via API for scripts is helpful but not a clear guideline.

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, and non-destructive behavior. The description adds valuable context: multiple source fan-out, fallback logic (GDELT preferred, GNews on failure), and soft-failure for USPTO due to API sunset. This goes beyond what annotations provide.

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

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

The description is a single paragraph that front-loads query examples and key functionality, then details sources, parameters, and the sibling alternative. It is dense but not overly long. Slight structure improvements (e.g., bullet points) could enhance readability, but it remains concise and informative.

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

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

Despite lacking an output schema, the description explicitly states the return structure: 'changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers source behavior, fallback, parameter details, and alternatives, making it fully complete for an agent to 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 coverage is 100% with descriptions for all three parameters. The description adds meaning by giving example values for 'value' (ticker or CIK) and 'since' (ISO date or relative shorthand like '30d'), and clarifies that 'type' only supports 'company'. This extra context aids correct 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 provides a change feed for a company over a time window, specified with concrete query examples like 'What's new with X' and 'latest on Y'. It lists specific sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from the sibling 'entity_profile' tool, making its purpose unambiguous.

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

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

The description gives explicit examples of when to use the tool and explicitly states to use 'entity_profile' for static profiles. It also explains fallback behavior for news sources. However, it does not compare to other siblings like 'deep_research' or 'recent_alerts', which could provide further 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 provide idempotentHint but the description adds behavioral details: key-value scoping by identifier, persistence duration (24 hours for anonymous, persistent for authenticated). 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 (4 sentences) and front-loaded with the primary purpose. Every sentence adds value, and there is 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 the simple 2-parameter tool with no output schema, the description adequately covers purpose, usage context, persistence behavior, and relationship with sibling tools. It is complete.

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

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

The schema already fully describes the two required parameters, but the description provides examples of typical keys and explains the key-value pair abstraction. This adds context beyond the schema.

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

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

The description clearly states that the tool saves data for reuse later. It specifies the verb 'save' and resource 'data,' and distinguishes from siblings 'recall' and 'forget' by mentioning them.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and suggests pairing with recall and forget. This gives clear when-to-use guidance and contrasts with alternative memory tools.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context: it auto-disambiguates company inputs and internally cascades through several lookup endpoints, replacing 2-3 manual steps. This exceeds what annotations alone provide.

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

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

The description is moderately long but well-structured: it starts with example queries, states the core purpose, gives usage guidance, and then details each supported type. Every sentence adds value, and the front-loading is 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 absence of an output schema, the description thoroughly covers return values for both entity types, including citation URIs. It also explains input acceptance (ticker, CIK, name for company; brand or generic for drug) and internal cascading behavior, making it fully self-contained.

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

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

Schema description coverage is 100% with good schema-level descriptions for both parameters. The main description adds further value by detailing the return format for each type (e.g., ticker + CIK for company, RxCUI for drug), compensating for the lack of an output 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: resolving user-spoken names to canonical/official identifiers needed by other tools. It provides concrete example queries and details the specific supported entity types (company and drug) with what each returns, differentiating it from siblings 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?

The description explicitly advises when to use the tool: 'Use FIRST whenever you have a name but need an ID.' While it doesn't explicitly say when not to use it, the context makes it clear that it's for name-to-ID resolution, and no direct alternative is listed among siblings.

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

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

Beyond annotations (readOnly, idempotent, etc.), description details that the tool probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. Specifies return fields (score, confidence, signal density). No contradiction with annotations.

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

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

Two sentences plus a parenthetical example. Front-loaded with purpose. Every sentence adds essential context with no repetition 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?

Covers input, process, and output well. Since no output schema, description explains return structure. Lacks details on error handling or limits (e.g., entity count constraints), but adequate for a competitive audit tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by noting that first entity in 'entities' is treated as subject for narrative, and that 'context' is shared across probes. This enhances understanding beyond schema.

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

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

Title and description clearly state the tool compares AI visibility across multiple entities. Uses specific verb 'Compare' and resource 'AI visibility across multiple entities'. Distinguishes from sibling 'ai_visibility_check' by describing its aggregation and ranking functionality.

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 use case for competitive AI-marketing audits with an example question. References sibling ai_visibility_check as internal component, but does not provide explicit when-not-to-use or alternative sibling tool 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, idempotentHint, etc. Description adds important behavioral detail: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. No contradiction with annotations.

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

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

The description is front-loaded with purpose and key details, but runs long with multiple clauses and examples. Could be slightly tighter, but structure is logical.

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

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

Given the complexity (multiple data sources, partial failures, default version behavior), the description covers essential aspects. No output schema, but return fields are summarized. Adequate for agent use.

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

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

Schema coverage is 100%. Description adds that scoped packages are accepted for 'package' and that 'version' defaults to latest published when omitted, providing extra context 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 is a composite check for evaluating npm packages before adding to a project, covering license, advisories, version history, and bundle size. It specifies NPM ecosystem only in v1, distinguishing from sibling tools that may cover other ecosystems.

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?

Gives explicit use cases ('is X safe / popular / small' or 'what does adding lodash cost me') and notes NPM-only scope with alternatives for other ecosystems. No explicit when-not-to-use, but context is clear.

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

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

Discloses embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and character limit (200K chars, truncated and flagged). Annotations already declare idempotence and non-destructiveness, so description adds value by explaining internal mechanics without contradiction.

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

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

The description is concise with two sentences. Information is front-loaded and clear, though the second sentence is somewhat lengthy but packs necessary details.

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

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

Though no output schema exists, the description explains return format (passages with offsets and similarity scores). It also covers pairing with a sibling tool. Reasonably complete for a tool with three simple 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 coverage is 100%, so baseline is 3. Description adds context for 'text' (confirms max length), 'query' (gives example queries), and 'limit' (states default 5). Adds marginal value beyond schema.

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

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

Description explicitly states it does semantic search inside a fetched record, returning top-N passages with character offsets and similarity scores. It distinguishes itself from siblings like ask_pipeworx_grounded by explaining how they pair together.

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 using when the record is too big for the prompt to save context and avoid cramming. Also mentions pairing with ask_pipeworx_grounded for grounding over relevant passages instead of the whole document.

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 non-read-only, open-world, idempotent, non-destructive. Description adds substantial behavioral context: account type restriction, type-specific details, delivery channels with constraints (SMS rate limit, webhook auto-disable after 10 failures, signing secret one-time return). This far exceeds 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?

Description is roughly 100 words and front-loaded with purpose. It packs a lot of information into one paragraph, which is efficient but could benefit from bullet points for multiple types and delivery options. Every sentence adds value; 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 the complexity (3 parameters, nested objects, multiple types, delivery options), the description covers prerequisites, all type variations with examples, delivery constraints, return value, and even mentions the always-on feed. It is complete enough for an agent to correctly invoke the tool without requiring external documentation.

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

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

Schema coverage is 100%, but description enriches parameters significantly. It provides concrete examples for each type (e.g., sec_8k with items codes, polymarket_edge with topic), clarifies requirements for delivery fields (phone must be verified, webhook constraints), and explains the response includes webhook_secret. This goes well beyond the schema descriptions.

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

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

Description starts with 'Create a proactive monitoring subscription to a live-data event stream.' This clearly states the action (create), resource (subscription), and distinguishes from sibling tools like list_subscriptions or recent_alerts. It also mentions the return value (subscription ID).

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

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

Description specifies prerequisites (Pipeworx OAuth account), lists supported types with examples, and implies that subscription is for proactive push vs pull via recent_alerts. However, it does not explicitly state when not to use or compare to alternatives like unsubscribe.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds details about the output format (category-bucketed example questions with exact tool+argument shape) and the source ('live catalog of thousands of tools'), which goes 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 somewhat long but well-structured: it starts with common user questions, explains the output, then gives usage instructions. Every sentence provides value, though it could be slightly more concise without losing information.

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

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

Given the tool has only one optional parameter and no output schema, the description is completely adequate. It covers purpose, usage, parameter semantics, and the broad context of what questions are available. 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% and the parameter description lists possible values. The description adds meaning by explaining the effect of omitting vs. passing topic: 'no arguments for the full spread, or pass topic (e.g. finance) to focus.' This provides usage context not in the schema.

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

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

The description clearly states the tool's purpose: it returns example questions categorized by topic for onboarding. It distinguishes from siblings like ask_pipeworx by positioning itself as the starting point for understanding capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also explains when to omit the topic parameter or pass a specific focus. No explicit when-not-to-use, but the context is clear.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds that the row is deactivated not deleted, preserving historical events. It also mentions ownership enforcement, providing behavioral context beyond the structured fields.

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

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

The description is extremely concise with two sentences that front-load the action. Every sentence adds value without any 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?

Given the tool's simplicity (single param, no output schema, annotations present), the description covers ownership, the deactivation effect, and the relationship to historical events. It is fully complete for an agent to use correctly.

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

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

The schema already has 100% coverage with a clear description of the 'id' parameter. The tool description does not add additional meaning beyond what the schema provides, so it meets the baseline.

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

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

The description clearly states the verb 'cancel' and the resource 'subscription by id', making the purpose unambiguous. It distinguishes itself from the sibling 'subscribe' tool, though it does not explicitly contrast with other siblings.

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

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

The description explicitly notes ownership enforcement, guiding the agent to use this only for the user's own subscriptions. It implies when not to use it (for others' subscriptions) but does not mention alternative tools for that case.

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

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

The description adds value beyond annotations by detailing the return format (verdict categories, structured form, actual value with citation, percent delta) and the data source (SEC EDGAR + XBRL), with no contradictions to 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 trigger examples, and every sentence adds value—purpose, usage, scope, and output details are efficiently covered.

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

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

All necessary context is provided: purpose, usage, scope, and return format. The tool is simple (one parameter, no output schema) and the description is self-contained for an agent to select and 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?

Schema description coverage is 100% and already explains the 'claim' parameter well. The tool description does not add new parameter-specific meaning beyond restating the concept.

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 identifies the tool as a natural-language claim verifier against authoritative sources, listing trigger phrases and distinguishing it from sibling tools by noting it replaces multiple sequential calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the current scope (company-financial claims for public US companies), guiding appropriate invocation.

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