Magic 8 Ball

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

Annotations already provide readOnlyHint and idempotentHint. The description adds value by disclosing the default model, cost implications of using Anthropic, and the return format (per-model fields plus combined view).

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-loading the core action and output. Every sentence 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?

Despite no output schema, the description covers return structure (per-model score, confidence, signals, raw_response + combined view) and use cases. Minor missing details like pagination or error handling are acceptable given the tool's scope.

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

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

Schema coverage is 100%, but the description enriches each parameter with examples (e.g., 'Pipeworx' for entity), supported model values, and explanation of _apiKey's role, surpassing baseline 3.

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

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

The description clearly states the tool probes LLMs for knowledge about a topic and scores visibility (0-100). It uses specific verbs and resources, making the purpose distinct from siblings like ask_pipeworx or 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 lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs. BYO models, but does not explicitly state when not to use or mention alternatives.

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

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

The description discloses key behavioral traits: it automatically selects the best tool and fills arguments. It does not mention limitations or error handling, but given no annotations, it provides sufficient transparency for a natural language query tool.

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

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

The description is concise (3 sentences), front-loaded with the core action, and each sentence adds value: purpose, behavior, and examples.

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 a single required parameter, no output schema, and simple tool purpose, the description is complete enough. It explains what the tool does and how to use it. A 5 might require mentioning what happens if no data source is found.

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 coverage is 100%, so the description adds value by explaining the purpose and usage of the 'question' parameter with examples, beyond the schema's generic 'Your question or request in natural language'.

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 takes a plain English question and returns an answer from the best available data source. It distinguishes itself from sibling tools like 'discover_tools' or 'magic_8_ball_ask' by emphasizing automatic tool selection and argument filling.

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 tells when to use this tool: when you need an answer from data sources without browsing tools or learning schemas. It provides examples of appropriate questions, implicitly guiding against using other tools for simple 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?

Beyond annotations (readOnlyHint, openWorldHint, destructiveHint), the description details the internal process: resolves market, classifies bet, fans out to appropriate packs, returns evidence packet and market-vs-model comparison. This adds significant behavioral context.

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

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

The description is well-structured with a clear first sentence stating purpose, followed by logical details. It is slightly verbose but informative; could be trimmed for brevity 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 tool's complexity (2 params, no output schema), the description covers all essential aspects: inputs, process, output, and use cases. It mentions the return type (evidence packet and comparison) 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?

The description enriches both parameters: for 'market', it explains accepted formats (slug, URL, question text); for 'depth', it clarifies the difference between 'quick' and 'thorough' and notes the default. This adds value beyond the schema definitions.

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

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

The description clearly states the tool researches Polymarket bets by pulling relevant Pipeworx data in one call. It specifies the verb 'research', the resource 'Polymarket bet', and outlines the input types (slug, URL, question text). This differentiation from siblings like ask_pipeworx is explicit.

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

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

The description provides explicit use cases: 'should I bet on X?', 'what does the data say?', 'is there edge?'. It also notes this is the core demo product and implies it's preferable to general tools. 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?

With no annotations, the description carries full burden. It discloses data sources (SEC EDGAR, FDA) and return format (paired data + URIs), but lacks details on read-only nature, rate limits, or error behavior. Adequate but not thorough.

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: three sentences, front-loaded with the core purpose, and every sentence adds essential information without redundancy. Ideal structure.

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

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

Given the tool has only two parameters and no output schema, the description covers entity types, return data, and benefits. Missing details like whether results are paginated or include metadata, but overall sufficient for a straightforward comparison 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%, meaning each parameter is documented. The description adds value by explaining how 'values' differ per type (tickers/CIKs for companies, drug names) with examples, going beyond the schema's basic description.

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

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

The description clearly states the tool compares 2-5 entities side by side, specifies two entity types ('company' and 'drug') with distinct data fields, and highlights that it replaces sequential calls. This gives a specific verb and resource, effectively differentiating from siblings.

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

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

The description implies usage by stating it replaces 8-15 sequential agent calls, indicating efficiency for batch comparisons. However, it does not explicitly state when not to use or compare to siblings like 'resolve_entity' or 'ask_pipeworx', leaving room for ambiguity.

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

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

No annotations are provided, so the description must carry the full burden. It states that the tool returns 'the most relevant tools with names and descriptions,' which gives a high-level behavior. However, it does not disclose potential side effects (none expected), rate limits, or authentication requirements. Since it's a search tool, the behavioral transparency is adequate but not exceptional.

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, consisting of three short sentences. The first sentence states the purpose, the second describes the output, and the third provides usage guidance. Every sentence earns its place with no waste.

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

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

Given that the tool has only two simple parameters with full schema coverage, no output schema, and is a straightforward search tool, the description is largely complete. It tells the agent what it does, when to use it, and what it returns. A slight improvement would be to mention the return format (e.g., list of tool names and descriptions) more explicitly, but it's sufficient for effective use.

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

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

Schema description coverage is 100%, so both parameters ('query' and 'limit') are already described in the schema. The description does not add any additional meaning beyond the schema; it only mentions the query parameter implicitly ('describing what you need'). Thus, it does not compensate beyond the baseline score of 3.

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

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

The description clearly states the tool's purpose: to search a tool catalog by describing a need. It specifies the action ('Search'), the resource ('Pipeworx tool catalog'), and the method ('by describing what you need'). It also distinguishes itself by advising to call it first when many tools are available, differentiating from sibling tools like ask_pipeworx or magic_8_ball_ask.

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 tells the agent when to use this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This is clear usage guidance with a conditional scenario, making it highly actionable for the AI.

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 provided, so description carries full burden. It clearly states the tool bundles multiple data sources, returns citation URIs, and replaces many calls. Could mention response format or rate limits, but overall transparent.

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, front-loaded with purpose, then lists data sources, return type, and usage guidance. Every sentence provides value; no redundant information.

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

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

Given no output schema, description explains return values (citation URIs). Complexity is moderate; covers main behavioral traits and use cases. Could mention error handling or pagination if any, but 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?

Input schema has descriptions for both parameters: type enum notes only company supported, value includes examples and name resolution caveat. Description adds context about returned data per type, adding value beyond schema.

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

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

Description explicitly states it returns a full profile across multiple packs for an entity, with specific examples for company type. It clearly distinguishes itself from sibling tools like resolve_entity 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?

Provides explicit guidance: use for comprehensive profile, direct to usa_recipient_profile for federal contracts, and mentions resolve_entity for name resolution. Clearly states when not to use.

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

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

With no annotations provided, the description carries the full burden. It correctly states that the tool deletes a memory, implying a destructive action, but does not disclose whether deletion is permanent, if confirmation is required, or any side effects. The description is accurate but minimal.

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, short sentence that is front-loaded with the verb. Every word is necessary, and there is no extraneous information.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description is minimally complete. It explains what the tool does and the parameter's role. However, it lacks details about the operation's effect (e.g., whether it's irreversible) and does not compare with sibling tools like recall or remember.

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

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

The schema already has 100% coverage for the single parameter 'key' with a clear description. The tool description adds 'by key' which confirms the parameter's role but does not provide additional semantic detail 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 'Delete', the resource 'stored memory', and the means 'by key'. It directly and precisely defines what the tool does without ambiguity.

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

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

The description implicitly indicates when to use this tool (when you want to delete a memory by key), but it does not provide guidance on when not to use it or mention alternatives like recall or remember for other operations.

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 the tool fetches the page and extracts title, description, and key links. This goes beyond the readOnlyHint annotation by explaining the specific operations. It does not mention error handling or rate limits, but annotations already convey safety.

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

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

The description is concise with no wasted words. It front-loads the purpose and covers key aspects in three sentences. 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?

For a tool with no output schema, the description clearly describes the output as a single text blob in llms.txt markdown format. It covers input requirements, processing steps, and output use. Given the simple parameter set and rich annotations, this is complete.

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

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

Schema description coverage is 100%, so the description adds minimal extra value. It mentions max_links default and cap (25, max 50), which is not in the schema. Baseline 3 is appropriate as the schema already provides adequate meaning for both parameters.

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

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

The description clearly states the tool generates an llms.txt file from a URL. It specifies the target audience (AI crawlers) and the output format. There are no ambiguous terms, and it distinguishes itself from siblings by being a unique tool for this specific task.

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 (getting client's site indexed, drafting own project, auditing competitor) but does not mention when not to use or suggest alternatives. Since no sibling tool serves the same purpose, this is acceptable but leaves room for improvement.

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 exist, so the description must disclose behavior. While it mentions 'mystical answer,' it does not explicitly state that the response is randomly generated and not based on any knowledge. This could mislead an agent into treating it as a factual lookup.

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

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

Two concise sentences that front-load the core functionality (ask question, get answer) and then detail options and use cases. 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 game tool, the description covers input, modes, and usage. However, it does not explain that answers are random, which is crucial for correct invocation. The presence of an output schema partially compensates, but the description should be more explicit.

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 context beyond the schema by summarizing the two optional modes ('cynical mode for negative-weighted answers, corporate mode for business jargon'). With 100% schema coverage, the baseline is 3, and the description provides extra value.

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

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

The description clearly states the tool accepts a yes-or-no question and returns a mystical answer. It distinguishes itself from siblings by being a fun/random decision tool rather than a factual query tool 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?

Provides explicit use cases: 'Use when you need a random decision, tie-breaker, or humorous perspective.' This helps the agent know when to invoke it, though it could be more specific about when not to use (e.g., for factual questions).

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 rate limiting (5 messages per identifier per day) and provides content guidelines (describe what you tried, no user prompt). With no annotations, this is helpful but lacks details like whether feedback is anonymous or confirmation of sending.

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, each serving a distinct purpose: purpose, usage guidelines, rate limit. It is front-loaded with the main action and very concise with 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 complexity (3 params, nested object, no output schema, no annotations), the description covers purpose, usage, rate limit, and content guidelines. It lacks details about return behavior or authentication, but for a feedback tool, this is reasonably 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%, so baseline is 3. The description adds value by specifying how to write the message (be specific, 1-2 sentences, 2000 chars max) and not to include user prompts, which goes beyond the schema's 'plain text' 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 uses a specific verb ('send feedback') and resource ('Pipeworx team'), and lists exact use cases (bug reports, feature requests, missing data, praise). It clearly distinguishes itself from sibling tools as no other sibling does feedback.

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

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

The description explicitly states when to use the tool (bug reports, feature requests, missing data, praise) and what not to include (end-user's prompt verbatim). It also mentions rate limits. However, it does not compare to alternatives or say 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds details: sourced from CF analytics, no PII, caching duration (5min-1h), and self-aggregating nature.

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

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

The description is concise, front-loaded with the return summary, then use cases, then technical details. Every sentence adds value.

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

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

Despite no output schema, the description explains the return structure (pack, tool, count) and caching. For a read-only aggregate tool, this is complete.

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

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

Only one parameter 'window' with 100% schema coverage. The description adds value by explaining when to use shorter vs longer windows, going beyond the schema enum.

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 recent window. It uses specific verbs and resources, and distinguishes itself from sibling tools by focusing on trending data.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use case with agent demand. Also describes caching behavior and window selection context.

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

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

The description goes beyond annotations by explaining the algorithmic process: walking child markets, extracting dates/thresholds, sorting, and reporting violations. It also specifies the output format and aligns with the readOnlyHint annotation, showing no contradiction.

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

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

The description is well-structured with a clear lead sentence, but it is somewhat verbose. However, every sentence provides necessary details, and the length is justified by the tool's complexity.

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

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

Despite no output schema, the description fully specifies the return format (list of entries with fields). It also covers the input, process, and conditions for arbitrage, making the tool's behavior completely understandable.

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

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

Schema coverage is 100%, and the description adds meaningful context for the single parameter 'event' by providing an example slug and explaining how it is used to identify the event. This adds value beyond the schema's description.

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

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

The description clearly states it finds arbitrage opportunities in Polymarket events by checking monotonicity violations. It provides a detailed example and distinguishes itself from sibling tools like 'polymarket_edges' by focusing specifically on within-event price order 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 explains when to use the tool (when an event has multiple 'by date' or 'by threshold' markets) and the logic behind it. It does not explicitly state when not to use it or provide alternatives, but the context is sufficiently clear for appropriate use.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds significant behavioral detail: V1 scope, data sources (FRED + coinpaprika), processing steps (group by asset, fetch price history once, compute probability), and output structure (ranked by edge magnitude with suggested direction). 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 a single paragraph that starts with the core purpose and then elaborates. It is informative without being overly verbose, though some minor redundancy exists (e.g., repeating 'top N'). Overall, efficient.

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

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

Despite lacking an output schema, the description fully explains what the tool returns and how it works. For a tool with 3 params and no output schema, it covers the essential behavioral context, including internal logic and data sources.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description reiterates defaults and adds context about their role (e.g., 'limit' is top N), but does not significantly extend beyond the schema. Baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('scan') and resource ('highest-volume Polymarket markets'), clearly states the goal (find where Pipeworx data disagrees most with market price), and distinguishes from siblings like 'polymarket_arbitrage' by focusing on edge discovery from model disagreement.

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

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

The description explicitly frames the tool for the 'what should I bet on today' question, indicating its primary use case. While it doesn't list when not to use, it implies a discovery scenario, and the context signals with sibling tools provide some differentiation.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context beyond annotations, including typical spread range (2-25pp), two modes of operation, and the return structure, without contradicting any annotation.

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

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

The description is concise, front-loaded with the core purpose, and efficiently covers modes and return format without wasted words. Every sentence adds value.

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

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

With no output schema, the description adequately explains return values (leg-by-leg prices, spread). It covers the two modes, parameter usage, and provides examples, making it complete for a tool with optional parameters.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning by explaining the interplay between parameters (explicit overrides topic) and providing examples, going slightly 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 cross-venue spreads between Kalshi and Polymarket, identifies two distinct modes (topic shortcuts and explicit pairings), and describes the output. It distinguishes itself from sibling tools like polymarket_arbitrage which may cover different arbitrage types.

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

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

The description explains when to use the topic mode vs explicit pairings, and gives examples. However, it does not explicitly state when not to use this tool or compare it to alternatives like polymarket_arbitrage, leaving some ambiguity for the 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?

No annotations are provided, so the description carries full burden. It discloses the dual behavior (single vs. list) and implies persistence across sessions. However, it does not mention any side effects or performance considerations, which is acceptable for a retrieval tool.

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

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

Two sentences with zero waste. Front-loaded with the primary action, then additional context. Every sentence earns its place.

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

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

Given the low complexity (1 optional parameter, no output schema, no annotations), the description is complete enough. It explains the two modes of operation and the persistence context. Could mention return format but 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%, and the description adds value by explaining the effect of omitting the key. However, it does not add much beyond what the schema says, so a baseline of 3 is appropriate.

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

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

The description clearly states it retrieves a stored memory by key, or lists all if key is omitted. It distinguishes the tool's purpose from siblings like 'remember' and 'forget'.

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

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

The description explains when to use the tool (to retrieve context saved earlier) and when to omit the key (to list all). It does not explicitly mention when not to use it or alternatives, but the context is clear enough.

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

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

With no annotations, the description carries the full burden. It discloses parallel fan-out to multiple sources, return structure (changes, count, URIs), and parameter formats (ISO date and relative). It does not mention error conditions or rate limits, but the core behavior is well covered.

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: overview, parameter behavior for company, return items, and usage suggestion. It is concise without redundancy, though slightly packed. Each sentence adds value.

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

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

Given no output schema, the description adequately covers the return value (structured changes, count, URIs). It addresses all parameters and the main use case. Minor gaps exist (e.g., error handling) but the tool is well-scoped for its purpose.

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

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

Schema coverage is 100% with good descriptions, but the tool description adds value beyond schema: it explains the type=company behavior (parallel fan-out), recommends typical 'since' values, and gives concrete examples. This enhances understanding beyond the raw 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 ('What's new about an entity since a given point in time') with a specific verb and resource, and distinguishes it from siblings by focusing on change monitoring over time, contrasting with tasks like entity profile or comparison.

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

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

The description explicitly recommends use for 'brief me on what happened with X' or change-monitoring workflows, and notes the limitation that only 'company' type is supported. 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It reveals persistence differences between authenticated users (persistent) and anonymous sessions (24-hour TTL), which is critical for agent 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?

Three sentences, each serving a distinct purpose: what it does, when to use it, and persistence behavior. Concise without being terse.

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 required string params, no output schema), the description is complete enough. It covers purpose, usage, and key behavioral constraint (persistence). No gaps for this tool type.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter semantics beyond what the schema already provides (key/value descriptions with examples). It merely restates the purpose.

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

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

The description clearly states the tool stores a key-value pair in session memory, specifies the verb ('store'), resource ('key-value pair'), and context ('session memory'). It distinguishes itself from siblings like 'recall' (retrieve) and 'forget' (remove).

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

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

The description explicitly advises when to use this tool: to save intermediate findings, user preferences, or context across tool calls. It does not provide explicit when-not-to-use or alternatives, but the context is clear and helpful.

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 provided, so the description must disclose traits. It details return values (ticker, CIK, name, URIs) but omits side effects, idempotency, error handling, or rate limits. Adequate but not rich.

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

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

Three concise sentences, front-loaded with purpose, no redundant information. 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?

For a simple 2-parameter tool with no output schema, the description is fairly complete: what, how, and what's returned. Could mention error handling but 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 covers both parameters with descriptions, and the description adds value by providing example values and clarifying acceptable formats (e.g., 'AAPL', '0000320193', 'Apple').

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 action 'resolve an entity to canonical IDs', specifies the supported type 'company' with concrete examples, and distinguishes from sibling tools which are unrelated (e.g., ask_pipeworx, remember).

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

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

The description implies when to use: to replace multiple lookup calls, and it limits v1 to company entities. However, it does not explicitly state when not to use or mention alternatives, though siblings are not comparable.

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. The description adds that it calls ai_visibility_check per entity, returns a ranked list with score/confidence/signal density, and surfaces which entity is most/least recognized. 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: purpose, mechanism, use case/return. No fluff, every sentence is informative. Perfectly 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?

The tool has 4 documented parameters, no output schema but description details the return (ranked list with score/confidence/signal density). For a comparison tool, this covers expected behavior. Could mention pagination or limits on entity count but mostly 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% so baseline is 3. The description adds value by noting that the first entity is treated as 'subject' and specifying default model behavior, but otherwise does not significantly extend schema descriptions.

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

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

The description clearly states the tool compares AI visibility among multiple entities, specifies it uses ai_visibility_check, ranks results, and gives a concrete example. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description explicitly mentions use for competitive AI-marketing audits and provides an example query. It implies when to use but does not explicitly state when not to use or list alternatives.

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

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

No annotations provided, so description carries full burden. It describes the return values including verdict types, extracted form, actual value with citation, and percent delta. It also notes it replaces multiple steps. It does not discuss error behavior or auth, but for a v1 tool with read-like semantics, this is adequate.

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

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

Two sentences plus a list of return values. Extremely concise with no redundant words. The most critical information (purpose, scope, output) is front-loaded and easy to parse.

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 a single parameter and no output schema, the description covers the tool's behavior adequately. It explains what claims are accepted, what is returned, and the benefit of replacing multiple calls. Minor gaps include lack of error handling notes or performance expectations, but overall complete for its simplicity.

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 descriptive parameter comment. The tool description adds context about supported claim formats (e.g., 'Apple's FY2024 revenue was $400 billion'), but this largely overlaps with the schema. No additional semantics beyond what the schema already provides.

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 fact-checks natural-language claims against authoritative sources, specifically company-financial claims for US public companies via SEC EDGAR + XBRL. The verb 'fact-check' and resource specification are precise, and it distinguishes from siblings by focusing on claim validation rather than general queries or entity comparisons.

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 the supported claim types (company-financial for US public companies) and mentions it replaces multiple sequential agent calls. However, it does not explicitly state when not to use (e.g., non-financial claims) or mention alternative tools, but the scope limitation is clear enough.

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