Va Museum

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world behavior. The description adds significant value by detailing the default model, the BYO key model for Anthropic, the cost implication, and the per-model response structure (score, confidence, signals, raw_response).

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence adds necessary information without repetition or fluff.

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

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

With 4 parameters, 1 required, and no output schema, the description must cover both. It fully explains all parameters and details the return format (per-model fields plus combined view, scoring 0-100). This is complete for an AI agent.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. However, the description adds substantial meaning: it explains the default model for models parameter, clarifies that _apiKey is optional and for Anthropic only, and describes how context disambiguates. This elevates the score.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score. It specifies the default model and how to add Anthropic. It distinguishes from siblings like scan_competitor_ai_presence by focusing on general visibility rather than competitive scanning.

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 brand checks, competitive monitoring. It does not provide when-not-to-use or alternative tools, but the context is clear enough for an AI agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds behavioral details: it routes to the right tool, fills arguments, and returns structured answers with citation URIs. No contradictions.

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

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

The description is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and is reasonably concise for the amount of information. It lists examples but could be slightly more compact; however, every sentence adds value.

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

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

Given the tool's complexity and the presence of annotations and output schema absence, the description sufficiently covers purpose, usage, and behavior. It provides examples and scope, though it could mention error handling or output format but is not required.

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 each parameter (aliases for question) described. The description adds examples and mentions that it accepts various aliases, but does not add significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: to answer factual questions by routing to one of many verified sources, with specific examples and a distinction from web search. It names the verb 'ask' and the resource ('3,591 tools across 836 verified sources').

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 to prefer this over web search for many types of factual queries and lists trigger phrases like 'what is', 'look up', etc. It does not explicitly exclude alternative sibling tools but provides clear 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds significant behavioral context: refusal reasons, return structure (answer, evidence, etc.), and the guarantee of not inventing facts. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage, then details behavior. It's informative but slightly long; however every sentence adds value. Very well structured.

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

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

Despite no output schema, the description fully explains the return object and possible refusal reasons. Parameter complexity is low (6 aliases for one parameter). The description covers behavior, error cases, and usage context completely.

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 3. The description notes 'question in natural language' and aliases, but adds little beyond the schema's own descriptions. Does not compensate with extra parameter semantics.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies it routes like ask_pipeworx but extracts answers only from tool results, distinguishing it from the sibling ask_pipeworx. The verb 'EXTRACTS' and resource 'answer from tool result' are 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also provides when not to use: 'prefer ask_pipeworx for casual lookups.' Mentions cost trade-off, giving clear guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral details: resolver contract, parent event extractor, news fallback mechanisms, safety for low-confidence matches, closed market handling, and liquidity warnings. 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 verbose but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds important information for a complex tool, though some redundancy could be trimmed. The opening sentence is clear and front-loaded.

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

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

Given the tool's complexity and lack of output schema, the description covers all aspects: input examples, output structure, edge cases (low confidence, closed markets, wide spreads), and safety mechanisms. It provides complete guidance for correct usage.

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

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

All three parameters have schema descriptions, and the tool description explains their meaning in detail: market input formats, depth options with defaults, and include_raw with size implications. Examples and clarifications add value beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and distinguishes it from siblings like ask_pipeworx_grounded or polymarket_edges by offering comprehensive research in one call.

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

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

The description explicitly states when to use the tool: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z''. It doesn't mention when not to use it or alternatives explicitly, but the context implies it's for thorough research rather than quick queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled, fiscal year handling, sorting by primary metric, and return of citation URIs. No contradictions. Slightly more detail on output structure could improve, but current coverage is strong.

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 longer but every sentence adds value. It is front-loaded with example queries, then structures information by entity type, sorting, and return format. A minor improvement could be trimming redundancies (e.g., repeating 'type=' explanations), but overall it is well-organized and not 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 complexity (two entity types, multiple data sources, sorting, citations) and lack of output schema, the description covers essential aspects: what data is retrieved, how it is ordered, and the inclusion of citation URIs. It handles edge cases like off-calendar fiscal years. It does not detail the exact structure of the paired data, but the context is sufficient for an agent to infer usage.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning beyond the schema by explaining how to use 'type' (company/drug) and 'values' (tickers/CIKs for company, names for drug), including examples. It also clarifies that the values are case-insensitive (implied by examples) and that max is 5. This justifies a 4.

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

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

The description uses specific verbs like 'compare' and 'rank', identifies the resource as entities (companies or drugs), and includes example queries that clarify intent. It clearly distinguishes itself from siblings by stating it replaces sequential lookups, contrasting with single-entity tools like entity_profile.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong usage guidance. It implies when to use (for comparisons) but does not explicitly exclude other sibling tools like entity_profile or validate_claim. The context is clear, but a brief mention of alternatives would push to 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?

Beyond annotations (readOnly, idempotent, non-destructive), description explains it returns top-N tools with schemas and examples, ready to call directly, adding value.

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

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

Concise, front-loaded with purpose and usage, every sentence serves a purpose with no fluff.

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

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

Fully explains what the tool returns and when to use it; output schema absence is compensated by return description.

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

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

Description adds alias information (task, q, description, search) and default/max for limit, supplementing the already comprehensive 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 finds tools by describing data or task, listing specific domains, and distinguishes from sibling tools (which are other actions, not discovery).

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' and lists when to use (browse, search, discover).

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 value by disclosing that it makes one parallel call, fans out across sources, and soft-fails on patents after May 2025, which augments 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?

Description is dense with information but front-loaded with example queries and key usage advice. Some redundancy exists (e.g., repeated mention of names not supported), but overall it is well-structured and essential sentences earn their place.

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

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

Despite no output schema, the description thoroughly lists all returned fields and sources (CIK, company name, recent filings with URIs, fundamentals, patents, news, LEI) and mentions limitations. This provides sufficient context for an agent to understand the tool's 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% with descriptions for both parameters. The description reinforces input constraints (ticker or CIK, names not supported) and hints to use resolve_entity, adding context beyond schema by clarifying that names are not supported and providing a fallback.

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

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

Description clearly states it provides a full cross-source profile of a US public company in one parallel call, listing sources and return fields. It distinguishes itself from siblings like compare_entities and resolve_entity by specifying its holistic nature and input constraints.

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

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

Explicitly advises to prefer this tool over chaining single-pack lookups for holistic views and instructs to use resolve_entity if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about sensitivity but no additional behavioral details beyond schema and annotations.

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

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

Two sentences, front-loaded with action, no wasted words. Every sentence earns its place.

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

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

For a simple 1-param tool with full schema coverage and annotations, the description covers purpose, usage scenarios, and sibling context. 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 has one parameter with clear description 'Memory key to delete' and 100% coverage. Description adds no extra parameter info beyond 'by key'.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb 'delete' and resource 'memory'. It distinguishes from sibling tools 'remember' and 'recall' by implying this is the deletion counterpart.

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 when to use: context is stale, task done, clear sensitive data. Mentions pairing with remember and recall but doesn't explicitly state when not to use alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context beyond annotations by explaining that it fetches the page, extracts content, and outputs a specific format. 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 (3-4 sentences) and front-loaded with the main purpose. It efficiently covers key points without unnecessary detail.

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

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

For a simple generation tool with annotations covering safety and idempotency, the description is adequate. It explains the process and output. Missing are error handling details and exact output format, but these are not critical given the context.

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

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

Schema description coverage is 100% with good parameter descriptions. The tool description adds context by explaining that max_links controls the number of link entries and that the output is a markdown blob. This adds value beyond the schema.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and explains the process (fetch, extract, emit) and use cases. It distinguishes from sibling tools by specifying its exact output and purpose.

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

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

The description provides explicit use cases and explains when to use the tool (getting a client's site indexed, drafting llms.txt, auditing competitors). However, it does not mention when not to use it or contrast with sibling tools like scan_competitor_ai_presence.

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

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

Annotations already provide readOnlyHint, idempotentHint, and non-destructive nature. The description adds that no authentication key is needed ('Keyless') and specifies the returned fields, which provides additional 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 very concise: two sentences that front-load the purpose and then list return values without any unnecessary words.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete. It covers what the tool does, how to call it, what to expect in return, and the prerequisite (having a system number).

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. The description adds value by explaining the source of the parameter (e.g., returned by search_objects) and gives an example format, helping the agent understand parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: retrieving the full record of a single V&A object by system number. It specifies the input format, lists return fields, and distinguishes itself from sibling tools like search_objects.

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 indicates when to use the tool (when you have a system number from search_objects) but does not explicitly mention when not to use it or list alternatives. The context is clear enough for an agent to differentiate.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, openWorldHint. Description adds value by listing specific return fields and documenting the include_inactive parameter, enhancing transparency 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?

Two focused sentences with front-loaded purpose. Every sentence earns its place; 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 low complexity, no output schema, and rich annotations, the description completely covers purpose, usage, and return fields. No gaps identified.

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

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

Schema coverage is 100% and the parameter description is already in the schema. The description mentions return fields but does not add significant meaning beyond the schema's documentation.

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 verb 'list' and resource 'subscriptions', names return fields (id, type, params, etc.), and distinguishes from siblings like 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 says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing context for when to use it, but lacks explicit when-not-to-use or direct sibling comparison.

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 behavioral traits beyond annotations: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' It also states 'The team reads digests daily and signal directly affects roadmap.' These details are not present in the annotations and add valuable context.

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

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

The description is concise (3 sentences) and well-structured. The first sentence states the purpose, the second provides usage scenarios, and the third adds important notes. No superfluous information.

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

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

Given the tool's simplicity and the absence of an output schema, the description is complete. It covers all input parameters, usage context, limitations, and behavioral notes. No information is missing for an agent to correctly invoke this tool.

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

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

The schema has 100% description coverage, but the description adds significant meaning: it elaborates on the enum values for 'type', and provides guidance for the 'message' parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb-resource pairing and distinguishes itself from sibling tools by explicitly listing use cases (bug, feature, data_gap, praise) that are not covered by other 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?

The description provides explicit when-to-use guidance: 'use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes a clear exclusion: 'don't paste the end-user's prompt.' Additionally, it mentions rate limits and non-quota nature.

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, and non-destructive. The description adds value by disclosing the data source (CF analytics-engine), absence of PII, and caching behavior (5min-1h). No contradictions.

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

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

The description is four sentences, front-loaded with key information, and every sentence adds value. No fluff or repetition.

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

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

For a simple tool with one parameter and no output schema, the description fully explains what is returned (top tools, top packs, total call volume) and caching, meeting all contextual needs.

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

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

Schema coverage is 100% with a well-described parameter. The description adds context on the trade-offs of window lengths (hot vs steady-state), which goes beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It uses specific verbs and resources, and the scope is distinct from siblings like discover_tools or 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?

Three concrete use cases are listed for when to use the tool (discovering hot data, confirming canonical choice, aligning use cases). While no explicit when-not-to-use is given, the use cases are clear and self-explanatory.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral context beyond annotations: details the algorithmic approach (monotonicity violations, partition-sum checks, Jaccard similarity threshold, placeholder filter), explains the partition_check output, and describes error conditions (e.g., partition with >20% placeholder fraction returns null). 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 detailed and informative but somewhat verbose. It front-loads the requirement and then explains modes, but includes lengthy explanations of semantic anchors, partition filters, and response structure that could be more concise. While well-organized, it does not earn every sentence; some details could be trimmed without loss.

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

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

Given the tool's complexity (two modes, multiple internal checks), the description provides a fairly complete picture. It covers input requirements, algorithm overview, output structure (opportunities array and partition_check), and special filters. No output schema is provided, so the description compensates adequately by describing return fields. A minor gap is that it doesn't list all fields of an opportunity object, but examples suffice.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by explaining that `event` is a slug or full URL and `topic` is a seed question, and elaborates on how each mode works. This goes beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with examples, but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_kalshi_spread. However, the purpose is specific and well-defined.

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 requires exactly one of `event` or `topic`, warns that calling with no args fails, and provides recommendations for when to use each mode (event for specific market, topic for cross-event scanning). It explains the advantage of cross-event mode. Missing explicit when-not-to-use scenarios, but guidance is clear and practical.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description details caching (1h KV-level), response structure (by_segment with three families), edge calculation (edge_pp_net, Kelly fractions), and diagnostics (why segments are empty). This adds significant transparency.

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

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

The description is verbose (almost 400 words) but well-structured with sections for model families, response, knobs, and diagnostics. It could be trimmed while retaining essential information, but the structure aids readability.

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

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

Given the absence of an output schema, the description thoroughly explains the response format (by_segment, fed_candidates, _diagnostics) and includes caching behavior, filter rationale, and edge calculation details. No gaps remain for agent invocation.

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

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

Schema covers all 9 parameters with descriptions. The overall description adds integration context (e.g., tradeable-edge knobs min_liquidity and max_spread_pp are explained together, and slippage_pp is discussed). Some redundancy exists, but the description adds value beyond schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs and resource, and the detailed explanation of model families distinguishes it from siblings like polymarket_arbitrage.

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

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

The description provides usage context ('what should I bet on today') and mentions filter knobs, but it does not explicitly contrast with sibling tools or state when not to use it. Some implicit guidance exists but no direct alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint, etc.) by detailing internal behavior: two modes, how matching works, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype), and what they mean. It clearly states when no valid spread exists (compatibility_warning) and explains the math behind spread calculation.

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

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

The description is relatively long but well-structured and front-loaded with the core purpose. Every sentence provides essential information (modes, response, safety fields). It avoids redundancy and is efficient for the complexity of the tool.

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

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

Given no output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spread, safety fields) and their meanings. It covers key aspects like compatibility_warning conditions, temporal alignment, and skipped types. Some details like error handling are missing, but overall it is sufficient.

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

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

Schema coverage is 100% with descriptions for each parameter, so baseline is 3. The tool description adds significant extra meaning: it explains the list of topic shortcuts, that topic is a pre-mapped shortcut, and that explicit parameters override the topic-mapped side. This enriches the schema descriptions.

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

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

The description starts with a clear, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes the tool from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison, and the verb 'compute' is implied. The two modes (topic shortcuts and explicit tickers) are clearly stated.

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 explains when to use each mode (topic shortcuts for common macros, explicit tickers for custom pairings) and provides warnings that most pre-mapped topics return compatibility_warning, setting expectations. It does not explicitly compare with sibling tools, but the usage context is well-covered.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping ('Scoped to your identifier') and the dual mode (retrieve single vs list all keys). No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the main action, and each sentence provides essential information without redundancy. 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 explains the return behavior (value or list of keys). It also covers scope and relationships with sibling tools. Adequately complete for the tool's complexity.

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

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

The input schema covers the single parameter with description. The description adds context by explaining that omitting the key lists all keys, and gives concrete examples ('the user's target ticker, an address, prior research notes'), reinforcing meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs ('retrieve', 'list') and resource ('saved values'), and distinguishes itself from sibling tools 'remember' and 'forget' by referencing them.

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

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

The description explicitly says when to use: 'Use to look up context the agent stored earlier...' and explains the behavior of omitting the key to list all keys. It also mentions pairing with 'remember' and 'forget' for saving and deleting, providing clear context. However, it does not explicitly state when not to use or 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?

Description mentions setting mark_read:true to flag events as read, implying a state change, which contradicts annotations readOnlyHint=true and idempotentHint=true. This is a serious inconsistency.

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

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

Front-loaded purpose sentence, followed by concise details on returned fields, parameter usage, and alternative access. No unnecessary words; each sentence adds value.

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

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

Covers most aspects (purpose, parameters, behavior, alternative access) but the contradiction regarding mark_read's mutability makes the description misleading and incomplete in terms of accurate behavioral disclosure.

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?

Description adds some meaning beyond the input schema (e.g., example filter 'sec_8k', explanation of mark_read effect), but the contradiction with annotations undermines reliability. With 100% schema coverage, baseline is 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 the tool pulls fired events from the subscription feed, specifying verb and resource. Distinguishes from siblings like subscribe/list_subscriptions by focusing on retrieval of recent alerts with filtering and mark_read functionality.

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

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

Provides context that the tool is for retrieving recent alerts, mentions polling suitability and an alternative REST endpoint, but does not explicitly compare to sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds rich behavioral context: fans out to multiple sources, explains fallback logic, mentions USPTO soft-fail, describes return format with changes[] grouped by source and 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?

Description is relatively long but front-loaded with example queries, then details behavior, parameters, and alternative tool. Every sentence is informative, though slight reduction could be possible 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 the complexity (multiple sources, fallback, parameter types, return format), the description covers all essential aspects. No output schema, but the description explains the structure of the return object sufficiently.

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

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

Schema coverage is 100%, baseline is 3. Description adds value beyond schema: explains type is only 'company', gives examples for since ('7d', '30d', '3m', '1y'), and clarifies value accepts ticker or CIK with examples.

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

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

The description uses specific verbs ('returns structured changes') and clearly identifies the resource ('change feed for a company in the last N days/weeks/months'). It distinguishes from sibling tool entity_profile by contrasting dynamic changes vs static profile.

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

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

Provides explicit example queries that signal when to use ('What's new with X', 'latest on Y'), and explicitly states when not to use ('Use entity_profile instead when you want the static profile'). Also explains fallback behavior for GDELT/GNews and USPTO soft-fail.

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

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

Adds context beyond annotations: scoping by identifier, persistence duration (24 hours for anonymous). No contradiction with annotations.

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

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

Concise with front-loaded purpose; three sentences are efficient and informative.

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

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

Given tool simplicity (2 params, no output schema), description covers scope, persistence, and sibling links adequately.

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

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

Schema coverage is 100%, and description reinforces key-value pair concept but does not add significant new meaning beyond schema examples.

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?

Uses specific verb 'Save data the agent will need to reuse later' and resource 'key-value pair'. Distinguishes from siblings by mentioning recall and forget.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward...' and provides context for authentication scenarios.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: each call cascades through several lookup endpoints internally and replaces 2-3 manual lookups. It also details the citation URIs returned. 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 effectively front-loaded with concrete examples and a usage directive. While it is somewhat long, every sentence adds value, and the structure (examples, then supported types with details) is clear. Minor redundancy could be trimmed but overall well-organized.

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

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

Given no output schema, the description fully explains return values for each type, including citation URIs. It also describes the internal cascading behavior. The description is complete for a tool of this complexity, covering all necessary contextual information for an AI agent to use it correctly.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning. It explains that for company, the 'value' can be ticker, CIK, or name and auto-disambiguates, and for drug it accepts brand or generic name. It also details what each type returns (e.g., ticker + CIK for company, RxCUI for drug), which the schema omits.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to an official identifier. It provides specific example queries like 'What's the ticker for…' and 'find the CIK for…', and distinguishes from siblings by emphasizing its role as the first step when an ID is needed. The verb 'resolve' combined with 'canonical/official identifier' is precise.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving clear when-to-use guidance. It also lists supported entity types (company, drug) with their return objects, implying when not to use (unsupported types). However, it does not mention alternatives or when to avoid this tool, missing some exclusion 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 read-only, idempotent, non-destructive. Description adds behavioral details: each entity probed with ai_visibility_check, ranked by score, first entry treated as subject. No contradictions.

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

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

Three sentences: first states purpose, second details behavior, third provides usage example. No filler, front-loaded, every sentence earns its place.

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

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

Given no output schema, description adequately explains return format (ranked list with score, confidence, signal density). Covers constraints (2-8 entities) and parameter roles. Lacks error handling details but acceptable.

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

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

Schema description coverage is 100%; description adds context like probing with another tool and treating first entry as subject, but does not significantly enhance meaning beyond schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities, uses a specific verb 'Compare' and resource 'AI presence', and distinguishes from siblings like ai_visibility_check by emphasizing side-by-side 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 provides a use case ('competitive AI-marketing audits') with an example question. Implies when to use over ai_visibility_check but lacks explicit when-not-to-use or alternative references.

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

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

Annotations already indicate safe, idempotent, open-world behavior. Description adds valuable details: partial failure handling, latency on first measurement, and that sources_failed reports timeouts. 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?

Front-loaded with purpose, then details. Some verbosity in listing fields, but well-structured and every sentence adds value.

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

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

Given no output schema, description lists all return fields, explains composite nature, and covers edge cases like partial failures and ecosystem limitations.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds context about scoped packages and default version behavior, going beyond schema.

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

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

Clearly states it's a composite check for npm package evaluation, specifying the two data sources and return block. Distinguishes from siblings by focus and ecosystem 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?

Explicitly says when to use (questions about safety/popularity/size/cost) and hints at alternatives for other ecosystems via deps.dev:version.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by noting the tool is keyless, the scale of the collection (1M+ items), and the specific return fields, providing transparency beyond annotations.

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

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

The description is concise, with every sentence providing essential information. It is front-loaded with the primary action and includes return fields and usage guidance without extraneous content.

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

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

Given the richness of the schema annotations and the absence of an output schema, the description adequately covers the tool's purpose, return values, and usage context. It could mention pagination or filtering behavior, but these are covered in the 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 clear parameter descriptions. The description does not add additional semantic detail about the parameters beyond what is already in the schema, so the 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 that the tool searches the V&A Museum's collection by keyword, specifies the types of items and the fields returned, and mentions using the id with get_object for full details. It distinguishes this search tool from the sibling tool get_object.

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 guidance on when to use this tool: for keyword searches across 1M+ items, and suggests using get_object for full details. It also notes that the tool is keyless, implying no authentication needed. However, it does not explicitly state when not to use it.

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

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

Discloses internal mechanics: 'BGE-base-en embeddings + cosine over 500-char overlapping windows', input cap '200K chars (longer inputs are truncated and flagged)', and that results include character offsets and similarity scores. This adds value beyond the readOnlyHint, openWorldHint, and idempotentHint annotations.

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

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

The description is relatively long but every sentence adds value. It front-loads the main purpose and usage, then provides technical details and pairing. Could be slightly shorter but not wasteful.

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 clearly explains return values (passages with offsets and scores). It covers truncation behavior, pairing with ask_pipeworx_grounded, and technical details. This is complete for an agent to use the tool effectively.

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: for 'text' it reminds to 'Pass the text you already pulled' and mentions max length, for 'query' provides examples, for 'limit' gives default and range (1-20, default 5). This adds practical detail beyond schema descriptions.

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

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

The description starts with 'Semantic search INSIDE a fetched record' which clearly states the verb and resource. It specifies the inputs (text query) and outputs (top-N passages with offsets and scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded, making it unique among the sibling tools.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Description states 'Creates a new subscription id' implying each call creates a new subscription, which contradicts the idempotentHint=true annotation (calling multiple times should not create duplicates). This is an annotation 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?

Description is concise (6 sentences), well-structured with purpose first, then type details, return value, requirements, and delivery options. 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 no output schema, description explains the return (subscription id) and covers all parameters, prerequisites, and limitations. Missing error handling or rate limits, but adequate for the tool's complexity.

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

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

Schema covers 100% of parameters, but description adds valuable context: explains the type enum, param structure with examples, delivery channels, and limits (SMS cap), going beyond the schema.

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

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

The description clearly states the tool creates a monitoring subscription to a live-data event stream, specifies the supported type (sec_8k), and details the triggers and delivery channels, making it distinct from sibling tools like list_subscriptions or unsubscribe.

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

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

The description explains when to use (creating a subscription) and prerequisites (Pipeworx OAuth account), but does not explicitly state when not to use or mention alternatives, though the context from sibling tools provides differentiation.

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

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

Adds valuable behavioral details beyond annotations: ownership enforcement, soft delete, and link to recent_alerts. No contradiction.

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

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

Two sentences, front-loaded with main action, no unnecessary words.

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

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

For a simple one-parameter tool with no output schema, description sufficiently covers behavior, ownership, and side effects.

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

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

Schema coverage is 100% and already describes the id parameter. Description adds no new parameter info beyond restating 'by id'.

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

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

Clear verb 'Cancel', resource 'subscription', and scope 'by id'. Distinguishes from siblings like subscribe and list_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?

Explains ownership enforcement ('only cancel your own subscriptions') and effect ('deactivated, not deleted, historical events stay'). Lacks explicit when-not-to-use or alternative comparison, but sufficient.

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 false, and openWorldHint. The description adds beyond that: details the data sources (SEC EDGAR + XBRL), return values (verdicts, structured form, citation, delta), and that it replaces multiple sequential calls. No contradiction found.

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 trigger phrases upfront, then purpose, scope, and return details. It is slightly verbose but every sentence adds value; no redundant content.

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

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

Given the tool's complexity (single param, no output schema, many siblings), the description fully covers purpose, usage, behavioral traits, and return values. It explains what the tool does, when to use it, and what it returns, leaving no critical gaps.

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

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

Schema coverage is 100% with a single parameter 'claim' described as a natural-language string. The description adds specific examples and clarifies the expected format, which is helpful 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 verifies factual claims against authoritative sources, provides trigger phrases ('Is it true that…', 'fact check', etc.), and specifies scope (company-financial claims). It distinguishes itself from sibling tools like 'ask_pipeworx_grounded' by being specialized for claim verification rather than general Q&A.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives concrete examples. However, it does not explicitly state when NOT to use this tool or mention alternatives from the sibling list.

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