Victorian Complaint

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds important behavioral context: free vs paid model usage, direct pass-through of API key to Anthropic, and the per-model response structure. 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?

Three sentences: first covers core function and default, second explains API key, third lists output and use cases. 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?

All 4 parameters are thoroughly explained. Output structure is described despite no output schema. Use cases are provided. For a tool of this complexity (4 params, LLM probing, external API), the description is fully 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%, but description adds significant meaning: entity examples, supported models, API key purpose, and context disambiguation. It explains default behavior and optional parameters clearly beyond schema titles.

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 probes LLMs to score visibility (0-100) for a given entity. It specifies the verb 'probe', resource 'LLMs', and output 'score'. Examples and default model help distinguish from siblings like 'scan_competitor_ai_presence'.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It mentions default model and BYO key for Anthropic. While it doesn't exclude alternatives, the context is clear enough for an agent to decide when to invoke.

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 bears full burden. It explains that Pipeworx selects tools and fills arguments, which is useful. However, it doesn't disclose potential limitations like latency, data recency, or whether the tool can handle multi-turn conversations.

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 (two sentences plus examples) and front-loaded with the core purpose. The examples are helpful, though they could be slightly more varied.

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

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

Given the simple schema (one string param, no output schema), the description is sufficiently complete for a query tool. It covers purpose, usage, and provides examples.

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

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

Schema coverage is 100%, but the description adds value by framing the parameter's use as 'in natural language' and providing examples. This goes beyond the schema's 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 it answers plain English questions by selecting the best data source, which is specific and distinguishes it from sibling tools that manage memory (remember/forget/recall), discover tools, or generate complaints.

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 examples and implies when to use it (any natural language query), but does not explicitly state when not to use it or mention alternatives among 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 declare readOnly and non-destructive. The description adds substantial context: it resolves the market, classifies the bet, fans out to appropriate packs based on bet type, and returns evidence and model comparison. This goes beyond annotations and provides clear behavioral 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?

The description is somewhat lengthy (three sentences) and includes a marketing claim about conversion rates. While front-loaded with purpose, it could be more concise by omitting the last sentence, which is less essential for tool selection.

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 2 parameters and no output schema, the description comprehensively explains inputs, process, and outputs. It covers what the tool does, how it works, and what it returns, making it fully contextual for an 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 coverage is 100% with descriptions for both parameters. The tool description adds value by explaining the depth enum values ('quick = 2-3 evidence sources, thorough = full fan-out') and clarifying that market accepts slug, URL, or question text. This enhances understanding beyond the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison), and distinguishes from siblings by highlighting it's the core demo product.

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 provides use cases like 'should I bet on X?' and 'what does the data say about this Polymarket market?'. It implies when to use and why it's better than alternatives, though it does not name specific sibling tools as alternatives.

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

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

No annotations provided, so description carries full burden. It discloses returns per type and URIs, but doesn't clarify read-only nature, side effects, or auth needs. 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?

Concise three-sentence description with no wasted words. Front-loaded with core purpose, then expands on types and benefit.

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?

Covers basics but lacks output format details or examples. Vague on 'paired data' and URI structure. Adequate for a tool with no output schema but could be more 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% (both parameters described). Description adds value by explaining what each type returns and how to format values (tickers/CIKs or drug names), beyond short 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 purpose: comparing 2–5 entities side by side in one call, with specific data per type (company, drug). Distinguishes from siblings (memory/query tools) as a dedicated comparison tool.

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

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

The description implies usage for multi-entity comparison and mentions efficiency (replaces 8–15 calls), but lacks explicit when-to-use or alternatives. No exclusions or context for when not to use.

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

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

The description discloses that the tool returns 'the most relevant tools with names and descriptions' and implies a ranking mechanism. Since no annotations are provided, the description carries the full burden. It is clear about the search-based behavior but does not mention any side effects or limitations beyond the implicit relevance ranking. A score of 4 is appropriate as it is transparent about the core functionality.

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 extremely concise, consisting of only three short sentences. The first sentence states the purpose, the second clarifies the output, and the third provides usage guidance. No extraneous information is included, making it highly efficient.

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

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

Given the tool's simplicity (2 params, no output schema), the description is nearly complete. It explains the purpose, usage, and output. A minor gap is the lack of information about error handling or what happens if the query returns no results, but this is acceptable for a search tool. With sibling tools being diverse and no output schema, the description provides sufficient context.

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

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

The input schema already covers 100% of parameters with descriptions, so the baseline is 3. The tool description does not add additional meaning beyond what the schema provides; it only restates the query parameter concept. The description does not elaborate on the limit parameter or provide examples of queries, but the schema already explains these well.

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 searches a catalog by describing needs and returns relevant tools with names and descriptions. It specifies a specific verb ('search') and resource ('Pipeworx tool catalog'), and distinguishes itself by instructing to call it 'FIRST' when there are 500+ tools.

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

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

The description provides explicit guidance on when to use this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This clearly indicates it is the initial discovery step, differentiating it from sibling tools that presumably do not offer catalog search.

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 exist, so description bears full burden. It discloses return format (pipeworx:// URIs) and bundling behavior, but lacks details on authorization, rate limits, or mutability. Adequate but not thorough.

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

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

Concise paragraph that front-loads main purpose, then details data sources and special cases. No fluff, though slightly dense. Could benefit from line breaks for readability.

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

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

Given the complexity of bundling multiple data sources and no output schema, the description adequately lists what is included and the return format. Missing error conditions or data freshness, but sufficient for typical use.

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

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

Schema covers both parameters with descriptions. Description adds value by specifying valid value formats (ticker/CIK) and directing users to resolve_entity for names, enhancing the schema's guidance.

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 provides a full entity profile across multiple data sources in one call, listing specific data types (SEC filings, XBRL, patents, news, LEI). It distinguishes itself from sequential calls and mentions an alternative tool for federal contracts, making 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?

Explicitly tells when to call usa_recipient_profile instead for federal contracts, and implies it replaces many sequential calls. Could be more comprehensive about other scenarios, but the provided guidance is actionable.

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

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

With no annotations, the description must disclose behavioral traits. It states the action is destructive (delete), but does not mention any side effects, permissions, or irreversible consequences. A 3 is adequate as it correctly indicates a write operation.

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

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

One sentence, no filler, directly states the action and input requirement. Every word contributes to the purpose.

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

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

Given a simple tool with one parameter and no output schema, the description is sufficient for basic use. However, it lacks context on what happens if the key does not exist, or if deletion is irreversible, which would be helpful for an agent.

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

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

Schema description coverage is 100% for the single parameter 'key'. The description adds no additional meaning beyond what the schema 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?

Description states 'Delete a stored memory by key', which clearly identifies the verb (delete), resource (stored memory), and how (by key). It distinguishes from siblings like 'remember' (store) and 'recall' (retrieve).

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

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

The description implies that this tool is used to delete a memory when you know its key, but it does not explicitly state when to use this vs. alternatives like 'forget' vs. 'remember' or 'recall'. No exclusion criteria are given.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the internal process (fetches page, extracts title/description/key links) and output format ('standard llms.txt markdown format' and 'single text blob'). This enriches understanding 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 extremely concise: two sentences each serving a distinct purpose (what it does and use cases), with no redundant phrases. It front-loads the core function and output, making it efficient for an AI agent 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?

Given the tool's simplicity, annotations covering safety, and complete schema descriptions, the description adequately covers the main functionality and output. It lacks explicit handling of edge cases (e.g., invalid URLs) but that is acceptable for a read-only tool with 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?

Input schema has 100% coverage with good descriptions for both parameters (url and max_links). The tool description does not add new semantic information about the parameters; it only reinforces their purpose indirectly through context. Thus, the description provides no additional value over the schema, meeting the baseline expectation.

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, with a specific verb ('Generate') and resource ('llms.txt file'). It distinguishes itself from sibling tools like ai_visibility_check by focusing on a concrete file output rather than general visibility analysis.

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 three explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. It does not explicitly exclude scenarios or name alternatives, but the use cases cover the main applications.

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

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

With no annotations, the description carries the full burden. It discloses a rate limit (5 messages/day) and that it's 'Free'. It does not explain other behaviors like data storage or authentication, though these may be less critical for a feedback tool. The description adds some value beyond annotations but lacks deeper behavioral context.

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

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

The description is very concise at three sentences. It front-loads the core purpose, immediately gives usage guidelines, and ends with a behavioral constraint. Every sentence is necessary and efficient, with no redundant or 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 and a simple feedback tool, the description covers the essential: what it does, when to use, what to include, and a constraint (rate limit). It does not explain the response or error behavior, but for a feedback tool that is acceptable and still fairly 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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description does not add extra meaning beyond restating the purpose and usage context. It reinforces the role of parameters but does not enrich their semantics beyond what the schema provides.

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

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

Description clearly states the tool's purpose: send feedback to the Pipeworx team. It specifies the actions (bug reports, feature requests, etc.) and distinguishes from sibling tools like ask_pipeworx or discover_tools by its unique feedback function.

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

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

Description provides explicit guidance on when to use (for bug reports, feature requests, etc.) and what to include/exclude (describe tools/data, not end-user prompt). It also mentions a rate limit. However, it does not specify alternatives among siblings or when not to use, missing a slight opportunity for exclusion 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds that data is self-aggregated from CF analytics-engine, no PII, and cached for 5min-1h. This provides useful context beyond annotations, though the exact output shape could be clarified.

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: first states output, second lists use cases, third explains data source and caching. No wasted words, front-loaded with key information.

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

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

The description covers purpose, usage, parameters, and behavioral traits. Missing some details on output structure (e.g., format of tool/pack entries) but sufficient for an agent to invoke correctly given the 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?

The only parameter 'window' has a clear enum description in the schema. The tool description adds context on when to use each window length, enhancing understanding. Schema coverage is 100% so baseline is high.

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

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

The description clearly states the tool returns top tools, packs, and call volume over recent windows. It specifies the resource (Pipeworx usage) and the verb (trending). Distinguishes from siblings like 'discover_tools' which likely focuses on discovery rather than trending.

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 concrete use cases: discovering hot data sources, confirming canonical tools, and checking alignment. Also gives guidance on window selection (short for hot, long for steady-state).

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 readOnlyHint=true, openWorldHint=true, destructiveHint=false, which align with the description's walk-and-report behavior. The description adds detail about the logic (extracting dates/thresholds, sorting, checking order), providing useful context beyond the annotations.

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

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

The description is concise but includes necessary explanatory detail about the arbitrage condition and return format. It could be slightly more terse, but the structure is logical and front-loaded.

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

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

The description fully explains what the tool does, how it works, what input is needed (with examples), and what output is returned (including fields). Given no output schema, this is comprehensive.

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 only parameter 'event' is well-described in the schema (100% coverage). The description adds that it can be a slug or full URL, which is additional helpful context.

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

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

The description clearly states the tool finds arbitrage opportunities by checking monotonicity violations within a Polymarket event. It specifies the verb (find), resource (arbitrage opportunities), and mechanism (monotonicity), distinguishing 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?

The description explains when to use this tool (when an event has multiple 'by date' or 'by threshold' markets) and provides an example. It does not explicitly state when not to use it or list alternatives, but the context is clear.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds value by explaining the internal workflow: scanning top markets, grouping by asset, single fetch of price history, computing model probability, ranking by edge magnitude. It also specifies the model source (lognormal from FRED + live coinpaprika). 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 (4 sentences) and front-loaded: the first sentence states the core action and purpose. Every sentence adds necessary context (model, grouping, output, use case). No redundant or filler 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 adequately explains return value: 'top N ranked by edge magnitude with suggested trade direction.' It mentions the model and data sources but lacks precise output format details (e.g., fields in each result). For a discovery tool, this is nearly complete, though explicit listing of return fields would raise it to 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds default values and max limit (e.g., 'Default 10, max 25') which are not in the schema descriptions, but this is marginal improvement. It references 'top N' and 'minimum edge' but does not substantially enrich parameter understanding beyond what the schema already provides.

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

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

The description uses specific verbs and resources: 'Scan the highest-volume Polymarket markets' and 'return ones where Pipeworx data disagrees most with market price.' It clearly distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on edge discovery rather than arbitrage. The intended use case ('what should I bet on today') further clarifies 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 implicitly states when to use the tool: for discovering betting opportunities without manually browsing hundreds of markets. It mentions the model and data sources, but does not explicitly exclude scenarios or mention alternatives (e.g., when to use `polymarket_arbitrage` instead). No 'when not to use' guidance 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?

The description goes beyond annotations by explaining why the spread exists ('venues have different participant pools') and details the return format (leg-by-leg prices in 0-1, spread in percentage points). Annotations already declare readOnlyHint, idempotentHint, etc., and the description complements them 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 well-structured: purpose first, then background, then two modes, then return format. Every sentence adds value with no redundancy or fluff.

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

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

Given no output schema, the description fully explains the return format and behavior. It covers both modes, parameter usage, and the rationale behind the spread. This is complete for a tool with this complexity and good annotations.

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

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

Schema coverage is 100% with parameter descriptions, but the description adds significant value: it explains 'topic' as pre-mapped shortcuts ('fed', 'btc', etc.) and clarifies that explicit parameters override the mapped side. This fully compensates 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' using a specific verb ('computes') and resource ('spread between venues'). It distinguishes itself from sibling tools like 'polymarket_arbitrage' by explicitly naming the two venues and focusing on the spread between them.

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

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

The description explains two modes ('topic' for pre-mapped macros and explicit for custom pairings) and implies usage for arbitrage detection ('that delta is a real arb signal'). However, it does not explicitly exclude alternatives or compare to siblings, so it stops short of a 5.

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

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

No annotations provided, so description carries full burden. Describes behavior as retrieval and listing, but does not disclose side effects (none expected), persistence guarantees, or return format. Adequate for a simple read operation, but could be more explicit about non-destructiveness.

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. Front-loaded with the primary purpose, followed by usage guidance.

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?

Simple tool with one optional parameter and no output schema. Description covers the two use cases and context. Could mention that keys are session-persistent, but overall sufficient for its 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% with the single 'key' parameter well-documented in the schema. Description adds context about omitting key to list all, which aligns with schema's optionality. Baseline 3 is appropriate as description adds marginal value over 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 specifies verb 'Retrieve' and resource 'memory', distinguishing between two use cases: retrieve by key or list all (omit key). Clearly differentiates from sibling tools like 'remember' (store) and 'forget' (delete).

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

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

Explicitly states when to omit key (to list all) and the context for use: 'retrieve context you saved earlier in the session or in previous sessions.' Does not explicitly say when not to use it, but the purpose 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?

With no annotations, the description carries the full burden. It discloses parallel fan-out to SEC EDGAR, GDELT, USPTO, explains the since parameter formats, and the return structure. It omits potential rate limits or authentication needs, but is generally transparent.

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

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

The description is a single paragraph that front-loads the purpose, then details behavior, parameter hints, and a use case. It is concise with no wordiness, though it could be slightly more structured with bullet points.

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

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

No output schema, so the description explains return values: 'structured changes + total_changes count + pipeworx:// URIs.' It thoroughly covers the single entity type (company) and parameter options. It is complete for the current scope.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the since parameter formats (ISO date and relative strings with examples) and the value parameter as ticker or CIK, going beyond the schema descriptions.

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

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

The description clearly states 'What's new about an entity since a given point in time' and details the specific behavior for type='company', including fan-out to multiple sources. This distinguishes it from siblings like entity_profile (static profile) and compare_entities (comparison).

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

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

The description explicitly recommends 'Use for "brief me on what happened with X" or change-monitoring workflows.' It implicitly covers when to use but does not explicitly state when not to use or list alternatives. Still, it provides 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?

No annotations provided, so description carries full burden. Discloses persistence behavior ('authenticated users get persistent memory; anonymous sessions last 24 hours') and implies the tool is safe (no destructive language). No contradiction with missing 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, no fluff, front-loaded with action. Could combine the second sentence more concisely, but it's still efficient. Slightly verbose with the list of examples in the schema, but that's schema, not description.

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?

Tool has no output schema, but description sufficiently explains what it does and its persistence model. With only 2 simple params and no complex behavior, the description is complete enough for an agent to use correctly. 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?

Schema coverage is 100% with clear descriptions for both parameters. Description adds value by providing usage context ('intermediate findings, user preferences, context') that goes beyond schema, though schema already covers key-value semantics well. Baseline 3 with bonus for added context.

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

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

Description clearly states verb 'Store' and resource 'key-value pair in session memory'. Distinguishes from sibling tools: 'forget' (delete), 'recall' (retrieve), 'ask_pipeworx' (query external), 'discover_tools' (discover).

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

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

Explicitly says when to use ('save intermediate findings, user preferences, or context across tool calls') and notes authentication persistence vs anonymous session expiry. No explicit when-not or alternatives mentioned, but purpose and sibling names imply exclusivity.

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

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

No annotations are provided, so the description must fully disclose behavior. It mentions the tool accepts multiple input types and returns specific outputs, but it does not discuss error handling, authorization, or what happens if the entity is not found. The description adds some useful behavioral context but is 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 two sentences long, front-loaded with the core purpose, and every sentence adds value. 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 the tool has 2 required params and no output schema, the description adequately explains inputs and outputs. It does not cover error cases, but for a simple lookup, this is reasonably 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 description coverage is 100%, and the description adds value beyond schema by providing concrete examples (AAPL, Apple) and clarifying that v1 only supports 'company'. This helps the agent understand parameter 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 resolves entities to canonical IDs, specifying the supported type ('company') and input formats (ticker, CIK, name). It distinguishes itself from sibling tools (memory, discovery, general Q&A) by being a specific resolution endpoint.

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

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

The description explains when to use it: when you need canonical IDs, and highlights efficiency (replaces 2-3 calls). It does not explicitly mention when not to use it or alternatives, but the context is clear enough for an AI 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?

The description explains the process (probes each entity, ranks by score, surfaces most/least recognized) and mentions output fields (score, confidence, signal density). This adds behavioral context beyond the annotations, which indicate read-only, open-world, idempotent, non-destructive behavior. No contradiction.

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

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

The description is a single paragraph that efficiently covers purpose, process, and use case. It is front-loaded with the main action. Minor redundancy could be removed but overall 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 the tool's complexity (4 parameters, all documented in schema), annotations, and no output schema, the description provides sufficient information: when to use, how it works, what it returns, and an example. It is complete for agent decision-making.

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 role of the first entity as 'subject' and describing the effects of the 'models' parameter (default and key requirement). This enriches the schema definitions.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies a specific verb+resource (compare AI visibility) and distinguishes from sibling 'ai_visibility_check' by focusing on 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 gives a clear use case ('competitive AI-marketing audits') and provides an example question. It implies when to use (multiple entities) vs. single check, but does not explicitly state when not to use or mention alternatives.

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

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

With no annotations, the description carries full burden. It discloses the return structure (verdict, structured form, actual value, citation, delta) and the data source (SEC EDGAR + XBRL). It also notes the version limit (v1 supports only company-financial claims). However, it doesn't mention potential limitations like authentication, rate limits, or what happens for unsupported claim types. No contradiction with missing 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 (three sentences) and front-loaded with the primary purpose. Every sentence provides essential information: what it does, supported domains, output format, and comparative efficiency. No wasted words.

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

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

Given the simplicity (single parameter, no output schema, no annotations), the description is fairly complete. It covers purpose, scope, output, and efficiency benefits. Could be slightly more explicit about error handling or behavior for unsupported claims, but overall adequate.

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

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

The single parameter 'claim' has a clear description and example in the schema (100% coverage). The description adds value by specifying the supported claim types (company-financial) and the expected format, going beyond the schema's generic string 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?

Clearly states it fact-checks natural-language claims, specifically company-financial claims, using SEC EDGAR + XBRL. The verb 'fact-check' and resource 'claim' are specific, and the description distinguishes it from general sibling tools like ask_pipeworx by narrowing the domain.

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

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

Explicitly describes when to use: for fact-checking claims, especially company-financial ones. Mentions efficiency by replacing multiple agent calls. Does not explicitly state when not to use (e.g., non-financial claims), but the scope is implicitly clear from the description.

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 bears full burden for behavioral disclosure. It fails to state whether the tool generates text, modifies data, or has side effects. Only implies stylistic transformation.

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 extremely concise but at the expense of completeness. It front-loads a catchy phrase but fails to provide necessary details for a 5-parameter tool.

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

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

Given the complexity (5 parameters, no schema descriptions, no annotations, and an output schema), the description is critically incomplete. It does not explain what the tool returns or how to use parameters effectively.

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 0%, and the tool description provides no explanation for any of the 5 parameters (e.g., complaint, length, indignation). The examples in the schema exist but the description adds no value.

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 hints at generating a complaint with Victorian indignation but does not explicitly state the action (e.g., 'generate' or 'return'). It vaguely indicates the tool processes complaints but lacks specificity.

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. The description does not mention contexts, exclusions, or comparisons to sibling tools.

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