Homebrew Formulae

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds no additional behavioral details such as edge cases, response format, or implications of missing parameters. It simply restates the trivial fact of counting installs.

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 too short to be considered concise. While brevity is valuable, this entry is under-specified and does not provide enough context for effective tool selection. A single phrase without verbs or structure is not useful.

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 optional parameters, no output schema), the description should at least explain what counts are returned and the role of each parameter. It fails to meet even this minimal requirement, leaving the tool functionally opaque.

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 0% schema description coverage and no parameter explanations in the description, the agent has no insight into what 'cask' or 'days' means. The description does not compensate for the lack of schema information, leaving the agent to guess parameter semantics.

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

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

The description 'Cask install counts' is extremely vague. It does not specify what kind of counts (e.g., total, per day) or how the tool differs from siblings like 'analytics_install' or 'cask'. A clear verb and resource are missing; the phrase is more of a label than a functional description.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it. The description gives no indication of the typical use case or limitations.

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 and openWorldHint, but the description adds no behavioral context beyond that. It does not explain what 'install counts' entails or any limitations.

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?

Very short, no wasted words, but the brevity sacrifices clarity. The single sentence conveys minimal 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, and the description fails to explain what the return data contains (e.g., format, fields). The term 'install counts' is ambiguous without elaboration.

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 50% (days has a description, formula has none). The description adds meaning to formula ('scope' with it, omit for top list), improving over the schema. However, days remains only schema-described.

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 'Install counts' is vague, but the additional phrase 'Pass formula to scope, or omit for top list' clarifies it retrieves install counts, possibly for formulas. It does not explicitly distinguish from sibling tools like analytics_cask_install.

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 some guidance: use 'formula' to scope to a specific formula, or omit for a top list. However, no when-to-use or when-not-to-use compared 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?

Annotations already indicate readOnly=true, openWorld=true, destructive=false. The description enriches this by explaining the internal routing, argument filling, and citation URI generation, providing behavioral insight far 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 a single focused paragraph that starts with the key instruction 'PREFER OVER WEB SEARCH'. Every sentence adds information: purpose, scope, internal mechanics, and concrete examples. No fluff or repetition.

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 (orchestrating 1,423+ tools), the description is remarkably complete. It covers the input (natural language question), the process (routing, argument filling), and the output (structured answer with citation URIs). No output schema exists, but the description adequately describes the return value.

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

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

The single parameter 'question' is well described in the schema. The description adds value by specifying the types of questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and clarifying that the tool interprets natural language requests, which enhances the schema's baseline.

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

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

The description uses specific verbs like 'routes', 'fills arguments', 'returns structured answer' and clearly identifies the resource as a meta-tool for 1,423+ domain-specific tools. It distinguishes itself from web search by stating 'PREFER OVER WEB SEARCH', making the purpose unmistakable.

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 prefer this tool over web search and lists example use cases covering numerous domains. It does not explicitly state when not to use it, but the strong preference language and broad coverage imply it should be used for factual structured data queries.

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

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

Adds significant behavioral context beyond annotations: resolves the market, classifies bet type, fans out to appropriate data packs, and returns evidence plus comparison. Annotations (readOnlyHint, openWorldHint, destructiveHint) are consistent with the description, and the description provides rich process detail.

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 somewhat long but front-loaded with the core action. Every sentence adds value, though some internal process details (e.g., classification, fan-out logic) could be streamlined without losing clarity.

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

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

Despite no output schema, the description fully explains return values (evidence packet + comparison). It covers input, process, output, and usage scenarios, making it self-contained and actionable for an AI agent.

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

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

Schema coverage is 100% and the description elaborates on parameters: market can be slug, URL, or question text; depth has quick/thorough with default explained. It adds meaning beyond the schema by describing the fan-out behavior associated with different depths.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (market slug, URL, or question text) and outputs (evidence packet, market-vs-model comparison), and differentiates from siblings by noting it's the core demo product that improves conversion.

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?'. While it does not mention when not to use or provide direct alternatives, the sibling tool list implies this is the primary research 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 (readOnlyHint=true) and non-destructive (destructiveHint=false). Description adds no behavioral details such as what happens when the cask is not found, or any other runtime traits.

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?

Extremely brief, but brevity comes at the cost of clarity. The single sentence does not fully describe the tool, making it under-specification rather than effective conciseness.

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 and description gives no indication of return values, success/failure conditions, or any side effects. Incomplete 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?

With 0% schema description coverage, the description must explain the 'name' parameter. Only stating 'by name' fails to clarify format, case sensitivity, or what constitutes a valid name.

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 'Cask by name.' is vague, lacking a verb and specific action. It implies lookup but does not clearly state what the tool does or how it differs from siblings like 'formula' or 'analytics_cask_install'.

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

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

No guidance on when to use this tool versus alternatives. Absence of usage context or exclusions leaves the agent without decision support.

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 data sources (SEC EDGAR/XBRL, FAERS) and return format (paired data + citation URIs), which goes beyond structured fields.

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

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

Single paragraph that efficiently covers purpose, use cases, type details, and output. No unnecessary sentences.

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

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

Despite no output schema, description adequately explains the return (paired data + URIs) and covers both entity types with specific data sources, making it 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 has 100% coverage; description expands on what 'values' mean (tickers/CIKs for company, drug names for drug) and reinforces the 2-5 range, adding 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?

Clearly states it compares 2–5 companies or drugs side by side, specifying the data pulled for each type (financials from SEC for companies, adverse events/approvals/trials for drugs). Distinguishes from sibling tools like entity_profile.

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

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

Explicitly lists trigger phrases like 'compare X and Y', 'X vs Y', 'how do X, Y, Z stack up' and mentions it replaces many sequential calls, guiding when to use.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds that it returns 'top-N most relevant tools with names + descriptions' and the default/max limit, but does not explain the relevance algorithm. 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 a single, well-structured paragraph that front-loads the purpose, then provides usage scenarios, examples, and a call to 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 no output schema, the description explains that it returns top-N tools with names and descriptions. It covers purpose, usage, behavior, and parameter details sufficiently for a discovery tool.

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

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

Schema description coverage is 100% with both parameters described. The description does not add new semantic information beyond the schema, meeting baseline for high coverage. Example domains are not parameter-specific.

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 'Find tools by describing the data or task' and provides specific examples of domains. It distinguishes itself from sibling tools by recommending it as a first call when many tools are available, avoiding 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?

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for' followed by a list of domains. Also provides a concrete when-to-use directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 behavior. The description adds valuable behavioral context: it returns data with pipeworx:// citation URIs and aggregates from multiple domains (SEC, USPTO, GLEIF, news). No contradictions, and it enriches understanding of what happens 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 a single paragraph that is front-loaded with the purpose, then details use cases, return contents, and parameter guidance. It is efficient but could be slightly more structured (e.g., bullet points for return items) to improve readability for an AI agent.

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 no output schema, the description fully explains what is returned (recent filings, fundamentals, patents, news, LEI). It also addresses the alternative for name inputs and the supported entity type. An agent has all information needed to correctly select and invoke this 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 covers 100% of parameters with descriptions. The description adds concrete examples ('AAPL', '0000320193'), explains constraints (only company type, names unsupported), and provides guidance on how to pass values, adding significant meaning beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Get everything about a company in one call.' It lists specific data types (SEC filings, fundamentals, patents, news, LEI) and explicitly distinguishes it from calling multiple individual tools, making the purpose highly specific and differentiated from siblings.

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

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

The description provides explicit usage scenarios (e.g., 'tell me about X', 'research Microsoft') and also states when not to use it ('Names not supported — use resolve_entity first'). This gives clear when-to-use and when-not-to instructions, plus an alternative 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 destructiveHint=true, so the description's 'Delete' is consistent. It adds minimal context beyond annotations, such as 'clear sensitive data,' but doesn't elaborate on effects or permissions.

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 efficiently cover purpose and usage. No extraneous information; every sentence is 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?

For a simple one-param mutating tool with no output schema, the description adequately covers purpose, usage, and related tools. It does not explain return values, but that's acceptable given no output schema.

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

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

Schema description coverage is 100% with the param 'key' described as 'Memory key to delete.' The description reinforces this but adds little additional meaning beyond 'by key' and 'clear sensitive data.'

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 'Delete a previously stored memory by key,' providing a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' 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?

The description explicitly says 'Use when context is stale, the task is done, or you want to clear sensitive data,' giving clear usage context. It also mentions pairing with 'remember' and 'recall,' but lacks explicit 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?

Annotations indicate read-only, but description adds no behavioral context beyond name; no mention of return type or side effects.

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

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

Extremely short but underspecified; not concise in a helpful way.

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?

Lacks completeness; no explanation of output, purpose, or usage context despite simple 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?

Only one parameter 'name' with no description; description only says 'by name' which weakly implies it is the formula identifier, but no format or constraints.

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

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

Description 'Formula by name' is vague; does not specify action (retrieve, compute, search). Only identifies resource.

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

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

No guidance on when to use this tool versus siblings; no context for appropriate use.

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

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

Beyond annotations, the description discloses rate limiting, daily digest processing by the team, and the fact that it does not count against tool-call quota. This gives the agent full behavioral understanding without needing to infer.

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, then covers usage, behavioral notes, and constraints. Every sentence adds value and there is 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 simplicity (3 parameters, nested object, no output schema), the description fully covers semantics, usage, and constraints. It leaves no ambiguity for an AI agent to misuse 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?

The input schema already has 100% coverage with clear descriptions for each parameter, including enum values for 'type'. The description adds extra context (e.g., explaining what each 'type' means in practice) but the schema alone is sufficient for basic usage.

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 submit feedback (bug, feature, data_gap, praise). It distinguishes from other tools by specifying when to use it (e.g., when a tool returns wrong data) and explicitly mentions that feedback is directed at the Pipeworx team, not for general use.

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 on when to use each feedback type (bug, feature, data_gap, praise) and what to include (describe in terms of tools/packs, avoid pasting prompts). It also notes rate limits (5 per identifier per day) and that it is free and doesn't count against quota.

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 reveals key behavioral traits: it walks child markets, groups related markets, checks monotonicity, and returns ranked opportunities with reasoning. Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds context about the internal logic but does not mention potential rate limits or data freshness. With annotations covering safety, a 4 is appropriate.

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

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

The description is concise and well-structured: a one-sentence summary, then bullet-like enumeration of the two modes with clear labels. Every sentence adds value, and the description is front-loaded with the core purpose. No redundant or vague language.

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 appropriately mentions return value ('ranked opportunities with suggested trade direction + reasoning'). It covers the two modes and their differences. However, it doesn't explicitly state that the parameters are mutually exclusive (if both provided, behavior is unspecified). The tool has no required parameters but the description implies at least one is needed. Overall, it is largely complete for an AI agent to use.

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

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

The input schema has 100% coverage, so baseline is 3. The description adds significant meaning beyond schema descriptions: it explains that 'event' is for single-event mode and 'topic' for cross-event mode, with examples. This helps the agent understand the context and usage of each parameter.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket by checking monotonicity violations. It specifies two distinct modes (event and topic) and explains what each does. The verb 'Find' and resource 'arbitrage opportunities on Polymarket' are specific, and the description distinguishes itself from sibling tools by detailing the monotonicity-checking mechanism.

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 on when to use each mode: use 'event' for a single Polymarket event slug, and use 'topic' for cross-event searches. It includes an example explaining why cross-event mode is needed for related but separate events. However, it does not explicitly state when not to use this tool or compare it to alternatives like 'polymarket_edges', which would earn 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?

Annotations already indicate read-only, non-destructive, and open-world. The description adds valuable behavioral details: scanning top markets, grouping by asset, fetching price history once, computing model probability, and ranking by |edge|. 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 paragraph but concise, covering what, how, and use case without redundancy. It could be slightly more streamlined, but every sentence adds value.

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

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

Given no output schema, the description sufficiently describes output: top N ranked by edge magnitude with suggested trade direction. It covers input, process, output, and use case, making it complete for a tool with 3 parameters and moderate 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?

Input schema has 100% coverage with descriptions for each parameter. The description does not add significant new meaning beyond the schema, only context about defaults and purpose. Baseline 3 is appropriate as schema already does the heavy lifting.

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 highest-volume Polymarket markets and returns those where Pipeworx data disagrees with market price, with specific verb 'scan' and resource 'Polymarket markets'. It distinguishes from sibling 'polymarket_arbitrage' by focusing on edge opportunities rather than arbitrage.

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

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

The description explicitly states it is built for the 'what should I bet on today' question, providing clear context for when to use. However, it lacks an explicit when-not-to-use or direct comparison to alternatives like 'polymarket_arbitrage'.

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, so safety is covered. The description adds valuable context about scoping to identifiers and pairing with remember/forget, enhancing behavioral understanding 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?

Two sentences, front-loaded with the primary action, then examples and scope. No unnecessary words; every sentence adds value.

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

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

Given the low complexity (one optional param, no output schema), the description covers purpose, usage, behavioral notes, and pairing with sibling tools. It is complete for effective use.

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

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

Schema description coverage is 100% for the single parameter, so the description adds no new semantic information. The advice to 'omit the key argument' is already stated 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 clearly states the tool retrieves a saved value or lists all keys, with specific verb 'retrieve' and resource 'value/key'. It distinguishes from siblings like 'remember' and 'forget' by mentioning them explicitly.

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

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

Provides clear use cases (look up context, target ticker, address, notes) and implies when to use (after saving via remember). Lacks explicit when-not-to-use or alternative tools, but the context is sufficient for a simple lookup 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?

The description goes beyond the annotations (readOnlyHint, openWorldHint, destructiveHint) by detailing the parallel fan-out to three sources, the return structure (changes + total_changes + citation URIs), and explaining the format of the 'since' parameter.

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

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

The description is efficiently written with front-loaded purpose and examples. Every sentence adds distinct value—use cases, data sources, parameter format, and return structure—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 tools three required parameters and no output schema, the description fully covers purpose, usage, parameter guidance, behavioral details, and return structure. It leaves no essential question unanswered.

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 provides 100% coverage with descriptions for all three parameters, but the description adds valuable context: 'type' is limited to 'company', 'value' can be ticker or CIK, and 'since' accepts both ISO dates and relative shorthand with examples.

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

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

The description clearly states the tools purpose with a specific verb and resource ('What's new with a company'), gives example user queries, and distinguishes it from siblings by detailing its multi-source fan-out to SEC EDGAR, GDELT, and USPTO.

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 example queries to guide when to use the tool, but does not explicitly state when not to use it or mention alternatives among the sibling tools. However, the context is clear enough for typical use cases.

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 safety is clear. Description adds no behavioral details beyond what annotations provide, but it does not contradict them.

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?

Extremely short (2 words), but underspecifies purpose. Conciseness is not achieved at the cost of clarity; more context is needed.

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?

Even for a simple tool with good annotations, the description fails to state the action (list/get), explain parameters, or mention result behavior. Incomplete for effective selection.

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 document 50% of parameters (days has range and default, limit lacks description). Tool description adds no parameter guidance, failing to compensate for the missing 'limit' semantics.

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

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

Description 'Recently-added formulae' is a noun phrase, not a verb action. It vaguely indicates the tool returns recent formulae but does not specify the operation (e.g., list, get, search). Differentiating from sibling 'formula' is unclear.

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

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

No guidance on when to use this tool over siblings like 'formula' or 'recent_changes'. No context about filters, prerequisites, or alternatives is provided.

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

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

Annotations indicate it's a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). Description adds persistence details: authenticated users get persistent memory, anonymous sessions retain for 24 hours. 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 somewhat wordy but well-structured, starting with purpose, then usage, then technical details. Each sentence adds value, though it 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?

Given no output schema and simple tool, description covers purpose, usage, persistence behavior, and sibling tools. It is complete enough 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?

Schema covers both parameters with descriptions (key and value). Description adds little beyond schema, just notes value can be 'any text'. Baseline 3 is appropriate as schema already provides high coverage.

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: 'Save data the agent will need to reuse later.' It specifies key-value storage, scoping by identifier, and distinguishes 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 'Use when you discover something worth carrying forward' and provides examples (resolved ticker, target address, etc.). It also indicates pairing with recall and forget, giving clear usage 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?

Annotations already indicate read-only (readOnlyHint=true) and non-destructive behavior. The description adds that the tool returns IDs plus pipeworx:// citation URIs, providing additional behavioral context. 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 concise and front-loaded with the core purpose. Each sentence adds value, though some slight redundancy could be trimmed. Overall, well-structured.

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

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

For a two-parameter lookup tool with no output schema, the description provides sufficient information: lists supported ID systems, gives examples, and states it returns IDs and citation URIs. It is complete given 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?

The input schema has 100% coverage, and the description enriches both parameters with examples and valid input formats (e.g., 'ticker (AAPL), CIK, or name' for value). This adds significant 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: looking up canonical identifiers for companies or drugs. It provides specific examples (e.g., Apple -> AAPL/CIK, Ozempic -> RxCUI) and explicitly differentiates itself from other tools by positioning as a prerequisite for 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 explicitly tells when to use this tool ('when a user mentions a name and you need the... ID') and advises to use it before calling other tools. It does not explicitly mention when not to use it, but the guidance is clear enough.

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

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

Annotations (readOnlyHint, openWorldHint, destructiveHint) are present and consistent. The description adds significant behavioral context: returns verdict types (confirmed/approximately_correct/refuted/inconclusive/unsupported), extracted structured form, actual value with pipeworx:// citation, percent delta, and mentions it replaces 4–6 sequential calls. 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 4-sentence paragraph that front-loads the purpose, then usage, then scope, then return details. Every sentence adds value with no redundancy. Succinct yet comprehensive.

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 one parameter, full schema coverage, and annotations, the description is outstandingly complete. It covers all essential aspects: what it does, when to use, supported domain, return values, and even performance advantage. No gaps given 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?

With 100% schema coverage (one parameter 'claim' described), baseline is 3. The description adds value by providing example claim formats ('Apple's FY2024 revenue was $400 billion') and reinforcing natural-language nature, going beyond the schema's brief description.

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

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

The description clearly states the tool's purpose: fact-checking, verifying, validating, or confirming/refuting natural-language claims against authoritative sources. It uses specific verbs and resource ('validate_claim') and distinguishes itself from sibling tools like 'entity_profile' or 'resolve_entity' by focusing on claim verification.

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 clear guidance on when to use (e.g., 'Is it true that…?', 'Verify the claim that…'), but could explicitly mention when not to use (e.g., non-financial claims). The scope is defined for 'v1 supports company-financial claims via SEC EDGAR + XBRL', implying limitations.

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