Dockerhub

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

Annotations already declare readOnlyHint, idempotentHint, and no destruction. The description adds cost implications (free vs. BYO key) and return structure, which are valuable beyond annotations. No contradictions.

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

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

The description is concise, well-structured, and front-loaded. It efficiently covers purpose, default behavior, parameter details, and use cases in a few sentences, with no redundant information.

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

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

Given 4 parameters and no output schema, the description adequately explains the return format (per-model {score, confidence, signals, raw_response} + combined view). It covers essential details for an agent to use the tool correctly, though a bit more on the combined view could push to 5.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context like default model (Workers AI Llama-3.3-70b) and explains that _apiKey is passed through to Anthropic, which adds meaning beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for brand/product visibility and scores it 0-100 per model, with specific use cases. It distinguishes itself from siblings by focusing on AI visibility measurement, not general Q&A or research.

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

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

The description explicitly lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use additional parameters (models, _apiKey). It does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations already convey readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it routes to 3,745 tools across 884 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This adds behavioral detail beyond annotations.

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

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

The description is detailed and well-organized, with a clear preference statement, list of applicable data types, explanation of mechanism, usage guidance, and examples. While slightly long, every sentence adds value and it is front-loaded with the most important 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 (3,745 tools, 884 sources) and lack of output schema, the description provides adequate context: it explains the routing mechanism, return format (structured with citations), and gives concrete examples. It is sufficient for an agent to understand when and how to invoke the tool.

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

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

Schema coverage is 100% with 6 parameters (all aliases for 'question'), each described clearly. The description explains that the tool fills arguments and routes the question to the right tool, adding semantic context about how the parameter is used. This goes beyond the schema's basic description of the parameter.

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

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

The description uses a specific verb 'routes' and clearly identifies the tool's function: answering factual questions by routing to one of 3,745 tools across 884 sources. It distinguishes itself from web search and lists a wide range of data types (SEC filings, FDA drugs, etc.), making its purpose unmistakable.

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

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

The description explicitly states 'PREFER OVER WEB SEARCH' for questions about structured data and provides a detailed list of when to use, including example queries and trigger phrases ('what is', 'look up', etc.). It does not explicitly state when not to use, but the preference is clear, and the examples cover many domains.

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

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

Annotations (readOnlyHint, idempotentHint) indicate safety, but the description adds significant behavioral context: the tool routes to a tool from a large set, fills arguments, and extracts answers only from the tool result, with explicit refusal reasons. 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?

Well-structured: starts with purpose, then behavior, return format, usage guidance, and cost trade-off. Every sentence is informative, though listing all refusal reasons in detail could be considered slightly verbose. Still effectively 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?

Despite no output schema, the description comprehensively details the return object (including success and failure modes) and the routing behavior. The tool's complexity is well-addressed, making it complete for an AI agent to decide and invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by explaining that the question will be used to route and fetch data, but the parameter semantics are already clearly defined in the schema. Slightly above baseline due to this contextual addition.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes it from the sibling tool 'ask_pipeworx'. It uses specific verbs ('extracts', 'returns') and resource ('answer from tool result').

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups'. Also mentions the extra cost vs. the sibling, giving clear context for when to use this tool vs. alternatives.

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

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

The description extensively details behavioral traits beyond annotations: fan-out logic per category, response shapes, resolver contract, parent event extractor, news fallback fields, safety mechanisms (low confidence short-circuit, closed market handling, wide spread warnings), and resolution-rule risk. Annotations indicate read-only, idempotent, non-destructive; description confirms and adds deep context 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 very long (multiple paragraphs) and covers many details. While structured, it could be more concise without losing essential information. It front-loads the main purpose but then dives into extensive specifics.

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

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

Given the tool's complexity (multiple classifiers, fan-out patterns, response shapes, edge cases) and absence of output schema, the description is remarkably complete. It covers all key aspects: resolution handling, parent events, news fidelity, safety checks, cancellation rules. No significant gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning: examples for market parameter, explanation of depth options, and detailed guidance on include_raw (summary vs. full payloads, response size implications). This adds value beyond the schema.

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

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

The description explicitly states it researches a Polymarket bet by pulling Pipeworx data in one call. It clearly defines input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from siblings like polymarket_edges which focus on cross-market edge detection, while this tool is for a single bet.

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 cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. However, it does not explicitly state when not to use it or compare to sibling tools for exclusion.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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?

Single dense paragraph front-loaded with common query patterns. Every sentence is informative, but could benefit from slight structuring (e.g., separate input behavior vs output). Still very concise and 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?

No output schema, but description briefly covers return format (paired data + citation URIs) and sorting. Covers input, behavior, and output adequately for a simple two-param tool. Could mention error handling or rate limits, but overall 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%, but description adds value by explaining what each type returns (company: financials, drug: adverse events, approvals, trials) and providing examples for values (tickers, drug names). Reinforces constraints and adds context beyond schema.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 entities (companies or drugs) with specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from sibling tools like entity_profile by emphasizing one parallel call vs sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries that map to the tool. Clearly indicates when to use it (comparing entities) and implies not to use it for single entity lookups.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are complemented by detailed behavioral description: decomposition, parallel routing, verbatim evidence, confidence, source, gaps array, citation scheme, non-invention guarantee, and expected response time (15-60s). No contradictions.

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

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

The description is dense and well-structured but slightly long. Front-loaded with main purpose, but every sentence earns its place. Could be trimmed slightly without losing 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 complexity, zero output schema, and rich annotations, the description covers all necessary aspects: purpose, usage, behavioral traits, parameter semantics, prerequisites, and expectations. Fully adequate for agent selection and invocation.

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

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

Although schema coverage is 100%, the description adds significant value: explains depth options ('quick=3, standard=5, thorough=8'), that thorough requires paid plan, and that question can be broad/multi-part. This enables proper agent decision-making.

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: 'grounded multi-source research in one call'. It specifies the action (research, decompose, route, extract), the resource (multi-source), and distinguishes it from sibling tools like ask_pipeworx.

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

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

Explicitly states when to use: 'Use for broad or multi-part questions' and when not: 'use ask_pipeworx for single lookups'. Also mentions prerequisites (Pipeworx account) and limitations (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 and destructiveHint=false, ensuring safety. The description adds value by stating the return format (top-N tools with names, descriptions, full input schemas with examples, ready to call) and that no second schema lookup is needed. 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 front-loaded with the core purpose and efficiently lists domains and return value details. The list of domains is lengthy but informative. Every sentence earns its place, though it could be slightly more concise.

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

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

Given the tool's simplicity and full annotation coverage, the description provides complete context: what it does, when to use it, what it returns (with examples), and even a note on no second schema lookup. No output schema exists, but the return value is well-explained.

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 6 parameters, so the description does not need to add much. It merely restates the natural language intent for the query parameter. No extra semantic nuance is provided 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 finds tools by describing data or task, and distinguishes it from siblings by positioning it as a first-call meta-tool to browse available options. The verb 'find' and resource 'tools' are specific, and the list of domains clarifies scope.

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

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

The description explicitly advises to 'call this FIRST' when wanting to see the option set, and provides concrete use cases (browse, search, look up, discover) with a list of covered domains. This gives strong guidance on when to use it versus alternatives.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent. The description adds context: fans out across multiple APIs, explains the USPTO sunset soft-fail, fallback mechanisms (GDELT→GNews), and specifics of returned data (e.g., 'LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC'). No contradictions.

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

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

The description is dense with useful information but slightly verbose. It is well-structured with examples first, then behavior details, and limitations. A bit more conciseness could improve scanning, but still highly effective.

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

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

Since there is no output schema, the description fully explains what the tool returns, including specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), field details, and known limitations (USPTO sunset). This is comprehensive for a holistic profile tool.

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

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

Schema coverage is 100%, but the description adds significant value: it explains the 'type' parameter is only 'company' for now, and for 'value' it specifies ticker or zero-padded CIK formats, explicitly stating names are not supported. This goes beyond simple schema descriptions.

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

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

The description states the tool generates a 'full cross-source profile of a US public company' with specific examples like 'Tell me about X' and lists exact outputs (CIK, filings, fundamentals, patents, news, LEI). It explicitly distinguishes from chaining single-pack lookups, making the purpose very clear.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over chaining single-pack lookups' when the user asks for a holistic view. It also tells when not to use it (names not supported) and directs to use resolve_entity first. It details accepted input formats (ticker or zero-padded CIK) and warns about unsupported names.

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

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

Description aligns with annotations (destructiveHint=true, readOnlyHint=false). Adds context about clearing sensitive data and reasons for deletion. Does not mention idempotency but annotations already cover that.

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

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

Two sentences, no wasted words. Front-loaded with action and resource, then usage guidance.

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?

Tool has low complexity (single param, no output schema). Description fully covers purpose, usage context, and relation to sibling tools. No gaps.

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

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

Schema coverage is 100% for the single parameter 'key', and schema already documents its purpose. Description adds no additional parameter 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?

Description states 'Delete a previously stored memory by key' – specific verb and resource, distinguishes from siblings by mentioning 'remember and recall'.

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

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

Explicitly states when to use: 'context is stale, task done, clear sensitive data'. Also advises pairing with 'remember and recall', providing clear context and alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that it fetches the page, extracts elements, and emits markdown. Could mention error handling for unreachable URLs, but overall adds useful behavioral context beyond annotations.

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

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

The description is three sentences, starting with main purpose, then process, then use cases. It is front-loaded and concise, though the use-case list could be slightly trimmed. No unnecessary words.

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

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

For a simple tool with two parameters and no output schema, the description covers all necessary context: purpose, process, output format, and usage scenarios. No gaps that would hinder correct agent invocation.

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

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

Schema descriptions for 'url' and 'max_links' are already clear and cover 100% of parameters. The description does not add new semantic details about the parameters; it merely restates the process. Baseline score of 3 is appropriate.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, explaining the process (fetches page, extracts title/description/key links, emits standard markdown) and output format. It is specific and distinct from sibling tools like scan_competitor_ai_presence.

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

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

Explicitly lists three use cases: getting client's site indexed, drafting own project's llms.txt, auditing competitor's AI visibility. Lacks explicit 'when not to use' guidance, but the uniqueness among siblings makes that less critical.

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. Description adds that it 'gets metadata', reinforcing the read-only nature, and specifies the returned data fields, providing useful context beyond annotations.

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

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

Two concise sentences front-load the purpose and usage, with zero wasted words. Every sentence serves a clear function.

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 metadata retrieval tool with comprehensive annotations and output schema (not shown but implied), the description covers all essential aspects: what it does, what data it returns, and when to use it.

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

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

Input schema has 100% coverage with clear descriptions for both parameters. Description does not add new parameter semantics beyond the schema, so baseline 3 is appropriate as the description does not degrade but also does not enhance understanding.

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

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

Description clearly states the tool retrieves detailed metadata for a Docker Hub repository, listing specific fields (description, pull count, stars, etc.). It differentiates from siblings like search_images by focusing on metadata for a specific repository and noting the use case of verifying before pulling.

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 before pulling an image to verify quality and currency, which provides clear when-to-use context. It lacks mention of when not to use or explicit alternatives, but the guidance is sufficient for the tool's simple purpose.

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, idempotent, and non-destructive. The description adds valuable context: the sort order ('by recency') and the specific return fields ('tag name, digest, size, and push date'). No contradictions, and the additional details enhance the agent's understanding.

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 three sentences, each serving a distinct purpose: stating the action and sorting, listing returned data, and providing usage context. No wasted words.

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

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

For a simple listing tool with full schema coverage, good annotations, and an output schema, the description is complete. It covers what the tool does, what it returns, and how to use it. No additional information is necessary for correct invocation.

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

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

The input schema has 100% description coverage, so the schema already defines the parameters well. The description only indirectly references the required parameters ('for a Docker image' implies namespace and name). It does not add new semantic information beyond the schema.

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

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

The description explicitly states the action ('List available tags'), the resource ('for a Docker image'), and the sorting ('sorted by recency'). It also differentiates from sibling tools like search_images by clearly specifying that it lists tags of a given image, not searching for images.

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

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

The description includes a clear usage suggestion ('Use to find and select specific versions to pull'), indicating when the tool is appropriate. It does not explicitly mention when not to use it or provide alternatives, but the purpose is well-stated.

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. Description adds return fields (id, type, params, etc.) and default active-only behavior. No contradictions. Lacks mention of pagination but acceptable for simple list.

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 purpose, zero unnecessary words. Perfectly concise.

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

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

Describes return fields and usage context. No output schema, so description carries documentation burden. Slightly incomplete on field semantics (e.g., 'params' undefined) but adequate for a 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 coverage is 100% with description for include_inactive. Description adds minimal value beyond schema (implies default active). Baseline 3.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinct from sibling tools subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more' and 'find an id to cancel', directly connecting to subscribe/unsubscribe 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 limits, free usage, and team reading frequency, adding context beyond annotations. No contradictions with annotation hints.

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

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

Single paragraph with clear structure; each sentence adds value without redundancy. Slightly verbose but still effective.

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

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

Thoroughly covers usage, constraints, and expected behavior for a 3-parameter tool with nested objects and no output schema.

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

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

Schema coverage is 100%, but description adds practical guidance (e.g., '1-2 sentences typical, 2000 chars max') and clarifies context fields' purpose.

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

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

Clearly states the tool's purpose: sending feedback about bugs, features, data gaps, or praise. Distinguishes itself from all sibling tools which are analytical or informational.

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

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

Explicitly specifies when to use each feedback type (bug, feature, etc.), warns against pasting end-user prompts, and mentions rate limits (5/day) and quota exemption.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true. The description adds useful behavioral context: derived from CF analytics-engine, no PII, just counts, and caching behavior (5min-1h depending on window). This goes beyond what annotations provide without contradictions.

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

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

The description is concise with no wasted words. It starts with a clear purpose, then lists specific use cases, followed by additional details. Each sentence serves a purpose, and the structure is easy to scan.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description adequately explains the return concept (top tools, packs, call volume) but lacks exact output format. However, for an aggregated trend tool, this is sufficient context for an AI agent to decide and invoke correctly.

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

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

Schema coverage is 100% with a single parameter described. The description adds value by explaining the effect of different window values: "Shorter windows surface what's hot right now; longer windows show steady-state demand." This enhances the schema's description.

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

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

The description clearly states it returns "top tools, top packs, and total call volume" over a recent window. It distinguishes from sibling tools by focusing on trending aggregated usage data, which is unique among the listed siblings.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, checking alignment). It provides clear context on when to use the tool but does not explicitly state when not to use it or mention alternatives. The context is strong but lacks exclusion criteria.

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

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

The description discloses all relevant behavioral traits beyond the annotations. It explains the monotonicity and partition-sum checks, the semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and the fill check that distinguishes theoretical vs. realizable edge. It warns about thin legs and conditions where the arbitrage is not tradeable. Annotations already mark the tool as read-only and idempotent, and the description adds rich context 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 well-structured, starting with the essential requirement, then detailing each mode, the checks, and the response. It uses bolded terms and clear sections. Every sentence adds value, and the length is appropriate given the tool's complexity. There is no redundancy or waste.

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

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

Despite the lack of an output schema, the description thoroughly explains the response structure: opportunities[] with fields like gap_pp, suggested_trade, reasoning; and partition_check with sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade. It also covers the fill check output. The description integrates well with the sibling tool polymarket_fill_risk for further actions. It is complete for an agent to understand and invoke correctly.

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

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

Although the input schema has 100% description coverage, the description adds significant meaning: it explains that `event` accepts slugs or full URLs, gives examples like 'fed-decision-may-2026', and clarifies that `topic` is a seed question for cross-event scanning. It also describes the behavioral difference between the two modes, which is not evident from the schema alone.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two distinct modes (event and topic) and explains what each does. It also differentiates from the sibling tool polymarket_fill_risk, which is for assessing fill risk, not detecting arbitrage. The verb-resource combination is specific and unambiguous.

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

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

The description explicitly starts with 'REQUIRES one of `event` or `topic` — call with no args fails,' providing a clear constraint. It recommends event mode for specific markets and topic mode for cross-event scanning. It also directs users to polymarket_fill_risk for custom sizing, offering an alternative tool when needed. This gives comprehensive when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds extensive behavioral context: caching (1h at KV level), detailed model families (FRED, GDELT), edge calculation including slippage, output structure with by_segment and diagnostics, and filter knobs. 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 quite long (multiple paragraphs) and contains a lot of technical detail. It is front-loaded with the purpose and well-structured, but it could be more concise without losing essential information. Given the complexity of the tool (9 parameters, three model families), the length is somewhat justified, but it still feels verbose.

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

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

The description is thorough and covers all aspects needed for an agent to use the tool correctly: model families, edge calculation, filtering knobs, output structure with diagnostics, caching, and example defaults. There is no output schema, so the description compensates fully by explaining return values (segments, diagnostics). The detail is comprehensive given the tool's complexity.

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

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

Schema coverage is 100% with all 9 parameters described. The description adds significant value beyond the schema, explaining the role of each parameter in the tradeable-edge filters, providing examples (e.g., min_liquidity: 'Set to 5000 to drop thin-book opportunities'), and clarifying interactions (e.g., min_kelly vs min_partition_leg_kelly). The descriptions are more detailed than the bare schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs (scan, return) and identifies the resource (Polymarket markets with edge opportunities). The title 'Polymarket Edges' matches. It distinguishes from sibling tools like polymarket_arbitrage and bet_research by focusing on edge opportunities from model disagreement.

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

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

The description explicitly states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides clear context for when to use the tool. While it doesn't explicitly mention when not to use it or list alternatives, the sibling tool names (like polymarket_arbitrage) imply different focuses. The usage guidance is strong but lacks explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: snapshots are written on cache-miss, data bounded by TTL, decay computed on daily closes net of default slippage (not intraday). This enriches the agent's understanding beyond annotations.

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

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

The description is detailed but front-loaded with the core question. Some technical phrases could be streamlined, but every sentence adds value. It is well-structured for an experienced user.

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

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

Despite no output schema, the description thoroughly explains the response structure: tracked[], expired[], snapshot_dates[] with field semantics (first_seen, trend, decay_pp_per_day, lifespan_days). It also covers limitations and data gaps. This fully compensates for the missing 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 basic descriptions. The description adds context: default values (days=14, window='1wk'), clamping (days 2-30), and interprets window as 'snapshot family'. This adds meaning beyond schema definitions.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from siblings like polymarket_edges by focusing on historical time-series and trend analysis. The verb 'answers' with a specific question ('how long has this edge existed and is it shrinking?') makes the purpose explicit.

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 context on when to use: for distinguishing between fresh and old edges, implying use for historical analysis. It mentions limits (60-day TTL, snapshot start) but does not explicitly state when not to use or compare to alternatives like polymarket_edges. The example provides strong situational 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds operational details: walks the ladder, returns verdict (clean|degraded|cannot_fill), identifies forced directional risk, and explains the dominant loss mode. It does not contradict annotations.

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

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

The description is lengthy but well-structured with sections for modes and return fields. Every sentence adds value, but the density may be slightly high for quick parsing. Front-loaded with purpose and required parameters.

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

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

No output schema exists, so the description covers return values thoroughly: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. It fully compensates for missing 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 description coverage is 100%. The description adds context: explains size_usd interpretation (max spend vs target proceeds), default side for basket (auto), and clarifies mode selection. It goes beyond the schema descriptions.

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

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

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return fields and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk.

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

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

It explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns about partial basket fills converting arb into unhedged positions. It also specifies required parameter choices (market vs event).

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are already informative. The description adds rich behavioral details: two modes, response structure including safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge case handling. No contradiction with annotations.

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

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

The description is thorough but slightly verbose. It front-loads the main purpose and uses clear sections (modes, response, safety fields). While every sentence provides value, it could be tightened slightly without losing clarity.

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

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

Given no output schema, the description explains response fields thoroughly (top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers potential issues and edge cases, making it complete 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?

Input schema covers all 3 parameters with descriptions. The description adds value by listing the 10 topic shortcuts, explaining override semantics for explicit ticker/slug, and providing examples. Schema coverage is 100%, so description adds moderate extra context.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings (e.g., polymarket_arbitrage) by focusing on cross-venue comparison.

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

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

Explicitly explains when to use (to compare spreads) and when not (compatibility_warning scenarios, temporal misalignment). Provides clear usage modes (topic vs explicit ticker/slug) and notes pre-mapped topics may not always be tradeable.

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, and idempotentHint=true. The description adds behavioral detail such as listing all keys when key is omitted, and scoping to identifier. 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?

Four sentences, each serving a distinct purpose: operation, usage context, scoping, and related tools. No wasted words; efficient and well-structured.

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

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

Given no output schema, the description covers the tool's function, usage context, scoping, and related tools. It does not specify return format, but for a simple retrieval/list tool, this is not a critical gap.

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

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

The single parameter 'key' is fully described in the schema (100% coverage). The tool description adds semantic enrichment with examples of typical key values (user target ticker, address, research notes), going beyond the schema's basic description.

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

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

The description clearly states the tool retrieves previously saved values or lists all keys, with a specific verb and resource. It distinguishes from siblings remember and forget by explicitly naming them as pairs, and explains that omitting the key triggers listing.

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

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

Provides concrete examples of when to use (look up user target ticker, address, research notes) and mentions scoping to identifier. However, it does not explicitly state when not to use this tool over alternatives, though the pairing with remember/forget implicitly covers it.

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

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

The description states that setting mark_read:true flags returned events as read (a state change), but the annotation readOnlyHint is true, implying no modifications. This is a direct contradiction, scoring 1.

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 purpose, then returns, filter options, and side notes. No unnecessary words; every sentence adds value.

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

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

Covers return fields, filtering, mark_read effect, and alternative access. Missing explicit mention of limit parameter behavior and unread_only, but those are in schema. Adequate for a read-only tool.

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

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

Schema coverage is 100% with descriptions; the description adds examples (type 'sec_8k') and explains the effect of mark_read and since, adding value beyond the schema.

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

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

The description clearly states it pulls fired events from a subscription feed, specifying the verb 'Pull' and the resource 'fired events'. It differentiates from siblings like 'list_subscriptions' by focusing on events rather than subscriptions.

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

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

The description explains filtering options (type, since) and the effect of mark_read, and notes polling is fine. It also provides an alternative URL for script/dashboard access, giving context on when to use this tool vs. the API endpoint.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the multi-source fan-out (SEC, GDELT/GNews, USPTO), fallback behavior, and return structure (changes[] grouped by source + total_changes + citation URIs).

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

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

The description is information-dense but well-structured, starting with usage examples, then behavior, parameters, return values, and sibling differentiation. It earns its length, but could be slightly more concise.

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

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

Despite no output schema, the description fully explains return values (changes[], total_changes, citation URIs) and covers all aspects: behavior, parameters, sources, fallback, and alternative tool. Complete for a 3-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 coverage is 100%, but the description adds significant value: explains 'since' accepts ISO dates or relative shorthand with examples ('7d', '30d', '3m', '1y'), recommends '30d' for monitoring, clarifies 'value' accepts ticker or CIK, and restricts 'type' to 'company'.

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

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

The description clearly states it provides a 'change feed for a company in the last N days/weeks/months' using specific verbs and resource. It explicitly distinguishes from the sibling tool 'entity_profile' which provides static profiles.

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 usage examples ('What's new with X', 'latest on Y') and recommends using 'entity_profile' instead for static profiles. It provides clear context on when to use this tool.

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

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

Annotations indicate this is a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds valuable behavioral details: persistence differences between authenticated users (persistent) and anonymous sessions (24-hour retention), and scoping by user identifier. 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 four sentences long, with the first sentence immediately stating the core purpose. Every sentence adds necessary context (usage, examples, persistence, companion tools) without unnecessary words or repetition.

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

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

For a simple key-value store tool with two parameters and no output schema, the description fully covers usage scenarios, storage semantics, persistence rules, and links to companion tools (recall, forget). It is complete for the intended 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?

The input schema already covers both parameters with clear descriptions, achieving 100% coverage. The tool description adds no new semantic information about the parameters beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Save data' and the resource 'data the agent will need to reuse later', distinguishing it from sibling tools like recall and forget. It provides specific examples and context, making the purpose unmistakable.

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

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

The description explicitly advises when to use the tool ('when you discover something worth carrying forward') and gives concrete examples such as resolved ticker or user preference. While it mentions pairing with recall and forget, it does not explicitly state when not to use it, so it falls just short of 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 already indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool 'cascades through several lookup endpoints internally,' providing useful behavioral context beyond the annotations.

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

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

The description is fairly long but well-structured with front-loaded examples and bullet-like details for each type. Every sentence adds value, though a slight condensation could improve conciseness without losing content.

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

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

Despite lacking an output schema, the description thoroughly explains what each entity type returns (e.g., ticker, CIK, RxCUI, citations). It also covers internal cascading behavior, making it complete for an AI agent to understand the tool's capabilities and output.

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

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

Schema coverage is 100%, but the description greatly enhances parameter meaning. For 'type' it explains the enum values and their return types. For 'value' it details accepted formats (ticker, CIK, name for companies) and auto-disambiguation, far exceeding the schema's brief descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, using examples like ticker, CIK, RxCUI. It distinguishes itself by advising 'Use FIRST whenever you have a name but need an ID,' setting it apart from sibling tools that likely operate on known IDs.

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

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

It explicitly guides when to use the tool via the 'Use FIRST' directive and lists supported entity types with input formats. It does not explicitly state when not to use, but the context is clear enough for an AI agent.

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

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

Describes that it probes each entity with ai_visibility_check, returns ranked list with metrics, and treats first entity as subject. Adds context beyond annotations, which already indicate read-only, idempotent, non-destructive behavior.

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

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

Three concise sentences front-loaded with purpose, process, and use case. No fluff; the example quotation adds value without being verbose.

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

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

Covers what, how (via ai_visibility_check), output (ranked list with score/confidence/signal density), and usage scenario. Without output schema, the description sufficiently informs 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?

Adds meaning beyond schema by clarifying the first entity's role as subject, the default model, and context disambiguation. Schema coverage is 100%, so description enhances understanding.

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

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

Clearly states the verb 'compare' and resource 'AI visibility' across multiple entities, distinguishing from sibling ai_visibility_check by emphasizing side-by-side comparison and ranking.

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 it's useful for competitive AI-marketing audits and implies single-entity checks should use ai_visibility_check. Could be more explicit about 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: composite nature, multiple sources, bundlephobia timing (5-30s first measurement), and sources_failed field. No contradiction with annotations.

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

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

The description is thorough but slightly lengthy. It effectively front-loads the composite purpose and uses clear structure. Could be trimmed slightly but every sentence serves a purpose.

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

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

No output schema exists, so the description fully explains the return structure: summary block with fields (is_latest, license, etc.), per-advisory detail, links, and alternative versions. Also covers partial failure behavior, making it complete for a tool with this complexity.

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

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

Schema coverage is 100%, so schema already documents both parameters. The description adds value by noting scoped packages are accepted (e.g., '@types/node') and that version defaults to latest. This is helpful but not extensive beyond schema.

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

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

The description clearly states it's a 'composite check for adding an npm package' that fans out across deps.dev and bundlephobia, specifying the exact purpose and differentiating from sibling tools by noting it's NPM-only in v1.

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 an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also clarifies ecosystem scope and mentions graceful degradation for partial failures.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false, indicating a safe, read-only operation. The description complements this by specifying the source (Docker Hub) and the exact return fields, adding useful behavioral context 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 extremely concise with two sentences: one stating the action and return, the other providing usage guidance. No wasted words.

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

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

Given the existence of an output schema (not shown but indicated), the description does not need to detail return values. It covers the purpose, usage, and key behavioral aspects, making it complete for a search tool.

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

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

Schema description coverage is 100% with both parameters documented. The description mentions 'by keyword' aligning with the query parameter but adds no additional parameter-specific meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states it searches Docker Hub for container images by keyword and lists the return fields (repository name, description, pull count, star count, official status). It distinguishes from sibling tools like get_image and get_tags, which are for retrieving specific images or tags rather than searching.

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

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

The description provides a use case ('Use when finding images for deployment'), but does not explicitly state when not to use this tool or mention alternatives like get_image or get_tags. It gives context but lacks exclusions or explicit alternative 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable details beyond annotations: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K), truncation with flag, and that passages include offsets for verification.

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: starts with the core purpose, then usage guidance, then technical details. It is slightly verbose but every sentence adds value. 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?

Despite no output schema, the description fully explains what is returned (top-N passages with offsets and scores). It covers constraints (character cap, truncation), embedding details, and pairing with another tool. For a tool with few parameters, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter-level meaning beyond what the schema provides; it repeats the text and query descriptions. However, it does provide technical context about embeddings and windows, which indirectly helps understand parameters but doesn't improve their semantics.

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

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

The description clearly states it performs semantic search inside a fetched record. It distinguishes from sibling tools like ask_pipeworx_grounded by specifying use case when record is too large, providing a specific verb and resource.

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

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

Explicitly states when to use: when the record is too big to fit in the prompt. It also names an alternative (ask_pipeworx_grounded) and explains how they pair together, giving clear guidance on usage context.

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

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

Annotations already indicate write behavior and idempotency. The description adds valuable behavioral details: OAuth requirement, phone verification for SMS, 10/day cap, and webhook signing secret returned once. These complement the annotations without contradiction.

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

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

The description is well-structured with a clear opening line stating purpose and return, followed by requirements, type examples, and delivery options. It is fairly lengthy but each sentence adds substantive value without redundancy.

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

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

Given the richness of the schema and annotations, the description covers prerequisites, all subscription types with examples, delivery options with constraints, and the return value. It lacks error handling details but is complete for a subscription creation 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?

With 100% schema coverage, the description significantly enhances parameter understanding by providing concrete examples for each subscription type, explaining delivery channel behaviors, and detailing constraints like phone verification and caps. This far 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 explicitly states 'Create a proactive monitoring subscription' and highlights the return of a new subscription id. It distinguishes from siblings like list_subscriptions (list existing) and unsubscribe (remove) through its focus on creation.

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

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

The description specifies the requirement for a Pipeworx OAuth account and details supported subscription types with examples. While it does not explicitly state when not to use the tool, it provides clear context and prerequisites, making the usage straightforward.

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, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable behavioral context: it returns example questions from a live catalog, can be called with no arguments for full spread, and focuses on onboarding. 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 reasonably concise and well-structured, starting with common user questions and then explaining functionality. While it is not extremely short, every sentence adds value, making it effective without being verbose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains the return format (category-bucketed examples with tool shapes) and the appropriate usage context. Annotations cover safety, so nothing is missing.

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 single optional topic parameter. The description adds context by listing example topic values (e.g., 'finance', 'pharma') and the effect of omitting the parameter, going beyond the schema's description.

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

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

The description clearly states the tool's purpose as an onboarding entry point, listing multiple natural language queries that trigger it (e.g., 'What can I ask Pipeworx?', 'give me ideas'). It specifies it returns category-bucketed example questions with tool call shapes, effectively distinguishing it from sibling tools that perform specific queries.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use the optional topic parameter. While it does not explicitly list when not to use it, the context and emphasis on 'first' guide the agent well.

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 idempotentHint=true and destructiveHint=false; description adds context that the row is deactivated (not deleted) and historical events remain via recent_alerts, which adds value beyond 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?

Two concise sentences that cover purpose, ownership, and side effect with no wasted words. Front-loaded with the action.

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

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

Given the simple tool (1 param, no output schema, clear annotations), the description provides all necessary context: purpose, ownership constraint, and deactivation behavior. Complete for an agent to select and invoke correctly.

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

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

Single parameter 'id' is well-described in schema as 'Subscription id (uuid) returned by subscribe.' With 100% schema coverage and one param, description doesn't need extra detail; baseline 4 is appropriate.

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

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

The description clearly states the action (cancel a subscription by id) and adds specific details about ownership enforcement and deactivation behavior, differentiating it from siblings like 'subscribe'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), giving clear when-to-use guidance. Implicitly contrasts with 'subscribe' and 'list_subscriptions', but lacks explicit alternatives.

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

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

Annotations provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint false, indicating safe, repeatable, non-destructive behavior. The description adds significant context: it returns a verdict (confirmed / approximately_correct / refuted / inconclusive / unsupported), extracted structured form, actual value with pipeworx:// citation, and percent delta. It also notes it replaces 4-6 sequential calls, giving insight into efficiency.

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

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

The description is moderately concise but front-loaded with key synonyms and usage context. Every sentence adds value—purpose, scope, return details. It could be slightly shorter but remains 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 has only one parameter and no output schema, the description fully explains what the tool does, when to use it, what it returns, and its limitations. It covers the verdict types, return structure, and citation format, making it complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with one parameter 'claim' having a description. The tool description adds extra meaning by providing example claims ('Apple's FY2024 revenue was $400 billion') and clarifying it's a natural-language factual claim. This goes beyond the schema description, which only gives a generic example.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources for factual correctness. It provides synonyms like 'fact check' and 'verify the claim that...', directly distinguishing it from sibling tools like deep_research or search_within by focusing on claim verification rather than general research.

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

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

The description explicitly mentions when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also limits scope to 'company-financial claims (revenue, net income, cash position for public US companies).' While it does not explicitly list when not to use, the scope provides clear boundaries.

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