Bis

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

Annotations (readOnly, openWorld, idempotent, non-destructive) are consistent with description. Description adds behavioral details like default model, API key passthrough, and return structure (per-model fields + combined view), enhancing transparency.

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

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

Three sentences: front-loaded with purpose, then key details (default model, optional key), then use cases. No extraneous words; every sentence adds value.

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

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

Despite no output schema, the description outlines return structure (per-model fields + combined view). Parameters and behavior are fully covered. No gaps for an agent to 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% with good descriptions. The description adds meaning by explaining the _apiKey parameter's role (BYO key, pay directly) and the context parameter's purpose (disambiguation), going 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 starts with a specific verb ('Probe') and resource ('LLMs for what they know about a business/brand/product/topic'), and clearly states the output (visibility score 0-100). It distinguishes from sibling tools by focusing on AI brand awareness measurement.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default vs. extended functionality (Workers AI free, Anthropic requires API key). However, it does not explicitly state when not to use or compare to siblings.

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

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

No annotations are provided, so the description bears the full burden. It mentions that Pipeworx picks the right tool, fills arguments, and returns the result, but lacks detail on behavior like error handling, latency, authentication needs, or read-only nature. This is adequate but not rich.

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

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

The description is two paragraphs with clear front-loading: first sentence states purpose, then usage guidelines and examples. It is fairly concise with no wasted words, though slightly longer than necessary.

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

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

Given a single parameter, no output schema, and no annotations, the description covers purpose, when to use, and example queries. It mentions the breadth of sources, which is sufficient context for a straightforward query 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?

The input schema has 100% coverage with one 'question' parameter described generically. The description adds significant meaning by providing examples of question types and mentioning the range of sources, which helps the agent understand what constitutes a valid query.

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 natural-language questions by picking the right data source, with specific verb 'Answer' and resource 'natural-language question'. It distinguishes from sibling tools by highlighting automatic routing across 300+ sources, avoiding the need to figure out which Pipeworx tool to call.

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 ('Use when...') and provides example queries that trigger usage. It implies alternatives by noting you don't need to figure out which tool to call, but does not explicitly mention when not to use or list specific sibling 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?

Description details behavioral steps: resolves market, classifies bet, fans out to packs, returns evidence packet and comparison. Annotations already indicate read-only and non-destructive. Could mention external dependencies or time bounds, but overall strong.

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, each adding value. Front-loaded with core purpose. Slightly verbose but justified given the complexity; could tighten phrasing.

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

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

No output schema, but description adequately explains return: evidence packet and market-vs-model comparison. Could specify return format (e.g., JSON) but sufficient for agent 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%. Description explains market parameter accepts slug, URL, or text, and depth parameter enum values 'quick' vs 'thorough' with their meanings, adding value beyond schema.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific verb and resource. It distinguishes from siblings like validate_claim by focusing on Polymarket bets.

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

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

Explicitly lists use cases ('should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?') and implies alternatives by stating this tool is better for bet-relevant 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?

No annotations provided, so description carries full burden. Explains data sources (SEC EDGAR/XBRL, FAERS) and returned metrics but omits behavioral details like authorization needs, error handling, or pagination. Partially adequate.

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

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

Description is front-loaded with core purpose, then usage triggers, then type-specific details. Efficient overall but could be slightly more concise.

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 exists; description partially explains returns ('paired data + citation URIs'). Covers main two modes but lacks details on input format specifics (e.g., tickers vs CIKs) and error scenarios. Adequate but not exhaustive.

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%. Description adds value by providing examples and clarifying data sources per parameter type beyond the schema's basic descriptions.

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

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

The description clearly states the tool compares 2–5 companies or drugs side by side, uses specific verbs ('Compare'), and distinguishes from siblings like entity_profile (single entity) and fetch_dataset (generic data).

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

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

Explicitly lists user query triggers ('compare X and Y', 'X vs Y', etc.) and differentiates between company and drug types. Does not explicitly mention alternatives among siblings but covers usage context 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?

No annotations provided, so description bears full responsibility. It indicates read-like behavior and mentions 'top-N' results, but lacks details on authentication, result ordering, or pagination. Adequate but not comprehensive.

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 efficient and front-loaded, but the list of domains makes it slightly longer than necessary. Still, every sentence contributes 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's simplicity (2 parameters, no output schema), the description covers purpose, usage, parameter semantics, and strategic context thoroughly. No gaps remain.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining query examples ('analyze housing market trends') and hinting at limit's role ('top-N'), going 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 clearly states the tool's purpose with specific verbs like 'browse, search, look up, discover' and lists numerous data domains. It distinguishes itself from sibling tools by targeting tool discovery, not data 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?

Explicitly advises when to use the tool ('when you need to browse, search, look up, or discover what tools exist') and provides a strategic recommendation to call this first when many tools are available, indicating when not to use it for direct answers.

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

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

With no annotations provided, the description carries the full burden. It discloses exactly what data is returned (SEC filings, fundamentals, patents, news, LEI) and mentions the output includes pipeworx:// citation URIs. The limitation of only 'company' type supported is stated. Missing explicit statement about read-only behavior (assumed safe), but safe given no destructive hint.

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 moderately long but well-structured: it starts with the core purpose, lists use cases, summarizes returns, and ends with input format. Every sentence adds value, though some readability could be improved by splitting into shorter sentences. Still efficient for the information density.

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 thoroughly explains the return values (SEC filings, fundamentals, patents, news, LEI) and mentions citation URIs. It covers limitations (only company type, names not supported) and provides alternative for name resolution. The complexity of aggregating multiple data sources is appropriately addressed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'type' enum (only 'company' supported, others coming soon) and that 'value' must be a ticker or CIK, not a name. It also directs to resolve_entity for name inputs, which is helpful 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 uses a specific verb ('Get everything about a company') and resource ('in one call'), clearly distinguishing it from sibling tools by noting it replaces calling 10+ pack tools across multiple domains. Examples of user queries ('tell me about X', 'research Microsoft') further clarify its 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 explicitly states when to use (user asks for company profile) and when not to use (if only have a name, use resolve_entity first). It provides clear input constraints (ticker or CIK only) and mentions an alternative sibling tool by name.

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 must fully disclose behavior. Mentions 'tidy rows' but lacks details on idempotency, limits, caching, or auth. Adequate but not comprehensive.

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, each sentence adds value. Could be slightly more structured but 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 5 params and no output schema, description provides sufficient context to use correctly. Could add more about return format or pagination, but not strictly required.

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

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

Schema coverage is 100% (baseline 3). Description adds concrete examples for flow_ref, key, and period formats, which adds meaning beyond the generic 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?

Clearly states 'Fetch tidy rows from a BIS dataflow' with specific verb and resource. Provides examples of flow_ref and key format, and distinguishes from sibling tools like search_dataflows which are for metadata.

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?

Includes parameter usage examples for start_period/end_period and key format, guiding proper invocation. Does not explicitly mention when to use versus alternatives, but context with siblings implies uniqueness.

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?

Clearly indicates the destructive nature ('delete') and implies the memory must exist ('previously stored'). However, does not specify behavior if the key does not exist (e.g., error or no-op). For a simple tool, this is minor but could be improved.

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: action, usage context, sibling pairing. No extraneous information; front-loaded with verb and resource.

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

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

Given the simplicity (1 param, no output schema), the description covers purpose, usage, and how it fits with sibling tools. It is complete for an agent to understand when and why to use it.

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 the key parameter described as 'Memory key to delete'. The description does not add additional parameter semantics beyond the schema, so baseline score 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 'a previously stored memory by key'. It distinguishes itself from siblings 'remember' (store) and 'recall' (retrieve) by focusing on deletion.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with 'remember' and 'recall' for complete workflow, giving clear context.

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

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

The description discloses key behaviors: fetching the page, extracting title/description/key links, and emitting the standard llms.txt format. This adds significant context beyond the annotations (readOnlyHint, etc.), which only indicate safety and idempotency.

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 well-structured: first sentence states the core function, second describes the process and output, third lists use cases. No unnecessary words.

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

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

For a tool with no output schema, the description adequately explains the output format and what the tool extracts. It could mention error handling or limitations, but the given information is sufficient for an agent to decide to use it.

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?

Both parameters are fully described in the input schema (100% coverage). The description adds no further semantics beyond what the schema already provides, 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?

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and use cases. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation.

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 explicit use cases (getting client site indexed, drafting for own project, auditing competitors). However, it does not mention when not to use or provide alternative tools, which would elevate it to 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?

With no annotations, the description should detail behavioral traits like side effects, data freshness, or pagination. It only mentions 'pre-vetted' but does not explain implications. A list operation is inherently safe, but transparency could be improved.

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

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

Two sentences, no wasted words. The first sentence states the action and grouping, the second provides usage guidance and alternatives.

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 list tool with one optional parameter and no output schema, the description covers purpose, grouping, and usage guidance. It does not detail the return format, but that may be inferred from context. Slightly lacking in 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 schema has 100% coverage with one optional 'topic' parameter. The description adds value by listing valid topic values (rates, fx, etc.), though it does not explicitly say the parameter filters by these values. The agent can infer the connection.

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 lists pre-vetted BIS dataflow refs grouped by topic, and explicitly lists the topics. It distinguishes itself from sibling tools by directing users to search_dataflows for other needs.

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

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

Provides explicit when-to-use (for pre-vetted BIS dataflows) and when-not-to-use (everything else, recommending search_dataflows or a URL). This gives clear guidance for the agent.

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

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

With no annotations, the description carries full burden. It discloses rate limits (5/identifier/day), free usage (no quota impact), team reading frequency (daily digests), and roadmap impact. It also warns about what not to include (end-user prompts), ensuring proper usage.

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

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

The description is well-structured and front-loaded with purpose, then usage, then behavior. While thorough, a few sentences could be tightened (e.g., the purpose is restated in the type descriptions). Still, it remains efficient and clear.

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

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

Given the tool's simplicity (3 params, no output schema, no annotations), the description fully covers purpose, usage, parameter semantics, limitations, and impact. Missing a confirmation note is minor; the description is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds meaning by explaining enum values in context, clarifying the optional context object's fields (pack, tool, vertical), and advising on message formatting (specific, 1-2 sentences, 2000 chars max). 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb-resource relationship and distinguishes it from data-retrieval siblings by focusing on feedback. Examples of scenarios (bug, feature, data_gap, praise) add clarity.

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

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

The description explicitly defines when to use the tool: for bugs, feature requests, data gaps, or praise. It advises against pasting end-user prompts and provides rate-limit and quota information, giving clear contextual 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?

Description adds context beyond annotations: it explains the data source (CF analytics-engine), confirms no PII, and specifies cache duration (5min-1h). This aligns with the readOnlyHint, idempotentHint, and destructiveHint annotations, with 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 core purpose, and every sentence provides useful information. A few lines are slightly verbose but overall well-structured 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?

Given the tool's simplicity (one parameter, no output schema, good annotations), the description is fully complete: it covers purpose, usage, parameter semantics, and behavioral details. No gaps remain.

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

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

Schema already has full coverage (100%) with description for the 'window' parameter. Description adds extra context by explaining the effect of shorter vs longer windows, which adds 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?

Description clearly states it returns 'top tools, top packs, and total call volume' – specific verb and resource. It distinguishes from siblings by focusing on trending usage data, which is unique among the listed siblings.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical choice, checking alignment) and provides guidance on window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). Also mentions caching behavior.

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

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

Annotations already indicate read-only, non-destructive, open-world. Description adds behavioral context: it returns ranked opportunities with reasoning. 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?

Concise yet dense with information. First sentence states purpose, then explains the two modes with examples. 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?

Given the tool's complexity (two modes, monotonicity logic) and lack of output schema, the description fully explains what the tool does and what it returns (ranked opportunities with reasoning). 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. Description adds examples of each parameter and explains the mode they enable, providing extra semantic value beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: find arbitrage opportunities via monotonicity checking. It distinguishes two modes (event vs topic) and explains the cross-event mode's advantage over single-event, differentiating it from sibling tools 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?

Explicitly states when to use each mode: pass an event slug for single-event, or a topic for cross-event. It describes the limitation of single-event mode and suggests the alternative, providing clear when-to-use guidance.

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

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

The description adds significant behavioral detail beyond annotations: it explains the algorithm (scans top markets, groups by asset, fetches price history once, computes model probability, ranks by edge), the model used (lognormal from FRED + coinpaprika), and the output (top N with suggested trade direction). This aligns with readOnlyHint and destructiveHint annotations without contradiction.

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

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

The description is front-loaded with the main purpose and is well-structured, but it includes some extra details (e.g., 'V1 covers crypto-price bets...') that could be trimmed. Still, it remains informative and not overly verbose.

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

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

Given the tool's complexity and lack of output schema, the description fully explains the algorithm, model, output, and use case. It covers the scope (crypto-price bets), default behaviors, and differentiators. No gaps are evident for an AI agent to decide when to use it.

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

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

Schema description coverage is 100%, with each parameter described clearly (limit, window, min_edge_pp). The description provides context for the parameters but does not add new meaning beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description clearly states the verb (scan, return), the resource (highest-volume Polymarket markets), and the specific function (return those where Pipeworx data disagrees with market price). It distinguishes from sibling tools like polymarket_arbitrage and bet_research by focusing on edge-based opportunities.

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

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

The description explicitly frames the tool for the 'what should I bet on today' question, indicating when to use it for opportunity discovery. It does not explicitly mention when not to use it or list alternative sibling 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?

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable context: explains the arbitrage signal, that it returns leg-by-leg prices in raw probability, and spread in percentage points. No contradictions.

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

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

Well-structured with two modes clearly delineated. Every sentence adds value (purpose, why arb exists, modes, return format). Could be slightly more streamlined but is 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?

No output schema, so description must explain returns, which it does (leg-by-leg prices and spread). Covers both modes and the rationale. Minor omissions like error handling or limits, but 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%, so baseline is 3. The description adds meaning by listing the pre-mapped topic values and explaining that explicit parameters override topic-mapped sides, which is 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?

Clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', providing a specific verb (spread) and resource (cross-venue prices). This distinguishes it from siblings 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?

Explicitly describes two modes (topic shortcuts vs explicit tickers) with clear guidance on when to use each. However, it does not explicitly contrast with sibling tools or state 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?

No annotations provided; description covers key behavioral traits: it is a read operation ('retrieve'), scoped to user identifier, and returns either a saved value or list of keys. Does not detail error behavior for missing keys, but adequate for a simple retrieval tool.

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

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

Three sentences, front-loaded with the core action and use case. Every sentence adds value (purpose, usage example, scoping, pairing). Could be slightly shorter but no extraneous content.

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

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

Given no output schema, the description explains return behavior (value or list of keys). Covers scoping, pairing with related tools, and usage context. Complete enough for a simple memory retrieval tool with one optional parameter.

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 with a clear description for the single parameter 'key.' The description adds context (omit to list all keys) but does not provide additional semantic meaning beyond the schema. 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?

Clearly states the verb 'retrieve' and the object 'value previously saved via remember.' Distinguishes from siblings by explicitly naming 'remember' and 'forget' and describing behavior when key is omitted (list all keys).

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

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

Provides explicit usage examples (ticker, address, research notes) and hints at when to use ('without re-deriving from scratch'). Mentions scoping but does not list explicit alternatives or when-not-to-use conditions beyond the 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?

Discloses the parallel fan-out to three data sources (SEC EDGAR, GDELT, USPTO) and the return structure (structured changes, count, URIs). Since no annotations are provided, the description carries the full burden and handles it well. No side effects or destructive actions implied.

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 tightly written sentences, no redundancy. Front-loads the purpose and then provides essential detail. Every sentence adds value.

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

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

With no output schema, the description adequately explains the return values (structured changes, total_changes count, URIs). It covers the main aspects an agent needs to know. Could mention any limitations or error conditions, but overall sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra clarity by detailing the 'since' parameter format with examples (ISO dates, relative shorthand like '7d', '30d'), and provides concrete examples for 'value' (AAPL, CIK). 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?

Clearly states the tool's function as retrieving recent changes for a company, with specific example queries and explicit differentiation from static profile tools like entity_profile. The description is unambiguous and context-rich.

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

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

Provides explicit usage guidance with example user intents ('what's happening with X?', 'any updates on Y?') and even example queries. Does not explicitly state when not to use, but the context is clear enough. Lacks direct sibling comparison, but the examples effectively convey appropriate scenarios.

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, description discloses key behaviors: key-value storage, scoping by identifier, persistence differences between authenticated and anonymous users. Does not state overwrite behavior on duplicate keys, but overall 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 a single paragraph with no wasted words. Each sentence adds critical information: purpose, usage cues, scoping, persistence, and sibling tools. 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 simple two-parameter tool with no output schema, the description provides all necessary context: how data is stored, retention policies, scope, and relationships with siblings. Nothing essential is missing.

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

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

Schema covers 100% of parameters with descriptions, but description adds value by providing concrete examples for 'key' (e.g., 'subject_property') and clarifying 'value' accepts any text. This helps the agent understand 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?

Description clearly states 'Save data the agent will need to reuse later' with specific examples like 'resolved ticker, target address'. It distinguishes from siblings by mentioning recall and forget, making the tool's 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?

Explicitly says 'Use when you discover something worth carrying forward' and explains scoping and persistence. No explicit 'when not to use' but 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?

No annotations; description compensates by stating it returns IDs and citation URIs, and that it replaces multiple calls. As a lookup, non-destructive is implied.

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 four sentences: main purpose, details, usage instruction, efficiency note. Front-loaded with verb and resource.

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

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

No output schema; description fully explains return values (IDs + citation URIs) and workflow placement. Complete for a 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 covers 100% of parameters; description adds value by giving examples of valid inputs for `value` (ticker, CIK, name for company; brand or generic for drug) and clarifies the `type` enum.

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

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

Description clearly states the tool resolves entities to canonical identifiers (CIK, ticker, RxCUI, LEI) and provides examples. It distinguishes from siblings by emphasizing use before other tools needing IDs.

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 when to use (when user mentions a name needing a specific ID system) and instructs to use before other tools. 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?

Annotations already declare readOnly, idempotent, and non-destructive properties. The description adds behavioral context: it probes each entity, ranks by score, and returns a list. No contradictions with annotations.

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

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

The description is concise with four sentences, front-loading the main action. Every sentence adds value with no redundancy. It is well-structured and easy to parse.

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

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

Despite no output schema, the description specifies the return format (ranked list with score, confidence, signal density per entity). It covers the tool's behavior and process sufficiently for an agent to understand and invoke 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?

Input schema has 100% description coverage, so baseline is 3. The description does not add significant extra meaning beyond the schema; it repeats the concept of 'first entry as subject' which is already in 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 compares AI visibility side-by-side across multiple entities, probes with ai_visibility_check, ranks scores, and surfaces most/least recognized. It explicitly differentiates from the sibling tool ai_visibility_check by indicating this tool handles multiple entities.

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

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

The description provides a use case example ('competitive AI-marketing audits') and implicitly indicates that for single entity checks one should use ai_visibility_check. Could be more explicit about when not to use this tool, but usage 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 provided; description carries burden. It correctly implies a read-only search but does not explicitly state safety or side effects. Adequate for a simple search 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, front-loaded with action and resource, zero 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?

Mentions return type (flow_refs) and next step (pass to fetch_dataset). Lacks details on pagination or ordering, but sufficient for the tool's simplicity.

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

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

Schema coverage is 100%, so description adds minimal value beyond schema. Restates 'keyword matching dataflow name' matching query param 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?

Explicit verb 'search' and resource 'dataflow registry' with clear output 'flow_refs ready to pass to fetch_dataset'. Distinguishes from sibling tools like fetch_dataset and list_curated_flows.

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?

Implies usage chain (search then fetch) by describing output format. No explicit when-not-to-use or alternative guidance, 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?

With no annotations provided, the description carries full burden. It discloses the output format (verdict, structured form, actual value with citation, percent delta) and notes it replaces 4-6 calls. It does not mention side effects, idempotency, or logging, but transparently describes the behavior well.

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

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

The description is concise, front-loaded with the action, and every sentence provides necessary information without redundancy. Four sentences cover purpose, usage, scope, and output efficiently.

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

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

For a single-parameter tool with no output schema or annotations, the description is remarkably complete. It explains precisely what inputs are expected, how they are processed, what outputs are returned, and the domain scope. No critical gaps remain.

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 already describes the 'claim' parameter. The description adds value by specifying the supported claim scope (v1 company-financial claims via SEC EDGAR + XBRL), which goes beyond the schema's general 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's purpose: fact-checking natural-language claims against authoritative sources, specifically company-financial claims. It distinguishes from siblings like 'entity_profile' and 'resolve_entity' by being a specialized validation tool that replaces multiple 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?

The description explicitly states when to use ('when an agent needs to check whether something a user said is true') and provides examples. It also confines usage to company-financial claims, providing clear context, but does not mention when not to use or compare to specific sibling tools.

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