The Graph

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: default model (Workers AI Llama-3.3-70b), BYO key for Anthropic, and return structure (per-model score, confidence, signals, raw_response + combined view). 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?

Four sentences, front-loaded with the main action, no wasted words. Every sentence adds necessary 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 no output schema, the description covers return format well. It explains all optional parameters and use cases, making the tool fully understandable without external context.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining the default model, the purpose of _apiKey (BYO key for Anthropic), and context for disambiguation.

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

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

The description uses a specific verb 'probe' and resource 'LLMs' for knowledge about an entity, and grades visibility. It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by its focus on probing multiple models with scoring.

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

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

The description states when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and how to use optional models and API key. It does not explicitly exclude alternatives, but the context is clear enough.

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

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

Discloses that it routes across 300+ sources, picks the right tool, fills arguments, and returns the result. No annotations provided, so description carries burden. Does not mention read-only nature or failure modes, but overall behavior is 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?

Concise at about 100 words, front-loads purpose and usage. Every sentence adds value. Could be slightly more structured, but overall good.

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 simple schema (1 param, no output schema, no annotations), the description adequately covers purpose, usage, scope, and examples. Lacks details on return format or errors, but sufficient for a question-answering 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 a clear description for the param. The description adds value by providing concrete examples of questions, going beyond the schema's generic 'Your question or request in natural language'.

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

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

Clearly states it answers natural-language questions by automatically picking the right data source. Distinguishes from sibling tools which are more specific (e.g., query_subgraph, 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 describes when to use: when user asks 'What is X?', 'Look up Y', etc., and you don't want to select the specific tool. Provides examples and contrasts with manually picking a 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so description adds value by detailing operational behavior: resolves market, classifies bet, fans out to appropriate packs, returns evidence packet and comparison. No contradiction with annotations.

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

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

The description is a single paragraph that front-loads the core purpose and then details inputs, behavior, and usage examples. Every sentence is informative, though slightly verbose; could be tightened without losing meaning.

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

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

Given the tool has only 2 parameters and no output schema, the description covers purpose, input formats, behavior across bet types, and usage scenarios adequately. It is self-contained and provides enough context for an agent to use it correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces and extends schema info by explaining that 'market' accepts slug, URL, or question text, and 'depth' controls evidence sources. Adds value beyond schema.

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

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

The description clearly states it researches Polymarket bets by pulling Pipeworx data, specifying inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from sibling tools by positioning it as the core demo product for betting context, with no tautology.

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?

Explicit when-to-use scenarios: 'should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?'. It implies that agents using this tool convert better than discovering packs themselves, providing context without explicitly listing 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?

With no annotations, the description discloses data sources (SEC EDGAR, FAERS) and return type (paired data + citation URIs). It implies a read-only operation but doesn't explicitly state no side effects, which would be ideal. Overall, it provides good 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 a single paragraph that front-loads the main purpose. It is concise but could be slightly more structured (e.g., separating company vs drug details). Every sentence contributes, earning a 4.

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 only vaguely mentions 'paired data + pipeworx:// citation URIs' without specifying format or error handling. For a tool that replaces many calls, more details on output would improve completeness.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description goes beyond by explaining expected values (e.g., tickers for company, drug names) and gives concrete examples, adding significant value over 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 explicitly states the tool compares 2-5 companies or drugs side by side, with specific use case examples like 'compare X and Y' and 'X vs Y'. It distinguishes between two entity types and lists the data pulled for each, making the purpose very 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 provides clear when-to-use guidance with example queries ('compare X and Y', 'which is bigger') and states it replaces 8-15 sequential calls. However, it does not explicitly state when not to use or mention alternatives, slightly reducing the score.

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

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

No annotations are provided, so the description carries the full burden. It clearly states that it returns 'the top-N most relevant tools with names + descriptions' and implies it is a read-only search operation. However, it does not explicitly state that no data is modified, but no contradictions exist.

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 concise given the amount of information, and key points (purpose, usage guidance, domain list) are front-loaded. A minor improvement would be to separate the domain list into a bullet format, but it remains readable.

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

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

Given the tool's complexity (2 params, no output schema, many siblings), the description covers all essential aspects: what it does, when to use it, what domains it covers, and what it returns. It is self-sufficient for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by providing a concrete example for the 'query' parameter ('e.g., "analyze housing market trends"'), which helps the agent understand the expected format. The limit parameter is well-described in the schema, so no additional elaboration needed.

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 explicitly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous specific domains (SEC filings, FDA drugs, etc.) and clarifies it's for browsing/searching/discovering tools, clearly distinguishing it from siblings like 'introspect_schema' or 'recent_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 provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists when to use it (browse, search, look up) and implicitly when not (when you already know which 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?

With no annotations, the description carries full burden. It transparently lists the outputs (filings, fundamentals, patents, news, LEI) and mentions citation URIs. It is clearly a read operation. However, it does not explicitly state it is read-only or discuss 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: first states purpose and use cases, second lists outputs. It is front-loaded and concise with no wasted words.

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

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

Given no output schema, the description adequately explains what is returned. It also provides context about when to use versus alternatives. Minor omission: does not mention data limits (e.g., number of patents or news articles).

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 by explaining that type is currently limited to 'company' and that value can be a ticker or zero-padded CIK, and that names are not supported. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Get everything about a company in one call.' It provides specific example queries and enumerates the data returned (SEC filings, fundamentals, patents, news, LEI). It distinguishes from calling multiple other tools.

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

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

The description explicitly states when to use the tool: for queries like 'tell me about X' or 'research Microsoft'. It also gives a clear exclusion: if only a name is available, use resolve_entity first. This helps the agent decide between 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 carries the full burden. It clearly indicates the tool is destructive ('Delete') and for clearing sensitive data. It could mention irreversibility, but the word 'delete' is sufficiently transparent for a single-parameter 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 three sentences, each serving a clear purpose: action, use cases, and pairing advice. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and relationships to siblings. It is fully 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?

The schema covers 100% of the parameter with a description for 'key'. The description adds minimal context ('by key'). Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Delete a previously stored memory by key'. It uses a specific verb and resource, and distinguishes itself from sibling tools like 'remember' and 'recall' by mentioning them as complementary tools.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', guiding when not 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?

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by stating it fetches the page, extracts title/description/key links, and emits markdown format. This provides behavioral context beyond annotations.

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

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

The description is two sentences long, front-loaded with the core purpose, and includes additional context in a clear, scannable format. No unnecessary words.

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

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

Given the simple tool with two parameters, no output schema, and good annotations, the description covers all necessary aspects: what it does, how it works, and typical use cases. 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?

Schema coverage is 100% for both parameters: url and max_links. The description does not add additional meaning beyond the schema's descriptions, which is adequate. Baseline score of 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 tool generates a production-ready llms.txt file for any URL, explaining its purpose and output format. It distinguishes itself from sibling tools which cover unrelated functionalities like betting, research, or entity management.

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 (indexing client sites, drafting for own projects, auditing competitors), giving clear context for when to use. However, it does not mention alternatives or when not to use, which would make it a 5.

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

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

No annotations; the description discloses it is a read-only introspection returning schema structure, but fails to mention authorization, rate limits, or potential errors.

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

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

Two sentences, front-loaded with action, no extraneous wording.

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?

Adequate for a simple one-parameter tool; covers return value and purpose, but omits error conditions or response format details.

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%; the description adds minimal value beyond the schema's 'Subgraph deployment ID', merely restating the resource context.

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

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

The description clearly states the tool fetches a subgraph's GraphQL schema via introspection, specifying the resource and action distinct from siblings like query_subgraph.

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 building queries without external docs, but lacks explicit when-not-to-use or alternatives beyond implied 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It clearly states rate limits (5 per identifier per day), that it doesn't count against tool-call quota, and that feedback is reviewed daily and influences the roadmap. There are 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 a single, well-structured paragraph that front-loads the purpose. Every sentence adds value: it covers when to use, what to include, constraints, and impact. No wasted words.

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

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

Given the complexity (3 params, nested object, no output schema), the description is thorough. It explains usage context, constraints (rate limits, quota), expected input format, and the feedback process. No additional information is needed for an agent to use the tool 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%, so baseline is 3. The description adds meaning beyond the schema by briefly explaining each enum value (bug, feature, data_gap, praise) and providing tips for writing the message (be specific, 1-2 sentences, 2000 chars max). This enhances parameter 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 clearly states the tool's purpose: to send feedback about bugs, features, data gaps, or praise. It specifies the resource (Pipeworx team) and verb (tell), and distinguishes from sibling tools by focusing on feedback about the tool ecosystem rather than queries or 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 explicitly lists when to use the tool (bug, feature/data_gap, praise) and provides guidance on what not to do (e.g., don't paste end-user prompts). It also mentions rate limits and that it's free, helping the agent decide when to invoke 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?

Annotations already mark readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: data derived from CF analytics-engine, no PII, caching of 5min-1h depending on window. No contradictions, and description significantly supplements annotations.

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

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

Two sentences. First sentence states core functionality. Second sentence lists three concrete use cases with bullet clarity. Additional detail on source and caching is compact and relevant. Every sentence earns its place with no redundancy.

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

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

Despite no output schema, the description fully explains return structure ('just (pack, tool, count)'). With one simple parameter, clear use cases, and caching info, the description is complete and leaves no ambiguity for selection or 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?

Only parameter 'window' has full schema coverage with enum. Description adds semantic nuance: shorter windows for 'what's hot right now', longer for 'steady-state demand'. This enriches the schema's static enum definition.

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 recent window. The verb 'returns' and resource listing are specific. Sibling tools like 'discover_tools' or 'entity_profile' are distinct, and the description explains this tool's unique purpose of showing trending data based on aggregate usage.

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 three explicit use cases: discovering hot data sources, confirming canonical tool choices, and checking alignment with agent trends. Also implicitly advises when not to use (e.g., for detailed tool info). Caching behavior is noted, aiding timing decisions.

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 mark the tool as read-only and non-destructive. The description adds behavioral details: it walks child markets, extracts dates/thresholds, sorts them, and reports violations. This 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 a single paragraph of around 5 sentences. It opens with the main purpose, explains the logic, and ends with the return format. It is informative without being verbose, though it could be slightly more terse.

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

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

With no output schema, the description explicitly states the return structure. Input is simple with one parameter. Annotations cover safety and openness. The description is fully sufficient for an agent to understand and invoke the tool 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?

The input schema already describes the single parameter as a 'Polymarket event slug or URL' (100% coverage). The description provides an example and explains how the parameter is used (to walk child markets), adding minor value beyond the schema.

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

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

The description clearly states the action ('Find arbitrage opportunities'), the resource ('Polymarket event'), and the specific method ('monotonicity violations'). It distinguishes the tool from siblings by focusing on price ordering violations in related markets.

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

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

The description provides clear context: use this tool when an event has multiple 'by date' or 'by threshold' markets, and explains the condition for arbitrage. It does not explicitly list exclusions or alternatives, but the specificity makes usage clear.

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

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

Annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false) are enhanced by the description, which details data sources (FRED, coinpaprika), model (lognormal), process (scans top markets, groups by asset, fetches price history ONCE), and output (ranked by |edge| with direction). There is no contradiction; the description adds rich behavioral context beyond the 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 four sentences, front-loaded with the overall purpose, then details. Each sentence adds value without redundancy. It is concise and well-organized.

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

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

Despite no output schema, the description explains the return (top N ranked by edge magnitude with suggested trade direction). It covers input, process, and output comprehensively for a tool that combines multiple data sources and computations. Agents have sufficient context to invoke the tool 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% with good descriptions for all three parameters (limit, window, min_edge_pp). The description reiterates the purpose of limit and min_edge_pp but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate as the schema already handles parameter explanation.

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

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

The description clearly states the tool scans high-volume Polymarket markets, finds where Pipeworx data disagrees with market price, ranks by edge magnitude, and returns top N with suggested trade direction. It specifies asset type (crypto-price bets), model (lognormal from FRED + coinpaprika), and algorithm. 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 includes 'Built for the "what should I bet on today" question — agents/users discover opportunities without paging through hundreds of markets by hand,' which implies when to use it for opportunity discovery. However, it does not explicitly state when not to use or compare to alternative tools like polymarket_arbitrage or query_subgraph.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it explains the two modes, how parameters interact, and the return format (leg-by-leg prices and spread). 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 slightly longer but each sentence adds useful information. It front-loads the main purpose, then explains modes and return format. Could be tightened slightly but still effective.

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 lack of output schema, the description clearly explains what the tool returns (leg-by-leg prices and spread). It covers modes, parameter interactions, and the context of the arbitrage signal. Fully 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?

With 100% schema description coverage, the schema already documents each parameter. The description adds semantic value by explaining how the modes work, that explicit parameters override topic mappings, and providing the return context (prices and spread).

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 cross-venue spread between Kalshi and Polymarket. It explains the two modes (topic shortcuts and explicit tickers) and distinguishes this tool from siblings like 'polymarket_arbitrage' and 'compare_entities' by focusing on the specific arbitrage 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?

The description provides good guidance on when to use each mode: topic for pre-mapped macros and explicit for custom pairings. However, it does not explicitly state when not to use this tool or mention alternatives, though the context of sibling tools partially covers this.

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 must reveal behavior. It states the return value (data block plus errors) but omits details on network call timeouts, rate limits, or whether it's read-only (inferred but not explicit). Adequate but not thorough.

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

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

The description is two sentences, front-loading the action and then providing key context. No redundant information. Highly 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 query-only tool with no output schema, the description explains what is returned (data block + errors). Missing details on error structure or pagination are acceptable given simplicity. Could mention idempotency, but overall adequate.

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 minor value by clarifying subgraph_id formats. The description for 'query' and 'variables' essentially echoes the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Run a GraphQL query'), the target ('a subgraph on The Graph network'), and the tool's unique role. No sibling tool performs this function, so differentiation is inherent.

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 context for the subgraph_id format and where to find it, implying when the tool is used. However, it does not explicitly list prerequisites, alternatives, or when not to use it. Since no direct sibling exists, the lack of exclusions is acceptable.

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

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

With no annotations provided, the description carries the full burden. It implies a read operation ('Retrieve') but does not explicitly state that it does not modify state or disclose any side effects. It mentions scoping to an identifier, which adds some 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, all relevant and front-loaded with the essential action. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity and lack of output schema, the description adequately covers usage. It does not explain the return format or error handling, but for a retrieval tool, the core functionality is clear.

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 full coverage for its single parameter, so baseline is 3. The description adds value by explaining that omitting the key lists all saved keys, which is not in 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?

The description uses specific verbs 'retrieve' and 'list' and clearly states the resource: values saved via remember and saved keys. It distinguishes from siblings like remember (save) and forget (delete) by naming them.

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

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

The description provides clear context for when to use this tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and mentions pairing with remember and forget. It does not explicitly state when not to use, 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 are provided, so the description carries full burden. It discloses that the tool fans out to SEC EDGAR, GDELT, and USPTO in parallel, and returns structured changes with count and citation URIs. It does not cover rate limits, authentication needs, or error cases, but the behavioral description is adequate for an agent to understand the tool's 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 a single paragraph that efficiently packs essential information: purpose, example queries, sources, parameter formats, and return value shape. It is concise and front-loaded with the use case, though it could be slightly more structured with bullet points.

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 moderate complexity (3 parameters, no output schema), the description covers the tool's purpose, input semantics, and output shape reasonably well. It lacks details on error handling or limitations beyond the 'company' type restriction, but overall it is sufficiently complete for an agent to use the tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the 'since' parameter accepts ISO dates or relative shorthand with examples, and clarifies that 'type' only supports 'company'. This goes 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 the tool answers 'what's new with a company' and provides concrete example queries. It specifies a specific verb ('what's happening with', 'any updates on') and resource ('company'). It distinguishes from siblings like 'entity_profile' and 'compare_entities' 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 provides explicit example queries and states 'Use when...', giving clear context for when to invoke. It doesn't explicitly state when not to use or name alternatives, but the examples cover the intended use cases sufficiently.

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

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

No annotations provided, so the description carries the burden. It discloses key-value scoping, persistence differences between authenticated and anonymous sessions, and retention duration. However, it does not mention behavior on duplicate keys (overwrite vs error), which is a minor gap.

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, front-loaded with the purpose, no wasted words. Every sentence adds essential information.

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

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

No output schema, but the description is sufficient for a store tool. It explains scoping, persistence, and retrieval pairing. Minor gap: no mention of return value or success indication.

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

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

Input schema has 100% coverage, so the baseline is 3. The description adds value by providing examples for key and value, enhancing understanding 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 saves data for reuse, with a specific verb ('Save') and resource ('data'). It distinguishes itself from sibling tools like recall and forget.

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

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

Explicitly says when to use ('when you discover something worth carrying forward'), provides examples, and mentions pairing with recall and forget, offering clear context for 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 that the tool returns IDs plus citation URIs and implies read-only behavior (lookup). However, it does not explicitly state that there are no side effects, nor does it mention error handling or permissions. The description is mostly transparent but lacks explicit safety 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?

The description is concise (3 sentences) and front-loaded: first sentence states purpose, second gives examples, third provides procedural guidance. Every sentence is informative and necessary, with no redundancy or fluff.

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

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

The tool is simple (2 params) and has no output schema. The description explains return values (IDs and citation URIs) and gives examples, which is sufficient for an agent to understand the output. However, it lacks details on error handling or edge cases (e.g., ambiguous inputs). Overall, it is 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 parameter descriptions, so baseline is 3. The description adds value by explaining the purpose of each parameter with examples (e.g., 'For company: ticker (AAPL), CIK (0000320193), or name.'), making parameter usage clearer for the agent.

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 explicitly states it looks up canonical/official identifiers for company or drug, lists specific ID systems (CIK, ticker, RxCUI, LEI), and provides concrete examples. It distinguishes from siblings by noting it replaces 2-3 lookup calls and should be used before other tools needing official identifiers.

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 clearly specifies when to use the tool: 'Use when a user mentions a name and you need the CIK... the ID systems that other tools require as input.' It also gives sequential guidance: 'Use this BEFORE calling other tools that need official identifiers.' This provides both context and exclusion criteria.

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

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

The description discloses internal behavior (calls ai_visibility_check internally), return structure (ranked list with score, confidence, signal density), and treats the first entity as the subject. This adds significant context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false).

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 extraneous words. Every sentence provides essential information about functionality, use case, and output.

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 (4 params, no output schema), the description adequately covers parameter meanings (entities, models, apiKey, context) and return format (ranked list with scores). Combined with annotations, it provides sufficient information for an agent to use correctly.

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

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

The schema already describes all parameters (100% coverage). The description adds valuable usage context: entities limited to 2-8, first is subject, models: 'workers-ai' default vs 'anthropic' requiring apiKey, and context disambiguates common names. This enhances understanding beyond raw schema.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, specifies it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This specific verb+resource combination distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (broader).

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 a concrete use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use this tool or compare it with siblings like compare_entities, leaving room for ambiguity.

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

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

No annotations are provided, so the description carries the full burden. It lists the return verdicts and mentions that the tool replaces 4-6 sequential calls, implying efficiency. However, it does not explicitly state that the tool is read-only, its safety profile, or any rate limits or authentication requirements.

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

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

The description is concise, front-loading the main purpose and key details in 4 sentences. Every sentence adds value: purpose, use case, scope, return value, and efficiency gain. No unnecessary words.

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

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

Given the single parameter and absence of output schema, the description provides good context: input format, return verdicts, scope limitation, and efficiency. It could mention handling of ambiguous claims or units but is largely 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 description coverage is 100%, so the baseline is 3. The tool description adds value by providing examples of the claim parameter (e.g., 'Apple's FY2024 revenue was $400 billion') but does not offer additional semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose: to fact-check, verify, validate, or confirm/refute natural-language factual claims against authoritative sources. It provides specific verbs and resources ('validate_claim'), distinguishes itself from sibling tools by addressing fact-checking needs, and gives concrete examples of 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 explicitly states when to use the tool ('when an agent needs to check whether something a user said is true') and provides example queries. It also specifies the current domain scope (company-financial claims) but does not enumerate when not to use it or mention alternative tools.

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