Emoji Oracle

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: that Anthropic requires a BYO key and costs incurred by the user, and that it returns a combined view with per-model details. 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 two sentences with a brief follow-up on return format. It is front-loaded with the core purpose and efficient, though slightly verbose in the second 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 adequately explains the return structure (per-model fields + combined view). It covers all parameters, use cases, and behavioral notes (e.g., cost for Anthropic). The tool is relatively simple, and the description 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 coverage is 100%, so baseline is 3. The description adds meaningful examples for 'entity' (e.g., 'Pipeworx'), explains default value and required key for 'models' and '_apiKey', and clarifies the disambiguation role of 'context'. This goes beyond schema definitions.

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

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

The description uses specific verbs ('Probe one or more LLMs') and explicitly states the resource and outcome: scoring visibility per model. It distinguishes the tool from siblings by its unique focus on AI visibility auditing.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model vs. optional Anthropic key. It lacks explicit when-not-to-use guidance or alternatives, but the context is sufficient.

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

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

No annotations provided, so description carries full burden. It discloses that the tool picks the best data source and fills arguments automatically, which is helpful. However, it doesn't mention any potential rate limits, query complexity limits, or whether answers are cached. Still, for a general-purpose query tool, this 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?

Description is concise at about 60 words, with key information front-loaded. Each sentence adds value: purpose, mechanism, and examples. Could be slightly more compact 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 simplicity (one parameter, no output schema, no annotations), the description is quite complete. It explains the tool's autonomous behavior and provides examples. Could mention what happens if the question is ambiguous or unsupported, but not necessary for basic understanding.

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

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

Schema coverage is 100% with one parameter 'question' described as 'Your question or request in natural language'. The description adds context by stating the input is 'plain English' and giving examples, which enhances understanding beyond the schema's minimal 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 accepts natural language questions and returns answers from the best data source, with specific examples that illustrate its purpose. Distinguishes itself from siblings like discover_tools (which likely lists tools) and recall/remember (which deal with memory).

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

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

Explicitly tells when to use: when you need an answer from data without browsing tools or learning schemas. Provides examples and implies when not to use (e.g., if you need to directly invoke a specific tool). Contrasts with sibling tools like discover_tools (for tool discovery) and emoji_oracle_consult (for emoji-specific queries).

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

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

Annotations show readOnlyHint=true, openWorldHint=true, destructiveHint=false. Description adds details: market resolution, bet classification, dynamic fan-out to packs (e.g. crypto+fred+gdelt), and return of evidence packet with comparison. No mention of error handling or depth specifics, but overall good disclosure.

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 moderately long but every sentence adds value. Front-loaded with purpose. Could trim some redundancy (e.g., 'core demo product' sentence), but 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 no output schema, description covers what is returned (evidence packet + comparison). Explains internal logic (classification, fan-out). No missing crucial details for a research 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 has 100% coverage with descriptions. Description adds value by explaining depth enum values ('quick = 2-3 evidence sources, thorough = full fan-out') and market parameter variants. Goes beyond schema baseline.

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

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

Description clearly states it researches Polymarket bets by pulling Pipeworx data, specifies inputs (slug, URL, question text), and explains the process (resolve, classify, fan-out, return evidence). Distinct from sibling tools like ask_pipeworx or validate_claim.

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 gives use cases: 'should I bet on X?', 'what does the data say?', 'is there edge?'. Notes that agents using this convert better than discovering packs themselves. Lacks explicit when-not-to-use, but 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?

No annotations are provided, so the description carries full burden. It mentions the data sources and return format but does not disclose error handling, rate limits, or what happens if entities are not found. This is 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?

Two sentences with no wasted words. The first sentence states the core function, the second adds details and benefits. Front-loaded and 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?

For a tool with 2 parameters, no output schema, and an enum, the description covers the what, why, and how. It explains the data returned and the advantage over sequential calls. Missing details on error handling, but overall complete enough.

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 providing concrete examples for values and explaining the return format. It goes beyond the schema by highlighting the efficiency gain.

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 with specific fields for each type. It distinguishes itself from siblings by noting it replaces 8-15 sequential calls, making the purpose unambiguous.

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

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

The description explicitly mentions when to use it ('compare side by side in one call') and contrasts with sequential calls. However, it does not explicitly state when not to use it or list alternative tools, 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?

The description notes the tool returns 'the most relevant tools with names and descriptions,' which is helpful but not detailed beyond that. With no annotations provided, the description carries full burden, but it lacks specifics on search behavior (e.g., ranking criteria, whether it's read-only, or if it modifies state). A score of 3 is appropriate as it adds some transparency but not exhaustive.

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 sentence that efficiently conveys the purpose, usage, and context. Every word serves a purpose, 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 (2 params, no output schema, no nested objects), the description is reasonably complete. It covers what the tool does, when to use it, and what it returns. However, it could briefly mention that it is a read-only operation or that it does not modify state, but this is not critical for a search tool. Score 4 reflects good completeness for the context.

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

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

Schema coverage is 100%, so the input schema already describes both parameters (query and limit). The description adds minimal extra meaning beyond what the schema provides; it explains the query parameter's purpose but doesn't add new constraints or examples beyond what's in the schema description. Baseline 3 is correct.

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 ('Search...catalog') and clearly states the resource ('Pipeworx tool catalog'). It distinguishes this tool from siblings by explicitly calling it the first step when many tools are available, contrasting with tools like 'ask_pipeworx' or 'emoji_oracle_consult'.

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 this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This provides clear context and excludes alternative uses, guiding the agent effectively.

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 burden of behavioral disclosure. It mentions the output format (emoji sequence, vibe rating, optional text) but does not clarify if it is a read-only operation, any side effects, authentication needs, or rate limits.

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 core purpose, and every word adds value. It is concise and well-structured.

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

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

Given the tool's simplicity, the description covers the main functionality, inputs, and outputs. The presence of an output schema further reduces the need to detail return values. However, it lacks comparison to sibling tools and could briefly note the read-only nature.

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 each parameter already has a clear description. The main description reinforces the overall purpose but does not add new semantic details beyond what the schema 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?

The description clearly states the tool's purpose: asking a question to the Emoji Oracle and receiving a cryptic emoji prophecy with vibe rating. It distinguishes itself from siblings like ask_pipeworx by focusing on fun, oracular queries.

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

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

The description implies usage for oracle-style questions but does not provide explicit guidance on when to use this tool versus alternatives like ask_pipeworx or compare_entities. No exclusions or preferences are stated.

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

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

No annotations provided, so description carries full burden. It discloses return format (pipeworx:// URIs), data sources, limitations (only company, no names), and the bundling optimization. Lacks mention of auth or side effects but is otherwise 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?

Two concise sentences plus a bullet-style list of contents. Front-loaded with purpose. Every sentence adds value without 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?

For a 2-param tool with no output schema, it fully explains return format and contents, covers limitations, and provides cross-reference to alternative tool. No gaps.

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

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

Adds significant meaning beyond schema: clarifies type is currently only 'company', explains value can be ticker or CIK, explicitly warns against names and suggests resolve_entity. Schema coverage is 100% but description enriches it.

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 provides a full profile of an entity across relevant packs, lists specific data returned for 'company', and distinguishes from sibling tools by noting it replaces 10–15 sequential 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?

Explicitly tells when to use (aggregated profile) and when not to (federal contracts), and advises using resolve_entity for names, providing strong alternative guidance.

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

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

No annotations are provided, so the description must convey behavioral traits. It only states 'Delete' which implies mutation, but does not clarify if deletion is permanent, whether it requires confirmation, or what happens to associated data.

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, zero waste. Front-loaded with action and object.

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 delete tool with one parameter, the description is minimal but sufficient for basic understanding. However, lack of behavioral details (e.g., idempotency, error behavior) and no output schema leaves gaps 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% with one parameter 'key' described as 'Memory key to delete'. The description adds no further 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?

The description clearly states the verb 'Delete' and the resource 'stored memory by key', making the purpose obvious. It distinguishes from siblings like 'remember' (store) 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 versus alternatives like 'recall' or 'remember'. The description implies deletion, but does not state prerequisites or consequences.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds value by detailing the process (fetch, extract, emit) and output format (plain text blob for site-root/llms.txt), which goes beyond what annotations provide.

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: purpose, process, use cases. No wasted words, front-loaded with the core action. Every sentence is necessary and informative.

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

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

Given the low complexity (2 params, no output schema, annotations present), the description covers the main behavior and use cases. It does not mention error handling or limitations, but it is sufficient for an agent to understand the tool's purpose and usage.

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

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

Schema coverage is 100% with both parameters fully described. The description does not add new semantic information beyond the schema; it restates the default and max for max_links, but no new meaning.

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 for AI crawlers, specifying the actions: fetches page, extracts title/description/key links, outputs markdown. It distinguishes itself from siblings as no other sibling tool has a similar purpose.

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

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

The description provides explicit use cases: getting client site indexed, drafting for own project, auditing competitor. It lacks explicit when-not-to-use or alternatives, but the use cases cover common scenarios well.

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

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

With no annotations provided, the description carries full burden. It discloses rate limiting (5 per identifier per day) and that it is free. It also warns against including end-user prompts. No contradictions.

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

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

The description is 4 sentences with front-loaded purpose and specific use cases. It is concise without fluff, though could be slightly more streamlined.

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 purpose, usage, behavioral traits, and parameter hints. It is complete for a feedback tool with nested objects documented in schema.

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

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

All 3 parameters have schema descriptions (100% coverage). The description adds value by advising to describe what was tried in terms of Pipeworx tools/data and not to include verbatim prompts, which aids correct usage 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 verb 'send feedback' and specifies resources: bug reports, feature requests, missing data, praise. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by focusing on 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 lists specific use cases (bug, feature, etc.) and provides constraints (do not include end-user's prompt verbatim, rate-limited to 5 per day). It does not explicitly mention when not to use, but siblings do not overlap.

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 describing read-only and non-destructive, it adds data source, privacy (no PII), and caching behavior (5min-1h). 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?

Three sentences: core function, use cases, technical details. No fluff, all sentences earn their place.

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

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

For a simple tool with one parameter and rich annotations, the description fully explains usage, output, and caveats like caching and no PII.

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 parameter with enum descriptions. Description adds context: shorter windows for hot items, longer for steady-state.

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 returns top tools, packs, and call volume over a window. Distinguishes from siblings as no other tool does trending specifically.

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 and gives window guidance. Does not mention when not to use or alternatives, but the use cases are 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?

Discloses the full process: walking child markets, extracting dates/thresholds, sorting, and reporting violations. Consistent with readOnlyHint and openWorldHint 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?

Efficiently structured: purpose first, then logic, then output format. No redundant sentences.

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

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

Completely covers the tool's behavior, input, and output despite no output schema. The return fields are specified.

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 fully describes the 'event' parameter; the description adds value by explaining input formats (slug or URL) and how it's used to traverse markets.

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 precisely states the tool finds arbitrage opportunities via monotonicity violations, with a clear example distinguishing it from siblings like 'polymarket_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?

Describes when to use (events with multiple 'by date' markets) and implies not to use otherwise, but doesn't explicitly list alternatives or exclusions.

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

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

Goes beyond annotations (readOnlyHint, openWorldHint) by detailing the underlying model (lognormal from FRED + coinpaprika), process (scans, groups, fetches price history once), and output (edge rank with suggested direction). No contradictions.

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

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

Description is front-loaded with purpose and efficiently conveys process details. Slightly verbose but earns its sentences by explaining V1 scope and intended use case.

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

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

Given no output schema, description adequately explains return value (top N by edge magnitude with suggested direction). Provides sufficient context for a read-only 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?

Input schema provides full coverage with descriptions for all three parameters (limit, window, min_edge_pp). Description adds no further semantics, so baseline 3 is appropriate.

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

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

Description clearly states the tool scans Polymarket markets and returns those where Pipeworx data disagrees most with market price, specifically for crypto-price bets. It differentiates from siblings like polymarket_arbitrage by focusing on edge-based opportunity discovery.

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

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

Explicitly states it's built for the 'what should I bet on today' question, implying when to use. However, it lacks explicit exclusion criteria or alternatives, though the sibling tool list provides context.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds that it fetches current prices and computes spreads, and notes the typical price delta (2-25pp) as an arb signal. No contradictions.

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

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

The description is informative and well-structured, with a clear lead sentence, context, modes, and return info. Slightly lengthy but 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 explains return format (prices in 0-1, spread in pp). It covers inputs, modes, and output, making it complete for a read-only data 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 covers all three parameters with descriptions. The description adds the interaction logic: topic auto-fetches both sides, while explicit tickers override topic mapping. This clarifies relationships beyond schema.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishes between two modes (topic and explicit pairing), and specifies the output (leg-by-leg prices and spread). This differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description explains two modes (topic for pre-mapped shortcuts, explicit for custom pairings) and hints at usage contexts (arbitrage signal). It does not explicitly list when not to use or alternatives, but the modes provide clear guidance.

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

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

No annotations provided, so description carries full burden. It discloses that omitting key lists all memories and retrieving by key returns a specific memory. Could be improved by noting if retrieval is read-only or has side effects, but overall clear.

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 key verb 'Retrieve'. Concise and to the point. Could potentially add a note about the effect of the operation (e.g., no side effects) but efficient as is.

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 implies return value (memory content or list of keys). Siblings are clear, and context is simple (1 optional param). Completeness is high for a retrieval tool.

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

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

Schema description coverage is 100% (key parameter described in schema). Description adds value by explaining that omitting key lists all memories, which is not in schema. However, no additional constraints or formatting details are added.

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

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

The description clearly states the tool retrieves a stored memory by key or lists all memories when key is omitted. It is specific and distinct from siblings like 'remember' (store) and 'forget' (delete).

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 this tool (to retrieve context saved earlier) and implies when to omit the key (to list all). However, it does not explicitly mention when not to use it or alternatives beyond the implicit sibling distinction.

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?

Without annotations, the description carries the full burden. It discloses parallel fan-out to three sources, the supported type (only company), and the return structure (structured changes, count, URIs). It could mention read-only nature or idempotency, but the disclosed behavior is solid.

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 earning its place: purpose and sources, parameter format, return value and use case. No fluff, front-loaded with the core action.

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

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

Given no output schema, the description covers parameters fully and mentions the return format. It explains behavior (parallel fan-out) and use cases. Minor omissions like error handling or ordering are acceptable for this complexity level.

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 descriptions cover 100% of parameters, but the description adds valuable semantics: concrete formats for 'since' (ISO vs relative with examples), the dual use of 'value' (ticker or CIK), and the single enum value for 'type'. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: showing 'what's new about an entity since a given point in time' and details the multi-source fan-out for company type. It distinguishes itself from siblings like entity_profile (static profile) and compare_entities (comparison) by focusing on temporal changes.

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 using it for 'brief me on what happened with X' or change-monitoring workflows, and gives concrete advice for the 'since' parameter (e.g., '30d' or '1m' for typical monitoring). It does not explicitly state when not to use it, 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?

Discloses behavioral traits: 'Authenticated users get persistent memory; anonymous sessions last 24 hours.' Since annotations are absent, this description adds crucial context about data persistence without contradictions.

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

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

Three sentences, no fluff. First sentence states core action, second provides usage guidance, third adds behavioral transparency. Front-loaded with essential purpose.

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

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

Given the simple tool (two required string params, no output schema, no nested objects), the description is complete. It covers what, when, and persistence behavior. No missing aspects 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?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description reinforces purpose but does not add additional meaning beyond schema examples.

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

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

Clearly states the verb ('Store'), resource ('key-value pair in session memory'), and scope ('intermediate findings, user preferences, or context across tool calls'). Differentiates from sibling 'recall' (retrieve) and 'forget' (delete).

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

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

Explicitly says when to use ('save intermediate findings, user preferences, or context across tool calls'). While it doesn't explicitly mention when not to use or name alternative tools, the context signals indicate siblings 'recall' and 'forget' serve retrieval and deletion, providing implied 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?

No annotations provided, so description carries full burden. Discloses version (v1), input formats with examples, and output (ticker, CIK, name, URIs). Implies read-only lookup. Lacks explicit statement of no side effects, but adequate for a resolution 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: first defines high-level purpose, second details version, inputs, outputs, and benefit. Every word adds value. Front-loaded with key 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?

With no output schema, description effectively explains what is returned. Covers required inputs (type, value) and output elements. Also includes performance context (replaces 2-3 calls). Complete for a simple lookup 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 provides 100% coverage with descriptions. Description adds value by listing example inputs and clarifying that type currently only supports 'company', and value can be ticker, CIK, or name. Goes beyond schema with concrete examples and purpose context.

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

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

States the tool resolves an entity to canonical IDs across data sources. Specifies it's for company type, accepts ticker/CIK/name, and returns ticker, CIK, name, and URIs. Clearly distinguishes from sibling tools by noting it replaces 2-3 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?

Indicates when to use: when needing canonical IDs for an entity. Mentions efficiency (single call, replaces multiple calls). Does not explicitly state when not to use, but context implies it's for resolution tasks, not general Q&A (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 declare readOnly and idempotent. Description adds that it probes each entity with ai_visibility_check, returns ranked list with scores, and requires API key for Anthropic. Discloses constraints (2-8 entities).

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

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

Front-loaded with purpose, each sentence adds value (method, use case, return type). Could be slightly shorter but efficient overall.

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

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

Given 4 parameters, no output schema, and good annotations, description explains behavior, return content, and usage scenario. Missing details on error handling or limits, but adequate for the tool.

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

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

Schema has 100% coverage. Description adds context: first entity is subject, models can be omitted, _apiKey only if anthropic, context disambiguates. This goes 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?

States clear verb 'compare' and resource 'AI visibility across multiple entities side-by-side'. Distinguishes from sibling ai_visibility_check by explaining it probes multiple entities and ranks them.

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

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

Provides concrete use case ('competitive AI-marketing audits'), notes that first entity is treated as subject, and implies single-entity use should use ai_visibility_check. Could explicitly 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?

With no annotations, the description fully discloses the tool's behavior: it returns a verdict, extracted form, actual value with citation, and percent delta. It also notes the process replaces multiple steps. No contradictory or missing behavioral information.

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, each earning its place. The first sentence concisely states the purpose, and the second provides key details and value. No superfluous information.

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

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

For a simple tool with one parameter and no output schema, the description covers input, output, supported domains, and even value proposition (replacing multiple steps). It is complete and leaves no critical gaps.

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

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

The single parameter 'claim' has full schema coverage (100%). The description adds meaningful context by specifying that the claim should be natural-language and giving examples of company-financial claims, going beyond the schema's brief 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 fact-checks natural-language claims against authoritative sources, specifies the supported domain (company-financial for US companies), and lists the return elements. It distinguishes itself from siblings by noting it replaces 4-6 sequential agent 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?

The description implies usage by specifying supported claim types ('company-financial claims') and the data sources used. While it does not explicitly state when not to use it or mention alternatives, the scope is clearly defined, guiding appropriate use.

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