Corporate Apology

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds context: it notes that Anthropic calls incur direct costs via BYO key, and it specifies the return format (score, confidence, signals, raw_response). 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?

Three sentences, each serving a purpose: purpose+default, optional key explanation, return format+use cases. Front-loaded, no redundancy, every sentence earns its place.

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

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

Given no output schema, the description adequately covers return format (per-model + combined view). It addresses behavioral aspects (cost, default, optional Anthropic) and practical use cases. The tool is moderately complex but the description provides sufficient context for an agent to invoke it appropriately.

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

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

Schema coverage is 100%, baseline 3. The description adds value beyond schema by clarifying default model behavior, BYO key mechanics ('passed straight through'), and the disambiguation role of the 'context' parameter. Examples like 'Pipeworx' and 'OpenInvoice' further aid understanding.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs, visibility). It distinguishes the tool's purpose from siblings like 'scan_competitor_ai_presence' by highlighting multi-model probing and scoring, and provides use-case context (AI-marketing audits).

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

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

The description explains when to use the default model vs. Anthropic with a BYO key, and mentions typical use cases. It does not explicitly exclude alternatives or compare with siblings, but the guidance is clear and actionable.

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 explains tool selects the best data source, fills arguments, and returns result. No annotations provided, so description carries full burden. Could mention limitations or data freshness, but still informative.

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

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

Concise three-sentence description with examples. No fluff.

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

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

Given simplicity (1 param, no output schema), description is complete enough. Could mention if questions are limited to certain domains, but not necessary.

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

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

Schema covers 100% of parameters with description. Description adds context that the single parameter 'question' should be a natural language request, beyond the schema's '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?

Description states tool acts as a natural language query interface that selects the best data source. Clearly differentiates from siblings like 'corporate_apology_generate' or 'discover_tools' by focusing on answering arbitrary questions.

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

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

Explicitly says to ask in plain English without browsing tools or learning schemas. Provides examples. Implicitly contrasts with tools that require structured input.

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, non-destructive, and open-world behavior. The description adds valuable behavioral context: the tool resolves the market, classifies the bet, fans out to packs based on type, and returns an evidence packet and comparison. 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-5 sentences, front-loading the purpose and then detailing behavior. It is efficient but not overly terse. Every sentence adds value.

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

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

Given no output schema, the description adequately covers the return format (evidence packet plus market-vs-model comparison). It also implies fan-out logic and classification types. Sufficient for an agent to understand the tool's capabilities.

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 examples for 'market' (slug, URL, question text) and explains the 'depth' enum (quick vs thorough), providing meaning beyond the schema alone.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying the bet type, and returning evidence and comparison. It distinguishes itself from siblings like ask_pipeworx by focusing specifically on Polymarket betting with a structured fan-out to relevant data packs.

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 like 'should I bet on X?' and 'is there edge in this bet?', and claims it's the core demo product for better conversion. However, it does not explicitly state when not to use it or compare directly to specific sibling 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool returns paired data and resource URIs for both entity types. However, it does not explicitly state that the tool is read-only or describe any side effects, auth requirements, or rate limits. The behavioral traits are partially disclosed but not fully 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?

The description is concise, consisting of two sentences that front-load the core purpose. Every sentence adds value: the first defines the goal, the second elaborates on types and outputs. There is no redundancy or unnecessary detail.

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

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

Given the absence of an output schema, the description does well to summarize the return data (paired data + resource URIs) for both entity types. However, it could be more complete by specifying the structure of the paired data or providing an example of the output, but it is sufficient for a compare tool with two simple types.

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

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

The input schema already covers the two parameters with 100% description coverage. The description adds meaning by explaining what data is returned for each entity type (e.g., revenue, net income for companies; adverse-event reports for drugs) and providing examples of valid values. This enriches the schema explanations without merely repeating them.

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: comparing 2-5 entities side by side in one call. It distinguishes itself by specifying the two entity types (company and drug) and the data returned for each, and it explicitly notes that it replaces multiple sequential agent calls, differentiating it from potential alternative approaches.

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 guidance on when to use the tool: for comparing multiple entities in a single call to improve efficiency. It even quantifies the benefit (replaces 8-15 sequential calls). However, it does not explicitly state when not to use it or mention alternatives among the sibling tools, though the context implies it is for batch comparisons.

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

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

The description explains it returns ready-to-use text, which is the main behavioral trait. With no annotations, it carries the full burden and does so without contradiction, though it could mention that it generates text without side effects.

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, front-loaded with the main action, and contains no unnecessary words or 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 output schema exists, the description adequately covers purpose and key parameter. It could mention that the tool generates text based on provided inputs, but is still complete 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?

The description adds meaning to the sincerity parameter by listing its values and effect, partially compensating for the 40% schema coverage. It does not detail medium or audience, but enums provide constraints.

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

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

The description clearly states the tool generates a corporate apology statement, specifies the key sincerity parameter and its options, and distinguishes it from sibling tools (none similar).

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

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

The description indicates when to use the tool (to generate an apology) and highlights the sincerity parameter for tone control, but does not provide exclusions or alternatives, which are not needed given no similar siblings.

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

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

No annotations provided, so description carries burden. It states tool returns 'most relevant tools' and limits are described in schema, but does not detail how relevance is determined, or if the search is idempotent or has side effects. 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?

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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

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

Given tool has 2 simple params, no output schema, and no annotations, the description adequately covers its purpose and usage. Lacks info on output format or error handling, but not critical for this discovery tool.

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

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

Schema coverage is 100% with good descriptions for both parameters (query and limit). Description does not add new meaning beyond the schema, so baseline 3 applies.

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

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

Description clearly states verb 'Search' and resource 'Pipeworx tool catalog', and specifies it returns tool names and descriptions. It also distinguishes itself as a discovery tool to be called first when many tools are available, 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?

Explicitly instructs 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task', providing clear context for when to use this tool.

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

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

Despite no annotations, the description discloses that the tool returns many data types, citation URIs, and bundles data from multiple sources. It doesn't mention error handling or performance, but overall provides sufficient behavioral insight for an aggregation 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 and well-structured: front-loads the main purpose, uses bullet-like prose for data types, and provides explicit usage guidance in the last sentence. Every sentence adds value.

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

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

Given no output schema, the description explains the return format (citation URIs) and lists all included data types. It also explicitly notes what is excluded (federal contracts) and directs to the appropriate alternative, making it complete for this complex tool.

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

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

Schema coverage is 100%, but the description adds significant value by clarifying that only 'company' type is supported and that the value parameter accepts ticker or CIK (with examples), explicitly stating names are not supported and directing to resolve_entity.

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 a full profile of an entity across multiple packs, listing specific data types for 'company' and noting it replaces 10–15 sequential calls. The verb 'returns profile' is specific and distinguishes it from siblings 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?

Explicitly provides guidance: for federal contracts use usa_recipient_profile directly, and if you only have a name use resolve_entity first. This clearly tells when to use alternatives.

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

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

No annotations are provided, so the description must convey behavioral traits. It correctly implies a destructive action (delete), but lacks details on whether deletion is permanent, reversible, or requires confirmation. Returns are not described.

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 sentence, no wasted words. Front-loaded with action and resource.

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

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

For a simple 1-param tool with 100% schema coverage and no output schema, the description is adequate but lacks usage context (e.g., error behavior, idempotency). Could mention if deleting a missing key is an error or no-op.

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% (one parameter described in schema). The description says 'by key', which adds minimal extra meaning beyond the schema's 'Memory key to delete'. No format or constraints beyond schema.

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

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

The description clearly states the action ('Delete') and the resource ('a stored memory'), with a specific qualifier ('by key'). It distinguishes from siblings like 'remember' (create) and 'recall' (retrieve), though not explicitly.

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?

No guidance on when to use this tool vs alternatives (e.g., 'forget' vs 'recall' for reading). No mention of prerequisites or edge cases like deleting non-existent keys.

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 idempotentHint=true, so the tool is safe. The description adds that it fetches the page and emits a text blob, but does not describe error handling or output format details beyond 'single text blob'. With annotations covering safety, the description provides adequate but not extensive additional behavioral context.

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

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

The description is three sentences long, starting with the main action, then listing use cases. It is efficient with no filler, though slightly verbose in the use case list.

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, strong annotations), the description covers purpose, target audience, output format, and use cases. It does not mention rate limits or error behaviors, but annotations imply safety. Overall, it is contextually complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters described adequately. The description restates the purpose of the URL parameter and adds default/max for max_links, but does not add significant new 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 generates a production-ready llms.txt file for a URL, specifically for AI crawlers. The verb 'generate' and resource 'llms.txt' are specific, and the tool is distinct from all sibling tools listed.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own projects, and auditing competitors. It does not contrast directly with sibling tools, but the use cases are clear and appropriate.

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. It discloses the rate limit and content constraints (no prompts verbatim). Since the tool is a one-way feedback channel, no destructive or read side effects are expected, and the description is transparent enough for safe 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 two sentences plus a rate-limit note. It is front-loaded with the core purpose, then provides usage details. No wasted words.

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

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

For a feedback tool with no output schema, the description covers use cases, content rules, and rate limits. It could mention that the feedback is sent asynchronously or that no confirmation is returned, but given the simplicity, 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% (all parameters have descriptions). The description adds value by specifying typical message length (1-2 sentences, 2000 chars max) and content guidelines ('be specific', 'do not include the end-user's prompt verbatim'), which supplement the schema.

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

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

The description clearly states the tool's purpose: sending feedback (bug reports, feature requests, missing data, praise) to the Pipeworx team. It uses a specific verb ('Send feedback') and resource ('Pipeworx team'), and distinguishes itself from sibling tools which are query/compare/remember 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 when-to-use guidance for different feedback types and advises on content (describe what you tried, don't include user prompt verbatim). It also mentions a rate limit of 5 messages per day. However, it does not explicitly state when not to use the tool or name 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?

Adds caching, data source (CF analytics), and aggregation details beyond annotations (readOnlyHint, idempotentHint). 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?

Well-structured, front-loaded with purpose. Slightly lengthy but 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 simplicity (1 optional param, no output schema), description fully covers behavior, use cases, and data characteristics.

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 fully covers the parameter, but description adds rationale (short vs long windows) enhancing semantic understanding.

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

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

Clearly states the tool returns top tools, packs, and call volume based on trending data. Differentiates from siblings like 'discover_tools' by focusing on popularity signal.

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?

Lists three explicit use cases (discovering hot data, confirming canonical tool, alignment check). No explicit when-not-to-use, but context is strong.

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 and openWorldHint=true. The description adds behavioral details such as the two operational modes, the search across related markets in topic mode, and the return of 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 concise, using a clear two-sentence structure for modes and a final sentence on output. No redundant or unnecessary words; every sentence adds value.

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

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

The description covers purpose, modes, use cases (with an example where single-event fails), and output format. Despite no output schema, it clearly states 'returns ranked opportunities with suggested trade direction + reasoning', which is sufficient for an agent.

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

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

Schema coverage is 100% and parameter descriptions already mention the modes. The tool description adds extra behavioral context: in event mode it 'walks that event's child markets', and in topic mode it 'searches across separate events' and 'groups them'. This goes beyond the schema to clarify tool behavior.

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: finding arbitrage opportunities via monotonicity violations. It distinguishes between two modes (event and topic) and contrasts with likely sibling tool polymarket_edges implicitly by focusing on arbitrage rather than edges.

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

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

The description explains when to use each mode: event mode for a single Polymarket event, topic mode for cross-event exploration. It provides a concrete example of when topic mode is necessary ('Polymarket lists each cutoff as its own event'). However, it does not explicitly say when not to use the tool, but the guidance 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?

The description details the internal process: scanning top markets, grouping by asset, fetching price history once, computing model probability, ranking by |edge|, and returning top N with direction. This adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), which are already consistent with a read-only, data-fetching operation.

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

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

The description is relatively long but front-loads the main purpose in the first sentence. Every sentence adds value (model details, process steps, output format). Could be tightened slightly, but overall 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 complexity (API calls, mathematical model, ranking), the description covers logic, data sources (FRED, coinpaprika), and output (ranked edges with direction). It also notes it's V1 and covers only crypto-price bets, providing full context. No output schema exists, but return format is described sufficiently.

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

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

Schema coverage is 100%, so the schema already describes all three parameters. The description adds default values and context (e.g., 'window' is Polymarket volume window, 'limit' max 25), but does not significantly augment schema meaning. Baseline 3 is appropriate.

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

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

The description clearly states it scans Polymarket markets to find where Pipeworx data disagrees with market price, specifying the resource (Polymarket markets), verb (scan/return edges), and model (crypto-price bets with lognormal model). This distinguishes it from siblings like 'polymarket_arbitrage' and 'bet_research'.

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

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

The description explicitly says it's built for 'what should I bet on today' and helps discover opportunities without manual paging. It gives clear context for when to use it, though it doesn't explicitly mention alternatives or when not to use it.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds that the tool returns prices and spreads, explains the override mechanism, and notes it is a real arbitrage signal. No contradictions or hidden side effects.

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

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

The description is detailed but front-loaded with the core purpose. Each sentence adds information. Could be slightly more concise, but it effectively communicates all necessary details.

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

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

Without an output schema, the description explains the return structure (leg-by-leg prices and spread). It covers the tool's functionality well, though data freshness or update frequency is not mentioned.

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

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

Schema covers 100% of parameters. The description adds value by explaining the topic shortcuts, override behavior, and the exact meaning of each parameter, going beyond the schema's brief descriptions.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket, specifying two modes and distinguishing it from sibling tools like polymarket_arbitrage. The verb 'compute' is implicit but the resource and action are clear.

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

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

The description explains two usage modes (topic shortcuts or explicit tickers) and provides guidance on when to use each. It does not explicitly compare to siblings but the mode selection offers clear direction.

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 discloses the two behaviors (by key vs list all) but doesn't mention any side effects, permissions, or limitations (e.g., memory persistence scope).

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

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

Two sentences, no fluff. Purpose and usage are front-loaded. Every sentence adds value.

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

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

Given no output schema and no annotations, the description covers the basic purpose and parameter usage. However, it lacks details about return format, memory limits, or how this relates to 'remember' and 'forget'.

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 already describes the single optional parameter 'key' well (100% coverage). The description adds the 'omit to list all keys' nuance, which clarifies the parameter's behavior beyond the schema 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?

Description clearly states the tool retrieves memories by key or lists all when key is omitted. It specifies the resource ('memory') and distinguishes the two modes, though it could be more precise about what a 'memory' is.

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 mentions using it to retrieve context saved earlier, implying when to use. However, it doesn't explicitly contrast with sibling tools like 'forget' or 'remember' or provide 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, the description fully explains behavior: parallel fan-out to three sources, accepted date formats (ISO and relative), and return structure (changes, count, URIs). It lacks details on error handling or performance, but covers the key aspects for invocation.

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, each serving a purpose: overall goal, fan-out detail, parameter formats, return structure, and use case. No redundant or unnecessary text.

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

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

Given no output schema, the description covers all necessary information: input parameters, behavior, return format, and intended use. The tool is well-documented for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, but the description adds value beyond the schema: examples for 'since' ('7d', '30d', '3m', '1y') and guidance to use '30d' or '1m' for monitoring, plus ticker/CIK format for 'value'. This helps agents choose correct parameter values.

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 purpose: 'What's new about an entity since a given point in time.' It specifies the entity type (company) and the three data sources it fans out to (SEC, GDELT, USPTO). This distinguishes it from sibling tools like entity_profile 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 explicitly recommends use cases: 'brief me on what happened with X' or change-monitoring workflows. While it doesn't mention when not to use or list alternatives, the usage context is clear and actionable.

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

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

Discloses important behavioral traits: memory persistence depends on authentication, anonymous sessions last 24 hours. This goes beyond what annotations provide (none), adding valuable context about data retention.

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

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

Two sentences, front-loaded with main action and purpose, then usage guidelines. No wasted words.

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

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

Given no output schema and simple key-value pair, description adequately covers purpose, usage, and behavioral constraints. Slightly missing is mention of overwrite behavior or key uniqueness, but still complete for typical use.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by stating purpose of parameters ('findings, addresses, preferences, notes'), but does not add syntax details beyond schema.

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

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

Clearly states verb 'Store', resource 'key-value pair', and context 'session memory'. Distinguishes from sibling tools like 'forget' and 'recall' by implying storage action.

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 usage scenarios: 'save intermediate findings, user preferences, or context across tool calls'. Also notes persistence difference between authenticated and anonymous sessions, guiding when 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?

No annotations provided, so description carries full burden. It discloses the return fields (ticker, CIK, company name, pipeworx:// URIs) and the read-only nature is implied. Could be improved by explicitly stating it's a read operation, but current detail is sufficient.

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

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

Two sentences with no fluff. First sentence states the core purpose, second provides important details and context. Information 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?

For a simple tool with two parameters, the description covers input, output, and use case adequately. Despite no output schema, it lists return fields. No additional context is needed for correct invocation.

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

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

Schema coverage is 100%, and description adds significant value by providing concrete examples (AAPL, 0000320193, Apple) and clarifying that v1 only supports 'company'. This enhances understanding 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?

Description clearly states the tool resolves entities to canonical IDs, specifies the only supported type (company), and lists accepted input formats with examples. It distinguishes itself from siblings by indicating it replaces multiple lookup calls.

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

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

Description tells when to use (for entity resolution) and emphasizes efficiency by replacing multiple calls. It does not explicitly state when not to use, but the purpose is clear enough to avoid confusion with siblings like ask_pipeworx.

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

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

Annotations already indicate safe, idempotent, open-world behavior. Description adds that it runs multiple probes, ranks by score, and returns specific fields (score, confidence, signal density), which is valuable context beyond annotations.

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

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

Three concise sentences with no filler. Purpose, mechanism, and output are front-loaded. 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?

Provides return format details despite no output schema. Covers parameter semantics and use case. Minor omission: does not specify max entities (schema says 2-8) or any rate limits, but overall 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 has 100% coverage, baseline 3. Description adds extra meaning: first entity is the 'subject', models list with default and authentication note, context disambiguates names. This provides clear usage semantics.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side using ai_visibility_check, distinguishing it from the single-entity sibling tool. The verb 'scan_competitor_ai_presence' is specific and resource-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?

Explicitly frames the tool for competitive AI-marketing audits with a concrete example question. Implicitly contrasts with ai_visibility_check by stating 'probes each entity... with ai_visibility_check', but does not explicitly state 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?

No annotations are provided, so the description carries full burden. It discloses the data source (SEC EDGAR + XBRL), verdict types, and citation format. However, it does not address rate limits, authentication, error handling, or failure modes.

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 purpose. Each sentence adds meaningful information without redundancy. Minor improvement could be more succinct output list.

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 that replaces 4-6 agent calls, the description covers core functionality and outputs but lacks details on error conditions, unsupported claim types, or performance characteristics. With no output schema, the description should provide more on return format boundaries.

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

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

The input schema has 100% coverage for the single parameter 'claim', with a clear description. The tool description adds value by providing examples and domain-specific context (e.g., 'revenue / net income / cash') beyond the schema, helping the agent understand expected input format.

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 fact-check natural-language claims using authoritative sources. It specifies the domain (company-financial claims for public US companies) and lists outputs (verdict, extracted form, value, citation). However, it does not explicitly distinguish from sibling tools like compare_entities or entity_profile.

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

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

The description implies when to use (for company-financial claims) and mentions it replaces sequential agent calls, but does not provide explicit alternatives among siblings or state when not to use. It offers partial guidance but lacks completeness.

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