randomuser

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true. The description adds value by explaining the default free model, BYO key for Anthropic, and the per-model return structure. No contradictions.

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

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

The description is 4 sentences, front-loaded with the purpose, no wasted words. Every sentence adds essential information (default model, cost model, return format, use cases).

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

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

Without an output schema, the description details the return fields (score, confidence, signals, raw_response, combined view). It covers input params, costs, and use cases. It could mention error handling or rate limits, but for a probe tool, it is sufficiently 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 the description adds crucial context: the default model, that _apiKey is only needed for Anthropic, and that context helps disambiguate. It gives examples for entity and clarifies that models is optional, exceeding the schema's explanations.

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 'probe[s] one or more LLMs for what they know... and score[s] visibility (0-100) per model'. It specifies the action, resource, and output, distinguishing it from siblings like 'scan_competitor_ai_presence' by focusing on multi-model scoring.

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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It implicitly tells when to use but does not explicitly state when not to use or name alternatives, though the sibling 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool's approach ('Pipeworx picks the right tool, fills the arguments') and scope ('best available data source'), but doesn't disclose important behavioral traits like rate limits, authentication requirements, response formats, or error handling for this natural language query system.

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

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

The description is efficiently structured with a clear purpose statement upfront, followed by explanation of the tool's approach, and concrete examples. Every sentence adds value without redundancy, making it easy to understand the tool's unique value proposition quickly.

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 natural language query tool with no annotations and no output schema, the description provides adequate basic information but lacks details about response formats, error conditions, or limitations. The examples help, but more context about what types of questions work best or system constraints would improve completeness.

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

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

With 100% schema description coverage, the schema already documents the single 'question' parameter. The description adds meaningful context by specifying it should be 'in plain English' or 'natural language' and provides concrete examples that illustrate appropriate question formats, which goes beyond the schema's basic 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?

The description clearly states the tool's purpose with specific verbs ('ask a question', 'get an answer') and distinguishes it from siblings by emphasizing its natural language interface that eliminates the need to browse tools or learn schemas. It provides concrete examples that illustrate its unique capability compared to other tools on the server.

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

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

The description provides clear context about when to use this tool ('ask a question in plain English', 'no need to browse tools or learn schemas') and gives helpful examples. However, it doesn't explicitly state when NOT to use it or name specific alternative tools from the sibling list for different types of 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=true and openWorldHint=true. Description adds significant behavioral detail: resolves market, classifies bet type, fans out to relevant packs, returns comparison. No contradictions. Exceeds annotation-only 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?

Single paragraph, front-loaded with core purpose. All sentences earn their place, though slightly verbose (e.g., 'This is the core demo product...' could be trimmed). Efficient overall for the information conveyed.

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

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

Covers tool purpose, acceptable inputs, internal process, outputs, and use cases. No output schema exists, but return type is adequately described. Siblings exist but the description doesn't need to compare with all. Minor gap: no mention of error handling or edge cases.

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?

100% schema coverage with descriptions for both parameters. Description restates market parameter format (slug/URL/text) but adds no new meaning. Depth parameter is fully explained in schema with enum values and default. Description offers no additional semantics 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 uses specific verb+resource ('Research a Polymarket bet by pulling data') and clearly states the outputs ('evidence packet plus market-vs-model comparison'). It distinguishes from sibling tools by focusing exclusively on Polymarket bets, unlike ask_pipeworx or compare_entities which are more general.

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 use cases ('should I bet on X?', 'what does the data say...', 'is there edge...'). Notes that agents using this convert better, but lacks explicit when-not-to-use or alternatives. Still clear context for invocation.

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

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

The description discloses that it returns paired data and pipeworx:// URIs, and for each type it lists specific financial or clinical metrics. With no annotations provided, the description carries full burden; it does not explicitly state that the tool is read-only or safe (though 'compare' implies non-destructive). Adequate but lacking explicit behavioral guarantees.

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

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

The description is concise (4 sentences), front-loaded with the core purpose, and each sentence adds distinct value (scope, type-specific details, output format, efficiency claim). No redundant or 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 moderate complexity (two types, multiple data points), the description explains what data is returned and provides type-specific details. The schema covers all parameters. It lacks information on error handling, prerequisites, or rate limits, but with no output schema, the description covers the essential aspects for usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant detail: for 'type' it expands on which metrics are returned per entity type, and for 'values' it gives concrete examples (tickers vs. drug names). This goes beyond the schema's minimal 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 compares 2–5 entities in one call, specifies two entity types ('company' and 'drug') and the data returned for each, and explicitly mentions it replaces 8–15 sequential agent calls, effectively distinguishing it from 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?

The description provides clear context on when to use the tool (for side-by-side comparison of companies or drugs) and highlights efficiency gains by replacing many sequential calls. However, it does not explicitly state when not to use it or name alternative tools, but the purpose is still 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's a search operation (implying read-only, non-destructive), returns relevant tools with names and descriptions, and emphasizes it should be called first in specific contexts. However, it lacks details on rate limits, error handling, or authentication needs.

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, followed by usage guidance, in just two efficient sentences. Every sentence earns its place by providing critical information without redundancy, making it highly concise and well-structured.

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

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

Given the tool's moderate complexity (search functionality with 2 parameters), no annotations, and no output schema, the description is mostly complete. It covers purpose, usage context, and behavioral intent, but could improve by mentioning output format details or error cases, which are not fully addressed.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain query formatting nuances or limit implications). Baseline 3 is appropriate as the schema handles the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('Search the Pipeworx tool catalog') and resources ('tool catalog'), and explicitly distinguishes it from siblings by emphasizing its role in finding tools among 500+ options. It goes beyond a tautology by explaining the search functionality and return format.

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

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

The description provides explicit guidance on when to use this tool ('Call this FIRST when you have 500+ tools available and need to find the right ones for your task'), including a clear condition (500+ tools) and alternative context (vs. not using it with fewer tools). It directly addresses when to prioritize this tool over others.

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

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

With no annotations provided, the description fully discloses behaviors: returns pipeworx:// citation URIs, bundles multiple data sources, and mentions current limitations (only 'company' type, value must be ticker or CIK, name unsupported, federal contracts excluded for speed). This exceeds the transparency burden.

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 compact yet comprehensive, with front-loaded purpose, enumerated data sources, mention of URIs, replacement value, and a clear exclusion. Every sentence is informative, and there is no redundancy or filler.

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 (multi-source profile) and no output schema, the description adequately explains what is returned (citation URIs) and lists data types. It covers limitations and alternatives well. A minor gap: it does not specify response format or pagination, but for a profile tool this 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% (2 parameters fully described), but the description adds critical context: explains that type only supports 'company' (with future plans), value must be ticker or CIK (not name), and directs to resolve_entity for names. This goes well beyond the schema's 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 provides a comprehensive entity profile across multiple Pipeworx packs in one call, listing specific data sources (SEC filings, XBRL, patents, news, LEI) and positioning it as a replacement for 10-15 sequential calls, which distinguishes it from siblings like resolve_entity.

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

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

The description explicitly advises against using this tool for federal contracts, directing the agent to usa_recipient_profile instead, and notes that names are not supported—use resolve_entity first. 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a deletion operation, implying mutation/destructive behavior, but doesn't address permissions needed, whether deletion is permanent or reversible, error conditions, or what happens on success. For a destructive tool with zero annotation coverage, this is insufficient.

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

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

The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple tool and front-loads the essential information (delete operation).

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 destructive tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'stored memory' means in this context, what happens after deletion (e.g., confirmation, error handling), or how this relates to sibling tools. The lack of behavioral context makes it inadequate for safe agent use.

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

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

Schema description coverage is 100%, with the single parameter 'key' documented as 'Memory key to delete'. The description adds minimal value by restating 'by key' but doesn't provide additional context like key format, examples, or constraints beyond what the schema already covers.

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 ('Delete') and resource ('a stored memory by key'), providing specific verb+resource pairing. However, it doesn't differentiate from sibling tools like 'recall' or 'remember', which appear related to memory operations, so it misses full sibling differentiation.

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 no guidance on when to use this tool versus alternatives like 'recall' or 'remember', nor does it mention any prerequisites or exclusions. It simply states what the tool does without context for selection.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool generates random user profiles but doesn't describe what 'random' entails (e.g., data fields included, realism constraints), whether it requires authentication, rate limits, or what the output format looks like. For a generation tool with zero annotation coverage, this leaves significant behavioral gaps.

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

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

The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's appropriately sized for a simple tool and front-loads the core purpose immediately.

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 generation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what constitutes a 'user profile' (what fields are generated), the randomness characteristics, or the return format. The agent would be left guessing about the tool's output and behavioral details despite the simple input schema.

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

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

The description mentions filtering by gender, which aligns with the 'gender' parameter in the schema. However, with 100% schema description coverage, the schema already fully documents both parameters (count with default/max values, gender with allowed values). The description adds no additional parameter semantics beyond what the schema provides, meeting the baseline for high schema coverage.

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

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

The description clearly states the verb ('generate') and resource ('random user profiles') with a specific filter condition ('filtered to a specific gender'), making the purpose unambiguous. However, it doesn't explicitly differentiate from the sibling tool 'generate_users' - it implies filtering by gender but doesn't clarify if the sibling tool lacks this filtering capability or offers different 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?

The description provides no guidance on when to use this tool versus the sibling 'generate_users' tool, nor does it mention any prerequisites, exclusions, or alternative scenarios. The agent must infer usage from the description alone without explicit comparative 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown. This aligns with annotations and provides process details 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 two sentences: the first front-loads the action and purpose, the second lists specific use cases. Every word earns its place; no redundancy. It is concise and well-structured.

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

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

Given the tool's simplicity (2 params, no output schema), annotations cover safety and side effects. The description explains the process and output format adequately. Agents have enough information to invoke correctly without additional context.

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

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

Schema coverage is 100%, with clear descriptions for 'url' and 'max_links'. The description does not add extra semantic value beyond stating the tool fetches and extracts, which is implied. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL to aid AI crawlers. The verb 'generate' and resource 'llms.txt' are specific, and the context of AI indexing is well-defined. It distinguishes itself from sibling tools like 'ai_visibility_check' by focusing on file generation rather than checking visibility.

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 outlines use cases: getting a client's site indexed, drafting for own project, or auditing competitor sites. While it doesn't say when not to use or mention alternatives, the specificity of use cases provides clear context for an 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it describes what the tool generates (user profiles with specific attributes), it doesn't disclose important behavioral aspects like whether this is a read-only operation, whether it makes external API calls, what format the photos are returned in, whether there are rate limits, or what happens when invalid nationality codes are provided. The description is functional but lacks operational 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 extremely concise and well-structured in a single sentence that efficiently communicates the core functionality and optional feature. Every word earns its place - it specifies what's generated, the attributes included, and the filtering capability without any redundant information or unnecessary elaboration.

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

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

For a tool with 2 parameters, 100% schema coverage, but no annotations and no output schema, the description provides adequate but minimal context. It covers what the tool does and one optional feature, but doesn't address behavioral aspects, output format, or differentiation from the sibling tool. Given the lack of annotations and output schema, more completeness would be beneficial but the description meets minimum viable standards.

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 description mentions the nationality filtering parameter, which adds some context beyond the schema. However, with 100% schema description coverage where both parameters are well-documented in the schema (including default values, constraints, and format examples), the description doesn't provide significant additional parameter semantics. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's function: generating random user profiles with specific attributes (realistic names, addresses, emails, photos) and optional nationality filtering. It uses specific verbs ('generate', 'filter') and identifies the resource ('user profiles'). However, it doesn't explicitly differentiate from the sibling tool 'generate_by_gender' - both generate users but with different filtering capabilities.

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

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

The description provides some usage context by mentioning the optional nationality filtering capability, which implies when this filtering feature would be useful. However, it doesn't explicitly state when to use this tool versus the sibling 'generate_by_gender' tool, nor does it provide any exclusion criteria or prerequisites for usage.

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

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

Description discloses behavioral traits beyond the schema: rate limiting ('5 messages per identifier per day') and a usage policy ('Free'). It also provides a privacy instruction (not to include end-user prompts). Since no annotations are present, the description carries the full burden and does so effectively.

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 front-loaded with the main purpose. Every sentence adds value: purpose, usage guidance, and behavioral constraints. 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 tool's simplicity (3 parameters, no output schema) and the lack of annotations, the description covers all essential behavioral aspects (rate limits, privacy) and provides sufficient context for an agent to use the tool correctly. It could optionally mention what happens after sending (e.g., acknowledgment), but that is not critical.

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 the schema documents all parameters with descriptions. The description adds some extra guidance for the 'message' parameter (be specific, 1-2 sentences) and reinforces the purpose of 'type' and 'context', but does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

Description clearly states 'Send feedback to the Pipeworx team' and enumerates specific use cases (bug reports, feature requests, missing data, praise). This provides a specific verb-resource pair and differentiates the tool from sibling tools that serve other purposes.

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

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

Description gives clear context for when to use (feedback) and includes important guidance on what to include ('describe what you tried in terms of Pipeworx tools/data') and what to avoid ('do not include the end-user's prompt verbatim'). It also mentions rate limiting as a constraint. However, it does not explicitly state when not to use this tool or point to alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context: self-aggregating signal, CF analytics-engine, no PII, and caching (5min-1h). No contradictions.

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

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

The description is concise, well-structured with bullet points for use cases, and front-loaded with the main purpose. 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 simplicity (one parameter, no output schema), the description fully covers what is returned, window options, usage guidance, data source, and caching. 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% with a single parameter 'window' that has a detailed description. The description reiterates the window options and adds caching info, but does not significantly add meaning beyond the schema.

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

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

The description clearly states it returns top tools, top packs, and call volume over a recent window. It uses a specific verb ('returns') and resource, and distinguishes itself from siblings like 'discover_tools'.

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

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

The description provides explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment) and explains when to use shorter vs longer windows. It lacks explicit when-not-to-use or alternatives, 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 and non-destructive behavior. The description adds significant behavioral context: it walks markets, searches across events, groups them, checks monotonicity, and returns ranked opportunities with reasoning. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the purpose and then explains the two modes. Every sentence adds value, though it could be slightly more concise by separating the modes into bullet points or shorter sentences.

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 with two modes and no output schema, the description is comprehensive: it explains the workflow, provides examples, and notes what the output contains (ranked opportunities with direction and reasoning). It is sufficient for an AI agent to use 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% with descriptions for both parameters. The description enhances these by explaining the two modes and providing examples (e.g., 'when-will-bitcoin-hit-150k' for event, 'Strait of Hormuz traffic returns to normal' for topic), adding 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 finds arbitrage opportunities on Polymarket by checking monotonicity violations. It uses a specific verb 'find' and resource 'arbitrage opportunities on Polymarket', and distinguishes itself from siblings like 'bet_research' and 'polymarket_edges' by focusing on arbitrage across related markets.

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 outlines two modes ('event' for single event slug, 'topic' for cross-event) and provides guidance on when to use each, including an example where single-event mode misses the May≤June rule and cross-event mode catches it. This helps the AI agent select the correct mode.

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?

Annotation readOnlyHint=true and destructiveHint=false indicate no side effects, and description adds rich behavioral details: V1 covers crypto-price bets, uses lognormal model from FRED and live coinpaprika price, scans top markets, groups by asset, fetches price history once, computes model probability per market, ranks by |edge|, and returns top N with suggested trade direction. 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?

Description is well-structured with the main action first, followed by model details, algorithm steps, and output. It packs substantial information efficiently without unnecessary words, though it could be slightly shortened.

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 of the tool (multiple markets, model, ranking) and the absence of an output schema, the description thoroughly explains the data sources, algorithm, and output format (top N ranked by edge magnitude with suggested trade direction). It is fully adequate 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 description coverage is 100%, so baseline is 3. The description restates the parameter descriptions found in the schema (limit, window, min_edge_pp) but does not add new semantic information beyond what is already documented in the input 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 verb (scan, return), resource (high-volume Polymarket markets), and specific function (find where Pipeworx data disagrees with market price, rank by edge). It distinguishes from siblings like polymarket_arbitrage by specifying the edge-detection focus and data 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?

Description explicitly states the use case: 'Built for the "what should I bet on today" question — agents/users discover opportunities without paging through hundreds.' It implies when to use it but does not provide explicit when-not-to-use or alternatives; however, 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 declare readOnlyHint, idempotentHint, destructiveHint=false, so agent knows it's safe and idempotent. Description adds value by detailing behavior: two modes, output format (leg prices, spread), and that it's an arb signal. No contradictions.

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

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

Description is detailed but slightly verbose. However, it is well-structured with sections for modes and output. Every sentence adds value. Could be more concise but not excessive.

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 clearly states return values: leg-by-leg prices (0-1) and spread in percentage points. For a read-only analysis tool with good annotations, this is sufficient. 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% with individual parameter descriptions. Description adds semantics by explaining that topic maps to matching events on both venues, and explicit tickers override the mapped side. This adds context beyond schema descriptions.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb 'compute' and resource 'spread'. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue arb.

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

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

Description explains two modes (topic shortcuts for common events, explicit tickers for custom pairings), providing clear guidance on when to use each. Does not explicitly state when not to use or compare to alternatives, but adequately covers 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the dual functionality (retrieve by key or list all) and mentions persistence across sessions, which is valuable context. However, it doesn't cover error handling, performance characteristics, or what happens when a non-existent key is provided.

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 perfectly concise with two sentences that each earn their place. The first sentence states the core functionality, and the second provides usage context. There's zero redundancy or 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 single-parameter tool with good schema coverage but no output schema or annotations, the description provides adequate context about what the tool does and how to use it. The main gap is the lack of information about return values or error conditions, which would be helpful given the absence of an output schema.

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

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

The description adds meaningful context beyond the 100% schema coverage by explaining the semantic behavior: 'omit key to list all keys' clarifies the optional parameter's effect. While the schema documents the parameter type, the description provides the operational logic that makes the tool's dual functionality clear.

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 with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'). It distinguishes from siblings like 'remember' (store) and 'forget' (delete) by focusing on retrieval operations.

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

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

The description provides explicit guidance on when to use this tool: 'to retrieve context you saved earlier in the session or in previous sessions.' It also specifies when to omit the key parameter to list all memories, giving clear operational instructions.

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?

With no annotations, the description fully discloses key behaviors: it fans out to multiple sources (SEC EDGAR, GDELT, USPTO) in parallel for company type, accepts ISO dates or relative strings, and returns structured changes, a count, and URIs. This gives the agent a detailed understanding of the tool's operation and output.

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 only two sentences but packs significant detail: purpose, behavior, parameter formats, and return structure. Every sentence is essential and front-loaded, with no extraneous information.

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

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

Given the complexity (parallel fan-out, multiple sources) and lack of output schema or annotations, the description covers the core functionality well. It could be slightly more detailed on the exact shape of 'structured changes' or limits, but it is largely sufficient for an agent to understand and 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%, so the baseline is 3. The description adds meaningful guidance beyond the schema: for type it notes 'Only "company" supported today,' for since it recommends 'Use "30d" or "1m" for typical monitoring,' and for value it clarifies 'Ticker or zero-padded CIK.' This adds practical usage 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: 'What's new about an entity since a given point in time.' It specifies the verb 'brief me' and resource 'changes'. It distinguishes from siblings by explicitly saying 'Use for "brief me on what happened with X" or change-monitoring workflows,' which contrasts with entity_profile and compare_entities.

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

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

The description provides explicit context for when to use: 'Use for "brief me on what happened with X" or change-monitoring workflows.' It does not explicitly state when not to use or name alternatives, but the given context is clear and reasonably helps an agent 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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool stores data in session memory, distinguishes between authenticated users (persistent memory) and anonymous sessions (24-hour duration), and implies it's a write operation. It does not cover aspects like error handling or rate limits, but provides sufficient context for basic use.

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

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

The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose, usage, and behavioral details without wasted words. Each sentence adds value: the first defines the tool's function, and the second clarifies persistence rules, making it highly concise and well-structured.

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

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

Given the tool's moderate complexity (a write operation with no output schema and no annotations), the description is mostly complete. It covers purpose, usage, and key behavioral aspects like persistence differences. However, it lacks details on error cases or return values, which could be helpful for an agent, but is adequate for the context provided.

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, with clear documentation for both required parameters ('key' and 'value'). The description adds minimal semantic context by mentioning examples of what to store ('findings, addresses, preferences, notes'), but does not provide significant additional meaning beyond the schema. This meets the baseline of 3 when schema coverage is high.

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 with a specific verb ('Store') and resource ('key-value pair in your session memory'), distinguishing it from sibling tools like 'forget' (delete) and 'recall' (retrieve). It explicitly mentions what can be stored ('intermediate findings, user preferences, or context across tool calls'), making the purpose unambiguous.

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

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

The description provides clear context for when to use this tool ('save intermediate findings, user preferences, or context across tool calls'), which helps differentiate it from alternatives like 'recall' for retrieval. However, it does not explicitly state when not to use it or name specific sibling tools as alternatives, keeping it at a 4 rather than 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool performs a resolution (likely a read), returns specific fields (ticker, CIK, name, URIs), and replaces multiple lookups. It does not mention authentication or rate limits, but the behavior is well-explained.

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 succinct sentences, front-loaded with the primary action, and zero redundancy. Every sentence adds essential information.

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

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

Given no output schema, the description adequately explains the return values. The tool is simple (2 params, no nested objects), and the description covers inputs, outputs, and usage context. Minor omission: no mention of error handling.

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 both parameters are described. The description adds that 'type' is limited to 'company' in v1 and that 'value' accepts three specific formats, going beyond the schema's generic description.

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

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

The description clearly states the tool resolves entities to canonical IDs, specifies the supported type (company) and input formats (ticker, CIK, name), and distinguishes it from multiple lookup calls. This is specific and action-oriented.

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 the tool should be used when you need canonical IDs from various input identifiers, and highlights efficiency by replacing 2-3 lookup calls. It does not provide explicit when-not-to-use guidance, 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?

Description aligns with annotations (readOnly, idempotent, openWorld). Adds specifics: probes each entity, ranks by score, surfaces most/least recognized, returns ranked list with score, confidence, signal density. No contradictions.

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

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

Two well-structured sentences: summary, process, use case, output description. No wasted words, front-loaded with purpose. Efficiently 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 no output schema, description adequately describes output format (ranked list with score, confidence, signal density). Explains entity count range (2-8) and scope. Covers all key aspects for an agent to use correctly.

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

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

Parameter schema coverage is 100%. Description adds value beyond schema: explains entities (first is subject), models (supported values, default workers-ai), and condition for _apiKey. This clarifies behavior beyond schema listing.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking. It distinguishes itself from sibling like ai_visibility_check by emphasizing the comparative, rank-based output. Example use case further clarifies 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?

Provides clear context for competitive AI-marketing audits with a concrete example. While it doesn't explicitly state when not to use, it implies single-entity checks should use ai_visibility_check. No alternative or exclusion list, but adequate for most use cases.

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?

With no annotations provided, the description carries the full burden. It discloses the return format (verdict, structured form, actual value with citation, percent delta) and mentions the tool replaces multiple sequential calls. However, it does not address edge cases (e.g., unsupported claim types), error behavior, or performance characteristics.

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

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

The description is concise and well-structured: two sentences and a bullet list of return elements. It front-loads the key purpose and then details. Every sentence is informative and adds value without redundancy.

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

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

Given the tool's complexity and the lack of an output schema, the description provides a solid overview of inputs, outputs, and domain. It does not mention rate limits, authentication, or conditions for inconclusive results. Nonetheless, it is sufficiently complete for initial understanding.

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

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

The input schema has one parameter 'claim' with a description. The tool description adds substantial value by providing examples of valid claims and explaining the expected format. Since schema description coverage is 100%, the baseline is 3; the extra context and examples justify a 4.

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

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

The description clearly states the tool's function: fact-checking natural-language claims against authoritative sources. It specifies the domain (company-financial claims for public US companies) and provides concrete examples. It also contrasts with a multi-step alternative, making its unique purpose evident.

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 defines the supported scope (v1: company-financial claims via SEC EDGAR + XBRL), which implies when to use it and when not to. However, it does not explicitly list alternative tools or exclusions, leaving some room for ambiguity. The sibling tools include 'ask_pipeworx', which might serve as a general alternative for out-of-scope claims.

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