marine

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the return format (per-model score, confidence, signals, raw_response + combined view) and noting that Anthropic calls incur direct costs. 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 (two sentences) and well-structured. The first sentence states the core purpose, and the second adds usage scenarios and return format. Every phrase serves a purpose, and the information is 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?

Given no output schema, the description adequately covers return values (per-model details + combined view). All 4 parameters are described in schema and supplemented by the description. The tool's complexity is low-to-moderate, and the description provides sufficient context for correct invocation.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description enhances understanding by explaining the default model for the 'models' parameter, the direct pass-through behavior of '_apiKey', and the disambiguation role of 'context'. This adds meaningful context beyond the raw schema.

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

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

The description specifies the tool's core function: probing LLMs for knowledge about a topic and scoring visibility. The verb 'probe' and resource 'visibility' are clearly defined, and the purpose is distinct from sibling tools like 'ask_pipeworx' or '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?

The description explains when to use the tool (AI-marketing audits, brand checks) and provides model selection guidance (default Workers AI, BYO key for Anthropic). It lacks explicit exclusions, but the context is sufficient 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?

No annotations are provided, so the description carries the full burden. It discloses that Pipeworx 'picks the right tool, fills the arguments, and returns the result,' which adds useful behavioral context about automation. However, it lacks details on error handling, rate limits, or authentication needs, leaving gaps for a tool with no annotation coverage.

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

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

The description is front-loaded with the core purpose, followed by explanatory details and concrete examples. Every sentence adds value: the first explains the tool's function, the second describes its automation, and the third provides usage guidance with examples. No wasted words, 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 complexity (natural language processing to select tools) and lack of annotations/output schema, the description does well by explaining the automation process and providing examples. However, it could better address potential limitations or error cases. For a tool with no structured behavioral data, it's largely complete but not exhaustive.

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

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

The input schema has 100% description coverage, with the 'question' parameter documented as 'Your question or request in natural language.' The description reinforces this by stating 'Ask a question in plain English' and providing examples, adding semantic context beyond the schema. With only one parameter, this is sufficient for a high 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 clearly states the tool's purpose: 'Ask a question in plain English and get an answer from the best available data source.' It specifies the verb ('ask'), resource ('answer'), and mechanism ('Pipeworx picks the right tool, fills the arguments'), distinguishing it from siblings like discover_tools or recall. The examples further clarify its scope.

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

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

The description explicitly states when to use this tool: 'No need to browse tools or learn schemas — just describe what you need.' This contrasts with alternatives that might require manual tool selection or schema knowledge, providing clear guidance on its use case versus other tools on the server.

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 details the tool's inner workings: it resolves the market, classifies the bet, fans out to relevant data packs based on classification, and returns a comparison. Annotations already indicate readOnlyHint=true and openWorldHint=true, and the description adds valuable behavioral context 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 a moderately long paragraph but every sentence adds value: purpose, inputs, process, use cases, and value proposition. It could be slightly more concise, but it is well-structured 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?

Despite lacking an output schema, the description clearly states the return: 'evidence packet plus a simple market-vs-model comparison'. It covers the complex fan-out logic, classification, and the tool's purpose. For a read-only research tool, this is a complete and helpful description.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context by explaining how the 'depth' parameter affects fan-out (quick vs thorough) and clarifies valid formats for 'market'. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, or question text) and outputs (evidence packet, market-vs-model comparison). This distinguishes it from sibling tools like ask_pipeworx or validate_claim.

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

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

The description explicitly provides use cases: 'Use for "should I bet on X?", "what does the data say about this Polymarket market?", or "is there edge in this bet?"' It does not include when-not-to-use or 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?

Discloses return format (paired data + pipeworx:// URIs) and efficiency benefit (replaces 8–15 calls). No contradictions, but no detail on side effects or auth needs.

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, tightly written with no waste. First sentence states purpose, second details types, third covers returns and efficiency.

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?

Adequately covers what is needed for a tool with 2 parameters and no output schema. Explains types and return format, but could add detail on output structure or error handling.

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

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

Adds meaning beyond schema by detailing company metrics (revenue, net income, etc.) and drug metrics (adverse events, FDA approvals). Schema coverage is 100% but description enriches understanding.

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

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

Clearly states the tool compares 2–5 entities side by side, with specific verb+resource and type-specific metrics. Differentiates from sequential agent calls.

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

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

Provides clear context for when to use (comparing 2-5 entities of company or drug types). Lacks explicit exclusions or 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 are provided, so the description carries the full burden. It discloses key behavioral traits: it's a search operation that returns 'the most relevant tools with names and descriptions', and it has a default/max limit context (implied by the input schema's limit parameter description, which the description doesn't repeat). However, it doesn't mention error conditions, rate limits, or authentication needs, leaving some gaps for a tool with no 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 appropriately sized and front-loaded: the first sentence states the core purpose, the second adds critical usage context, and every sentence earns its place by providing essential guidance without redundancy. It's concise and well-structured for effective agent understanding.

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 moderate complexity (search function with 2 parameters), no annotations, and no output schema, the description is mostly complete: it covers purpose, usage, and behavioral output (returns tools with names/descriptions). However, it lacks details on output format or error handling, which could be helpful since there's no output schema, leaving a minor gap.

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 fully documents the two parameters (query and limit). The description adds no additional parameter semantics beyond what's in the schema, such as query examples or limit usage context. This meets the baseline of 3 for high schema coverage without extra value from the 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 with specific verbs ('Search the Pipeworx tool catalog') and resources ('tool catalog'), and explicitly distinguishes it from sibling tools by mentioning it's for when 'you have 500+ tools available' and should be called 'FIRST' to find the right ones, making it distinct from the sibling tools get_current_waves and get_wave_forecast.

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 guidelines: it specifies when to use ('when you have 500+ tools available and need to find the right ones for your task'), when to call it ('Call this FIRST'), and implies alternatives by suggesting it's for initial discovery in a large catalog, contrasting with the sibling tools which appear to be specific data retrieval functions.

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?

Despite no annotations, the description discloses the return format (pipeworx:// URIs), the scope of data, and the bundling behavior, though it doesn't mention rate limits or authentication.

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 efficiently convey purpose, supported types, data sources, and usage guidance 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 sufficiently explains return data and what is omitted, making the tool's behavior entirely comprehensible for a 2-parameter 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 100% schema coverage, the description adds value by explaining acceptable values for 'value' (ticker or CIK) and clarifying that names are not supported, plus suggesting resolve_entity.

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 full entity profile, lists specific data sources for companies, and explicitly replaces 10-15 sequential calls, distinguishing it from other tools.

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

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

It specifies when to use (for full profile) and provides an explicit alternative (usa_recipient_profile for federal contracts) and a prerequisite (use resolve_entity if only a name is available).

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 but only states the action ('Delete') without disclosing behavioral traits. It doesn't mention if deletion is permanent, requires specific permissions, has side effects, or what happens on success/failure, which is critical for a destructive operation.

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

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

The description is a single, front-loaded sentence with zero waste—it directly states the tool's purpose without fluff. Every word earns its place, making it highly efficient and easy to parse.

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

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

Given this is a destructive tool with no annotations and no output schema, the description is incomplete. It lacks crucial context like what 'delete' entails (e.g., irreversible?), error handling, or return values, leaving significant gaps for safe agent operation.

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 the 'key' parameter fully. The description adds no additional meaning beyond implying the key identifies a memory to delete, aligning with the schema but not compensating for gaps (none exist here). Baseline 3 is appropriate.

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

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

The description clearly states the specific action ('Delete') and resource ('a stored memory by key'), distinguishing it from sibling tools like 'recall' (likely retrieves) and 'remember' (likely stores). It's precise and avoids tautology with the tool name '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?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., that a memory must exist to delete), exclusions, or how it relates to siblings like 'recall' or 'remember', leaving the agent to infer usage context.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and not destructive. The description adds process details: fetches page, extracts metadata, emits standard markdown format. It does not cover error handling or rate limits, but the added context is valuable.

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

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

The description is three sentences, front-loaded with the primary purpose, and every sentence adds value. No unnecessary words 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?

For a tool without output schema, the description adequately covers output format (standard llms.txt) and use contexts. Missing mention of error handling, but the tool is simple and annotations provide safety profile, making it 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 coverage is 100% and already describes both parameters well (URL and max_links). The description reinforces but does not add significant new meaning beyond what the schema provides, meeting the baseline for 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 generates a production-ready llms.txt file for AI crawlers, specifying the resource (URL) and output format. It distinguishes itself from sibling tools, none of which perform similar functionality.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor AI visibility. It does not mention when not to use or alternatives, but given no related siblings, this is clear and sufficient.

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

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

With no annotations provided, the description carries the full burden. It discloses the return values (wave height, period, direction) and temporal scope ('right now'), which is useful. However, it doesn't mention potential limitations like data availability, accuracy, rate limits, or error conditions that would help the agent understand behavioral 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?

The description is two concise sentences that are front-loaded with the core purpose and efficiently convey key information without any wasted words. Every sentence adds value by specifying what it does and what it returns.

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 moderate complexity (2 required parameters, no output schema, no annotations), the description is reasonably complete. It covers the purpose, return values, and temporal scope. However, without annotations or an output schema, it could benefit from more detail on behavioral aspects like error handling or data sources to be fully 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?

Schema description coverage is 100%, so the schema already documents both parameters (latitude and longitude) adequately. The description adds no additional parameter information beyond what the schema provides, such as coordinate format or valid ranges, so it meets the baseline for high schema 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 specific action ('Get current wave conditions'), the resource ('for a coastal location'), and the scope ('right now'). It distinguishes from the sibling tool 'get_wave_forecast' by specifying current conditions versus forecast data.

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

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

The description implies usage context by specifying 'current wave conditions' and 'right now', suggesting this tool is for real-time data. However, it doesn't explicitly state when to use this versus the sibling 'get_wave_forecast' or provide any exclusions or prerequisites.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool returns but doesn't mention rate limits, authentication requirements, error conditions, or whether the data is cached/live. It adequately describes the core behavior but lacks operational context.

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

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

The description is a single, well-structured sentence that efficiently communicates purpose, scope, and output. Every word earns its place with no redundancy or unnecessary elaboration.

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 read-only forecasting tool with no output schema, the description provides sufficient context about what data is returned. However, it could benefit from mentioning typical response format or data sources. The combination of clear purpose and parameter documentation makes it mostly 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 fully documents all three parameters. The description doesn't add any parameter-specific information beyond what's in the schema, such as explaining coordinate systems or day range implications. This meets the baseline for high schema 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 specific action ('Get a multi-day daily wave forecast'), the resource ('for a coastal location'), and the output format ('maximum wave height, wave period, and dominant wave direction per day'). It distinguishes from the sibling tool 'get_current_waves' by specifying it's a forecast rather than current conditions.

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 when to use this tool (for multi-day forecasts rather than current conditions), which differentiates it from 'get_current_waves'. However, it doesn't explicitly state when NOT to use it or mention any prerequisites or alternatives beyond the sibling 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?

No annotations provided, so description carries full burden. It discloses rate limiting and message content restrictions but lacks details on response or privacy. Adequate but not thorough.

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

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

Two sentences, no redundancy. Purpose first, then additional guidelines. Every sentence adds value. Highly 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?

For a simple feedback tool with comprehensive schema, the description covers purpose, usage, and limits. Could be more complete about what happens after sending, but still sufficient for correct invocation.

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

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

All 3 parameters are fully described in the schema (100% coverage). The description adds behavioral context for the 'message' parameter (not to include user prompts), but the schema already provides meaning. Baseline 3.

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' with specific use cases (bug reports, feature requests, etc.). It distinguishes itself from sibling tools which are data/query-oriented.

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 guidance on when to use (bug reports, feature requests, etc.) and what to include/exclude in messages. Rate limit is mentioned. No explicit when-not-to-use, but siblings are very different so it's sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by specifying the data source ('CF analytics-engine'), lack of PII, and caching behavior (5min-1h). No contradiction.

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

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

Two short paragraphs with clear front-loading. Every sentence adds value: function, uses, data source, caching. 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?

With one well-documented parameter, no required fields, and no output schema, the description fully informs the agent about what the tool returns and how to use it. Suitable for a simple lookup.

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

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

Schema has 100% coverage with one parameter. Description adds semantic nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which goes beyond the schema's enum list.

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

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

The description uses a specific verb ('returns') and clearly states the resources: 'top tools, top packs, and total call volume'. It distinguishes from siblings like 'discover_tools' by emphasizing trending behavior derived from other AI agents.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and explains the effect of window choice. Lacks explicit alternatives or when-not-to-use, but covers context well.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds detail about how the tool walks child markets, extracts dates/thresholds, sorts, and reports violations. It also describes the return format. This is above average transparency, though it omits edge cases like 'no arbitrage found' or error handling.

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: it starts with the purpose, then explains the logic, then usage, then output format. Each sentence adds value. However, it is slightly longer than necessary; the example could be shortened. Still, good front-loading and efficiency.

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 and no output schema, the description provides a thorough explanation of the arbitrage logic and return structure. It covers the key contextual information needed for an agent to select and invoke the tool correctly. Missing error handling or default behavior, but overall complete enough.

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

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

The sole parameter 'event' has a schema description: 'Polymarket event slug ... or full URL.' The description repeats this exact information with 'Pass a Polymarket event slug or URL.' Since schema coverage is 100%, baseline is 3, and the description adds no new semantic meaning beyond the schema.

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

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

The description clearly states 'Find arbitrage opportunities within a Polymarket event' and explains the specific mechanism (monotonicity violations). The example with BTC thresholds concretely illustrates the purpose. This differentiates it from sibling tools like polymarket_edges, which likely serves a different 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?

The description explicitly says 'Pass a Polymarket event slug or URL', providing clear when-to-use guidance. However, it does not mention when not to use this tool or offer alternatives like polymarket_edges for other Polymarket analyses. The context is clear but lacks 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 (readOnlyHint, openWorldHint, destructiveHint) are consistent. Description adds substantial context: scanning top markets, grouping by asset, fetching price history once, computing model probability, ranking by edge magnitude, and returning suggested trade direction. No contradictions.

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

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

Description is relatively concise given the complexity, with a logical structure: main purpose, model explanation, ranking process, and use case. Minor redundancy but no fluff.

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

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

The description fully explains the tool's behavior: it scans, groups, fetches, computes, and ranks. It specifies coverage (crypto-price bets), data sources (FRED, coinpaprika), and output (top N with suggested direction). No output schema needed for this context.

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

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

Schema description coverage is 100% with each parameter documented. Description does not add extra meaning beyond what schema provides (limit, window, min_edge_pp). Baseline score for 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 scans high-volume Polymarket markets and returns those where Pipeworx data disagrees most with market price, specifying the model and data sources. It distinguishes from siblings like polymarket_arbitrage by focusing on edge detection for betting opportunities.

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

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

The description implies usage for discovering betting opportunities without manual browsing, but lacks explicit when-not-to-use or alternative tool differentiation (e.g., arbitrage). Clear context but no 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 already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral details: the two modes, parameter overriding logic, and the exact return structure (leg-by-leg prices and spread). 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 well-structured, starting with purpose, then modes, then return values. Every sentence adds value without redundancy.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers purpose, parameter semantics, return format, and use cases. No gaps remain.

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

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

With 100% schema description coverage, the description adds rich semantics: it explains the two modes, interaction between topic and explicit parameters, and how overrides work. This goes well beyond schema descriptions.

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

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

The description clearly states 'cross-venue spread between Kalshi and Polymarket for the same resolving question,' with specific verb ('calculate') implied and resource ('spread') identified. It distinguishes between topic and explicit modes, setting it apart from sibling tools like polymarket_arbitrage.

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

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

The description explains two usage modes (topic shortcuts vs explicit pairings) and provides examples, but does not explicitly state when to avoid using the tool 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?

No annotations are provided, so the description carries the full burden. It describes the tool's behavior (retrieval/listing of memories) and context (session-based or previous sessions), but lacks details on error handling, performance characteristics, or data format. It adequately covers basic functionality but misses deeper behavioral 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?

The description is appropriately sized and front-loaded: two concise sentences that directly state the tool's purpose and usage. Every sentence earns its place by providing essential information without 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 the tool's moderate complexity (retrieval/listing with one optional parameter) and no annotations or output schema, the description is somewhat complete but lacks details on return values, error cases, or memory persistence. It covers basic usage but leaves gaps in full operational context.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter. The description adds value by explaining the semantics: 'omit key' to list all keys, and that the key retrieves 'previously stored memory.' This clarifies usage beyond the schema's technical description, though it doesn't add syntax or format details.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'). It distinguishes from siblings by specifying it's for retrieving context saved earlier, unlike 'remember' (likely for saving) or 'forget' (likely for deleting).

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 vs alternatives: 'Retrieve a previously stored memory by key, or list all stored memories (omit key).' It also specifies context: 'Use this to retrieve context you saved earlier in the session or in previous sessions,' clearly indicating its role in memory retrieval rather than other operations.

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 fan-out to SEC EDGAR, GDELT, USPTO; accepted date formats; return structure (structured changes, total_changes count, pipeworx:// URIs). Does not mention read-only or destructive nature, but given the tool's purpose, it's implicitly safe.

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

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

Description is concise (3 sentences) and front-loaded with purpose. Every sentence adds essential detail without redundancy. Efficiently conveys multi-source behavior, date formats, and return elements.

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 3 required parameters and no output schema, the description adequately explains input expectations and return structure. It mentions structured changes with counts and URIs, which is sufficient for agents to understand what the tool returns. Could optionally add more detail on the return format but is complete enough.

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

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

Schema covers all 3 parameters (100% coverage), but description adds valuable context: explains 'since' accepts ISO date or relative ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for monitoring, clarifies 'value' can be ticker or CIK, and notes 'type' currently only supports 'company'. This goes beyond the schema's basic descriptions.

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

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

Describes specific verb ('get what's new') and resource ('entity changes'), clearly distinguishing from sibling tools like entity_profile (static profile) or compare_entities (comparison). The description explicitly states the tool's function and its multi-source fan-out behavior.

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 use cases: 'brief me on what happened with X' or change-monitoring workflows. While it does not mention when not to use or alternatives, the provided context is clear and sufficient for typical agent decision-making.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool stores data in session memory, distinguishes between authenticated (persistent) and anonymous (24-hour) sessions, and implies it's a write operation. It adds context beyond the schema, such as session duration and authentication effects, though it could mention limitations like storage capacity or error handling.

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 appropriately sized and front-loaded, with two sentences that efficiently convey purpose, usage, and behavioral context without redundancy. Each sentence adds value: the first defines the action and use cases, and the second clarifies persistence rules, making it concise and well-structured.

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

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

Given the tool's moderate complexity (2 required parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, and key behavioral aspects like session persistence. However, it lacks details on return values (since no output schema exists) and potential errors or limitations, leaving minor gaps in full context.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('key' and 'value') with examples. The description adds minimal semantic value beyond the schema by implying usage contexts ('findings, addresses, preferences, notes'), but it does not provide additional syntax, constraints, or format details. This meets the baseline of 3 when the schema handles most documentation.

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

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

The description clearly states the tool's purpose with specific verbs ('store a key-value pair') and resource ('in your session memory'), distinguishing it from siblings like 'recall' (retrieval) and 'forget' (deletion). It explicitly mentions what can be saved ('intermediate findings, user preferences, or context across tool calls'), making the purpose unambiguous and well-defined.

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

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

The description provides clear context on when to use this tool ('to save intermediate findings, user preferences, or context across tool calls') and hints at alternatives by mentioning persistence differences for authenticated vs. anonymous users. However, it does not explicitly name sibling tools like 'recall' or 'forget' as alternatives, nor does it specify when not to use it (e.g., for temporary vs. long-term storage).

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?

Describes returned data (ticker, CIK, name, URIs) and that it's a single call, but lacks details on error handling, edge cases (e.g., unresolved entity), or potential side effects. No annotations to supplement.

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

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

Two sentences with no wasted words, front-loaded with purpose. Efficient and to the point.

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 the core functionality well for a simple 2-param tool. Could mention error scenarios or limits, but overall sufficient for an agent to understand basic usage.

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

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

Schema coverage is 100% and the description adds meaningful examples and context (e.g., 'AAPL' as ticker, '0000320193' as CIK) that enhance understanding 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?

Clearly states the tool resolves entities to canonical IDs across Pipeworx data sources, with a specific verb and resource. Differentiates from siblings by noting it replaces 2-3 lookup calls.

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

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

Explicitly mentions the supported entity type (company) and input formats (ticker, CIK, name). Provides context on efficiency gains but does not explicitly discuss when not to use it or compare to direct siblings like ask_pipeworx.

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

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

The description reveals that the tool internally calls ai_visibility_check for each entity, ranks results, and returns a ranked list with score, confidence, and signal density. This adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.).

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 plus a parenthetical example. It front-loads the core purpose, every sentence adds value, and no information is redundant.

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 input constraints (2-8 entities, optional models and context), explains the internal process (probes with ai_visibility_check), and describes the output (ranked list with score, confidence, signal density). No output schema exists, but the description compensates adequately.

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 semantic value by explaining that the first entity in 'entities' is treated as the subject and the rest as competitors, and that 'context' disambiguates common names. This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general 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 states it is useful for competitive AI-marketing audits, giving a clear use case. It implies when not to use (single entity) but does not explicitly name alternatives; however, the context is sufficient 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?

With no annotations, the description carries full burden. It explains the return values (verdict, actual value, citation, percent delta) and source (SEC EDGAR + XBRL), but does not disclose limitations like unsupported claim types, data freshness, or potential cost/delay, leaving behavioral gaps.

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 well-structured sentences. The first states purpose and scope; the second details returns and benefits. No word is wasted, and key information is 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?

Given the single parameter and no output schema, the description adequately explains the return values and scope. It is mostly complete, though it could mention error handling or specific claim format requirements to fully prepare the 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?

The input schema covers the 'claim' parameter syntax with examples. The description adds value by clarifying the supported claim domain (company-financial, US public companies) beyond the schema's generic description, helping the agent choose appropriate claims.

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

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

The description clearly states the tool fact-checks natural-language claims against authoritative sources, specifies support for company-financial claims (revenue/net income/cash) for public US companies, and distinguishes itself from siblings like ask_pipeworx or compare_entities by its specialized function and efficiency.

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 indicates when to use the tool (fact-checking financial claims) and notes it replaces multiple sequential agent calls, providing context for its advantage. However, it does not explicitly state when not to use it or name specific sibling alternatives.

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