Cta

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, so the safety profile is clear. The description adds valuable behavioral context: it returns per-model {score, confidence, signals, raw_response} + combined view, notes that Anthropic calls require a BYO key and direct payment, and that the default model is free. There are no contradictions.

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

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

The description is concise: three sentences covering the core action, optional key usage, and return structure plus use cases. Every sentence adds essential information without redundancy. The most important details (probing LLMs and scoring) are 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?

All four parameters are adequately described, the return structure is given (per-model fields + combined view), and use cases are listed. Annotations cover behavioral traits fully. There is no output schema, but the description compensates by detailing the output. For a tool of moderate complexity with 4 parameters and no nested objects, the description is complete and leaves no major gaps.

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

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

Schema description coverage is 100%, with each parameter already having a description. The description adds value by naming the default model ('Workers AI Llama-3.3-70b'), clarifying that _apiKey is passed straight through to Anthropic's API, and providing examples for the context parameter (e.g., 'Boston restaurant'). This enriches 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?

The description uses specific verbs and resources: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It clearly distinguishes itself from sibling tools like ask_pipeworx (which answers questions) or scan_competitor_ai_presence (which likely does a broader scan) by focusing on visibility scoring across multiple models with a default free model.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and how to include Anthropic (BYO key). However, it does not explicitly mention when not to use it or list alternative tools for similar tasks, though the context is clear enough to guide appropriate usage.

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 annotations already covering read-only/idempotent/non-destructive behavior, the description adds valuable context: it routes to 5,501 tools, fills arguments, returns citation URIs, and notes it's a single fast call that works across tiers. It does not go into failure modes or rate limits, but it provides solid behavioral disclosure 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 more verbose than the minimal examples, but every sentence carries useful information: source domains, use triggers, alternatives, and output characteristics. It is well-structured with a clear hierarchy (preference, usage, escalation). A slight trim could tighten it, but it earns a solid 4.

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

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

Given the tool's aggregation complexity and the lack of an output schema, the description is thorough: it covers what the tool does, what it returns (structured answer + citation URIs), when to use it, when to use alternatives, and provides multiple concrete examples. It is complete enough for an agent to select and invoke the tool confidently.

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

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

The input schema covers 100% of parameters and defines aliases clearly, so the baseline is 3. The description adds meaning through example questions and broad guidance on what types of questions are appropriate, which helps the agent craft a well-formed 'question' value. This goes beyond the schema but not by a huge margin.

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 function: it routes natural-language questions to the appropriate underlying tools across 5,501 tools and 1,441 sources, fills arguments, and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unmistakable.

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

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

The description provides explicit, comprehensive usage guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data', lists trigger phrases ('what is', 'look up', 'find'), gives concrete examples, and nails down when to escalate to ask_pipeworx_grounded or deep_research. It also clarifies that ask_pipeworx handles breaking news through routing.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses the experimental nature, the possibility of live routing changes, the current equality to the stable version, and the fact that it returns identical responses. This adds crucial behavioral context about variability and purpose without contradicting any annotations.

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

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

The description is four sentences, each serving a clear purpose: identifying beta status, stating current state, giving usage instruction, and clarifying the fallback misconception. It is front-loaded with the core identity, and there is no fluff or repetition.

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

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

The description thoroughly covers the beta aspect, usage, current state, and relationship to the stable router. Given the tool's complexity (a routing variant) and lack of output schema, it could benefit from briefly explaining what 'universal router' does, but the sibling tool name and context make this mostly implied, so a small gap remains.

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

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

The input schema has 100% coverage, documenting the 'question' field and its aliases. The description adds no parameter-specific meaning beyond saying 'same arguments' as ask_pipeworx, which doesn't supplement the already-complete schema. Thus, the baseline of 3 applies.

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

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

The description clearly defines this as a beta version of ask_pipeworx, a universal router, and distinguishes it from the stable sibling by noting it runs candidate routing improvements. It explicitly states it is a full working router with the same 5,501 tools, arguments, and response shape, and clarifies the current state (no active candidate, so identical to ask_pipeworx).

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 explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that this is not a fallback, but it does not explicitly state when to avoid it (e.g., in production) or mention alternatives like ask_pipeworx_grounded, so a fully comprehensive usage spec is missing.

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, but the description adds substantial behavioral detail: it only extracts from tool results, returns refusal_reason values like 'not_in_source' and 'data_truncated', and costs one extra LLM call. No contradiction with annotations.

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

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

Every sentence is informative: purpose, mechanism, return shape, refusal modes, use cases, and tradeoff. Front-loaded with the core value proposition and ends with actionable guidance. Dense but each clause earns its place.

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

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

No output schema exists, but the description specifies full success/refusal return objects, refusal reason values, and cost implications. It covers routing scale, when to use, and sibling differentiation, making the tool fully invocable by 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?

Input schema covers 100% of parameters with descriptions, including aliases for question. The description does not need to restate parameters and adds no syntax or format detail beyond what the schema provides. Baseline 3 applies.

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

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

Description uses a specific verb+resource: 'EXTRACTS the answer using ONLY what the tool result contains' and characterizes it as a hallucination-resistant answer mode for high-stakes reads. It explicitly distinguishes from sibling ask_pipeworx by noting same routing but grounded extraction. The purpose is unambiguous and non-tautological.

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

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

Explicit when to use: 'Use whenever an answer will be quoted, cited, or acted on' with concrete examples. Explicit when not to use: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost. This directly supports tool selection 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 already state readOnlyHint=true, idempotentHint=true. The description adds substantial behavioral detail: fan-out logic per classifier category, response shape with specific fields (e.g., market_match_confidence, parent_event), safety short-circuits for low-confidence and closed markets, wide-spread tradeability notes, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is a single dense paragraph of over 500 words, with many details packed together. While front-loaded with the core purpose, it lacks section breaks or bullet points for readability. Information like resolver contract and parent event extractor appears in a continuous flow, reducing clarity. Every sentence adds value, but structure is poor.

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 comprehensively covers return values: result.market, result.analysis, result.evidence, resolver contract (market_match_confidence, alternatives, suggestions), parent event extractor, news fallback fields, safety states, and cancellation rule parsing. Edge cases like closed markets, wide spreads, and low-confidence matches are explicitly handled. The description leaves little ambiguity about the tool's behavior and responses.

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 each parameter already described. The input schema for 'market' covers slug, URL, and question text; 'depth' explains quick vs thorough; 'include_raw' explains summarization vs full payloads. The description provides fan-out examples (e.g., BTC bet → coingecko+fred+gdelt+gnews) but these illustrate behavior, not parameter meaning. Baseline 3 is appropriate as the schema does the work.

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

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

The description clearly states the verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and lists concrete use cases like 'should I bet on X'. This distinguishes it from sibling Polymarket tools such as polymarket_edges or polymarket_arbitrage, which focus on narrower tasks.

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 explicit use contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly state when NOT to use this tool or mention specific alternatives among the many sibling tools (e.g., polymarket_edges, ask_pipeworx). The guidance 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 already indicate read-only, idempotent behavior. Description adds valuable detail: pulls latest 10-K data for companies (with fiscal year handling), FAERS data for drugs, and returns citation URIs. 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?

Approximately 6 sentences, front-loaded with common query patterns. Every sentence adds value—no redundant or superfluous 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 the tool's complexity (two entity types, multiple data sources, sorting, citations) and lack of output schema, the description thoroughly covers behavior, data sources, sorting, and result format.

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 meaning: explains entity types ('company' vs 'drug') what data each pulls, and clarifies values format (tickers/CIKs vs drug names) with examples.

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

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

Description uses specific verbs ('compare', 'side-by-side') and resources ('companies', 'drugs'), with clear examples like 'X vs Y' and 'rank these companies'. It distinguishes itself from sibling tools like entity_profile by focusing on multi-entity 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear context for use. It implicitly excludes single-entity queries but doesn't name the exact alternative tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds behavioral context by specifying that it returns 'every vehicle currently running' and lists the output fields, which are not in annotations. It does not contradict annotations, but could mention rate limits or authentication requirements.

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

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

The description is a single sentence with an example, front-loading the core purpose and output fields. Every word contributes to understanding, with no fluff or repetition.

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

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

No output schema exists, but the description compensates by listing return fields (lat/lon, heading, destination, delayed flag, distance). It is adequate for a simple tool, though it could explicitly state the response is a list of vehicles. The open-world hint is reinforced by mentioning the CTA bus tracker source.

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 both route and _apiKey parameters described. The description provides an example call and clarifies the route parameter can be comma-separated (already in schema), adding marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns live CTA bus positions for a route, listing specific fields (lat/lon, heading, destination, delayed flag, distance). It provides a concrete example query and distinguishes it from sibling tools like cta_bus_predictions and cta_train_positions by focusing solely on bus positions.

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 when you need current positions of buses on a given route, as shown in the example. However, it does not explicitly state when to avoid it (e.g., for predictions) or name alternatives, leaving some ambiguity for the agent.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint=false, covering safety. Description adds behavioral details: returns predictions with 'DUE' meaning now, and lookup behavior for find_stop. 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?

Two sentences plus example, front-loading purpose and key patterns. Information-dense but not wasteful. Could be slightly more concise, but effective.

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

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

Covers main usage patterns (stop_id and find_stop), key output fields, and lookup behavior. Optional params like max, direction, _apiKey are documented in schema; description omits them, but schema fills gaps. Good enough for a read-only tool with full schema descriptions.

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 3. Description adds meaning beyond schema: explains stop_id comes from sign, find_stop is a fragment requiring route, and provides a concrete example. Adds 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?

Description clearly states it provides bus arrival predictions at a stop, listing output fields (route, destination, minutes, delay, vehicle id). Sibling tools like cta_bus_positions and cta_train_arrivals are differentiated by context and verb.

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?

Clearly distinguishes two usage patterns: use stop_id when known, or route+find_stop when only stop name is known. Provides example. Does not explicitly exclude alternative tools, but context implies this is for predictions vs. positions.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds behavioral context beyond annotations: it specifies the return format (line color, destination, arrival time, minutes_away, flags, platform description) and how station input works (name or mapid). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the main purpose, includes examples, and lists key outputs. 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?

For a tool with 4 parameters and no output schema, the description adequately explains return values (train details, flags, platform) and input formats. It covers what the agent needs to know for invocation. Slightly missing details on error handling or timezone but sufficient given complexity.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema by explaining that station can be a name or mapid, route disambiguates same-named stations, and max limits arrivals. Example usage clarifies parameter interaction.

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 defines the tool's purpose: real-time CTA 'L' train arrivals at a station. It uses specific verbs ('returns', 'answers') and resources ('next train', 'line color'). It distinguishes from siblings like cta_train_positions by focusing on arrivals at a station rather than train positions.

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 with examples and acceptable inputs (station name or mapid), but does not explicitly state when to use this tool versus alternatives like cta_train_positions. No exclusions or when-not scenarios are mentioned.

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 and idempotent. Description adds value by detailing what data is returned (lat/lon, heading, etc.) and that it's live.

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

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

Single sentence plus example, no fluff. Front-loaded with 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?

Despite no output schema, description lists return fields. Complete for a simple 2-param tool with 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%, so baseline is 3. Description adds an example and clarifies routes format, pushing it to 4.

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 live CTA train positions, listing specific lines and data fields. It distinguishes from siblings like cta_train_arrivals by focusing on positions.

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 an explicit example and lists accepted lines. Does not explicitly state when not to use, but sibling names imply distinction.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavior beyond that: returns gaps[] for unanswered facets, never invents findings, provides citation_uri only when fetchable, semantically excerpts relevant passages, and gives latency expectations (15-60s, up to 90s for thorough). This is a rich behavioral profile well 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 logically organized and front-loaded with critical access constraints and alternative guidance, but it is quite long and repeats depth semantics already covered in the schema. Most sentences earn their place, though a tighter edit could remove some 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?

For a tool without an output schema and with significant internal complexity, the description is remarkably complete: it covers input nature, depth behavior, output format (findings packet, gaps, contradictions), citation integrity, excerpting, latency, and limitations. No critical information for correct invocation is missing.

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

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

Schema covers both parameters at 100% with descriptive enum text, so baseline is 3. The description adds extra value by noting the paid-plan constraint for depth:thorough and clarifying that standard/thorough return contradictions with hop fields on findings. These are meaningful but not extensive additions, as most parameter semantics already live in the schema.

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

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

Description clearly states it performs grounded multi-source research across Pipeworx's 1441 structured data sources, explicitly distinguishing itself from open-web search. The verb 'research' and resource 'structured data sources' are specific, and it further differentiates from sibling tools like ask_pipeworx by describing decomposition and parallel tool routing.

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 (broad/multi-part questions over structured data) and when not to (single lookups, breaking news), naming ask_pipeworx as the alternative in both cases. Also provides account-tier guidance: unsigned users should use ask_pipeworx, and depth:'thorough' requires a paid plan.

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, destructiveHint, and idempotentHint. The description adds valuable behavioral context: 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This clarifies output format and reusability without contradicting 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 (5 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, use-case examples, output behavior, and when to call. No redundant or unnecessary words.

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

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

Given the tool's meta-function and absence of output schema, the description fully covers what the tool does, how to use it, and what it returns. It is complete for an agent to understand and invoke the tool correctly, especially with the context of many sibling tools.

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 marginal value by explaining the query parameter's purpose ('Natural language description of what you want to do') and listing aliases, but these are already in the schema. The examples in the input schema provide more context than 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: 'Find tools by describing the data or task.' It provides specific examples of use cases (SEC filings, financials, etc.) and distinguishes itself from sibling tools that are domain-specific retrievals. The verb 'find' and resource 'tools' are precise.

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

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

The description includes explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists scenarios where browsing/searching is appropriate. While it doesn't explicitly state when not to use it, the context is sufficient for selection.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral context: fans across multiple sources, returns specific fields, mentions patent API sunset with soft-fail behavior. No contradiction with annotations; description enriches understanding.

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 long but well-structured with examples and a bullet-like breakdown of return fields. Front-loaded with query examples. Every sentence adds value, though minor trimming could improve conciseness.

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

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

No output schema, so description must explain return values. It does: lists CIK, company name, recent filings with URIs, fundamentals, patents, news, LEI. Also covers parameter details and failure modes. Complete for a complex multi-source tool.

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

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

Schema already describes both parameters with 100% coverage. Description adds extra context: type includes future entity types, value requires zero-padded CIK, and clarifies that names are not accepted. This adds value beyond schema.

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

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

Description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call', with specific examples like 'Tell me about X' and 'brief me on Tesla'. It distinguishes from sibling tools like resolve_entity by noting that names require that tool first.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also warns that 'names not supported (use resolve_entity first if you only have a name)', providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds 'clear sensitive data' context but doesn't discuss edge cases like missing key or required permissions.

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

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

Two sentences, no wasted words. First sentence defines purpose, second provides usage guidance. Efficient 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?

For a simple one-parameter tool with annotations and no output schema, the description covers purpose, usage, and pairing. Lacks detail on error behavior but adequate for basic 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 coverage is 100% with parameter 'key' described as 'Memory key to delete'. Description reinforces 'by key' but adds no new semantic detail beyond schema.

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

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

Description clearly states 'delete a previously stored memory by key' with a specific verb and resource. It distinguishes from sibling tools by mentioning 'pair with remember and recall', making the role as delete counterpart explicit.

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 use cases: when context is stale, task done, or to clear sensitive data. Lacks explicit alternatives or when-not-to-use, but pairing mention gives 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining the process (fetches page, extracts title/description/key links, emits markdown) and the output format. 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 (3 sentences), front-loaded with the main purpose, followed by process details 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?

For a tool with 2 simple parameters and no output schema, the description fully covers input, output, and use cases. It explains the output format and purpose, making it complete for an AI agent.

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

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

Schema coverage is 100%, with both 'url' and 'max_links' described in the schema. The description reinforces the 'max_links' default and max values but does not add new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description uses a specific verb-resource combination ('Generate a production-ready llms.txt file') and lists concrete use cases (client's site indexing, drafting for own project, auditing competitor). It clearly distinguishes from sibling tools, which are all unrelated.

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 the tool is useful ('Useful for: ...') and provides context for AI crawlers. It does not explicitly list when not to use or mention alternatives, but the context is clear and sufficient for an AI agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about default return (active only) and inclusion of inactive via parameter. 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?

Two sentences, front-loaded purpose, no wasted words. Efficiently 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 simple tool with one optional param and no output schema, description covers purpose, return fields, usage context, and parameter behavior comprehensively.

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

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

Schema covers 100% of parameter with description. Main description does not add significant meaning beyond what 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 states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. Clearly distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implies when not to use and references 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 annotations all false, the description carries full weight. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), and the fact it's free ('Free; doesn't count against your tool-call quota'). It also explains the daily digest and roadmap impact.

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 long but each sentence serves a purpose, and it is well-structured with clear 'Use when', 'ONLY for', 'Filing', and rate-limit info. It could be slightly more concise, but the logical flow makes it easy to scan.

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 the two main workflows (new feedback and claim_token lookup) and the return behavior ('read whether it was fixed and what changed'). It lacks an output schema, but the description compensates. Some borderline details like what defines an 'identifier' could be added, but overall it's complete for the tool's purpose.

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

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

The schema already provides 100% coverage, but the description adds value beyond that. For claim_token, it explains the round-trip usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). For message, it adds 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies expected content beyond the schema's generic text.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools by specifying that it is for feedback/reporting issues, not for asking questions (e.g., ask_pipeworx). It also provides concrete use cases (bug, feature/data_gap, praise).

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 use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions: 'ONLY for tools served by this Pipeworx connection' and directs users to file with another server for non-Pipeworx tools.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description adds caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII), providing rich 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?

Front-loaded with core function, followed by bulleted use cases, then technical details—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?

The description explains the return concept ('pack, tool, count') and caching, but lacks explicit output structure. For a simple tool with one optional param, it is 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 coverage is 100%, so baseline 3. The description adds value by explaining the effect of different window lengths (short for hot, long for steady-state), beyond the 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 clearly states it returns 'top tools, top packs, and total call volume' over a recent window, distinguishing it from siblings like 'discover_tools' by focusing on what other AI agents are calling.

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?

Three explicit use cases are listed, but no guidance on when not to use this tool or alternatives (e.g., 'discover_tools') is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds rich behavioral context: it walks child markets, checks date/threshold ordering, computes partition checks, filters placeholders, and performs fill checks against live depth. 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 comprehensive but somewhat verbose; it could be more structured (e.g., bullet points) for easier scanning. However, every sentence serves a purpose and provides necessary detail.

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

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

Given the complexity of the tool (multiple modes, semantic anchors, partition filters, fill checks), the description covers all essential aspects. It explains the response structure and references related tools. No output schema exists, but the description compensates with detailed explanations.

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 already descriptive parameter descriptions. The description adds valuable semantic context: explains that event slugs or full URLs are accepted, clarifies the behavior when no args are passed, and defines the 'topic' parameter's purpose in cross-event scanning.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between modes (trending scan, event, topic) and clearly differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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 guidance on when to use each mode (no args for trending scan, event for specific market, topic for cross-event scanning) and mentions when not to trade (realizable_edge_pp <= 0 suggests book overround). It also directs to polymarket_fill_risk for custom sizing, offering 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?

The description goes far beyond annotations, detailing model families, tradeable-edge knobs, response structure, diagnostics, and caching behavior. It discloses internal logic (e.g., model calculations, filter conditions) and output format comprehensively.

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 with a clear front-loaded purpose, segmented explanation, and logical flow. It is verbose but every sentence earns its place given the tool's complexity. Could be slightly more concise without losing clarity.

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

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

With no output schema, the description fully describes the response structure (by_segment, diagnostics, fed info), caching, and filtering knobs. It covers all aspects needed for an agent to understand what the tool returns and how to use it 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 coverage is 100% with descriptions for all 9 parameters, but the description adds contextual value beyond schema definitions, such as explaining slippage assumptions and the purpose of min_partition_leg_kelly. This supplements the schema without being redundant.

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 Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and identifies the key resource (Polymarket markets with Pipeworx data). Though sibling tools exist, the unique focus on Pipeworx disagreement differentiates it.

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 positions the tool for 'what should I bet on today' and explains the three segments and filtering knobs, giving clear usage context. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

The description adds significant detail beyond annotations, including the data source (daily snapshots), how data availability is indicated via snapshot_dates with gaps, computation details for decay (daily closes, not intraday), and limits (60-day TTL, snapshot start time). This fully informs the agent of 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 well-structured with clear sections (RESPONSE:, LIMITS:) and front-loaded purpose. While lengthy, every sentence adds value and there is minimal redundancy. Could be slightly more terse but remains 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?

Without an output schema, the description fully compensates by detailing the response structure (tracked, expired, snapshot_dates), computation, and limitations. It leaves no significant gaps for the agent to infer.

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 useful context like defaults (days=14, window='1wk') and explains 'window' as a snapshot family, enriching understanding 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 provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes from the sibling polymarket_edges by focusing on temporal analysis rather than current 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 implies usage when needing to understand edge history vs. current state, contrasting a 'fresh wide edge' with a '3-week-old wide edge'. However, it does not explicitly state when not to use it or name alternative tools for other scenarios, leaving some room for ambiguity.

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

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

Describes read-only behavior (walking ladder), return fields (top_of_book, vwap_fill_price, etc.), and risks (thin legs, forced directional risk). Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description adds substantial 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?

Description is relatively long but well-structured with sections for single-market, basket, and usage advice. Every sentence adds value, though slightly verbose. Front-loaded with main 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?

Complex tool with two modes and many return fields; description covers everything needed including return values for both modes, parameter behavior, and risks. No output schema but description compensates fully.

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

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

Schema coverage is 100%, baseline 3. Description adds significant value: explains default side for basket (auto), size_usd meaning per mode (max spend vs target proceeds vs settlement notional), and clamp range. Far exceeds minimal 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?

Description clearly states tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth', with specific verb and resource. Clearly distinguishes single-market and basket modes, and differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why: theoretical overround on thin books is not capturable, and partial fills convert arb to unhedged directional position.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds substantial transparency about safety fields (compatibility_warning, temporal_alignment, skipped counters) and explains when spreads are meaningless (e.g., temporal gap, mismatched bet shapes). No contradiction with annotations.

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

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

The description is comprehensive but somewhat verbose, especially with detailed explanations of safety fields. It front-loads the purpose and modes effectively, but could be trimmed for conciseness without losing essential information.

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

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

Given the complexity of cross-venue spread and the absence of an output schema, the description fully covers the response structure (prices, top spreads, compatibility/temporal warnings). All important behavioral aspects are disclosed, making the tool self-contained for an AI agent.

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

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

Schema coverage is 100%, so parameters are documented. The description adds context: it explains the `topic` parameter's enumeration and purpose, and clarifies that `kalshi_event_ticker` and `polymarket_event_slug` override the topic-mapped sides. This enriches 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?

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from siblings by focusing on cross-venue comparison, and specifies two modes (topic shortcuts and explicit tickers) with concrete examples.

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 detailed usage guidance, including when to use (identical bet shapes, temporal alignment) and warnings about non-tradeable situations (compatibility_warning, temporal misalignment). It explicitly notes that pre-mapped topics often return warnings, setting realistic expectations. However, it does not name alternative tools for comparison.

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

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

Adds behavioral context beyond annotations: explains omission behavior (list all keys), scoping by identifier, and pairing with other tools. Annotations already indicate read-only and idempotent, so description complements 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?

Two sentences convey purpose, usage, scoping, and pairing. Front-loaded with main action, no filler. Every sentence serves a 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?

For a tool with one optional parameter and no output schema, description fully explains behavior, scoping, and integration with siblings. No gaps.

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

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

With 100% schema coverage, description adds meaning beyond schema: clarifies that omitting 'key' lists all keys. Schema says 'omit to list all keys' but description reinforces and provides usage examples.

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

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

Description clearly states the tool retrieves saved values or lists keys, with specific verb-resource pairing. Distinguishes from siblings 'remember' and 'forget' by using complementary language.

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 concrete examples of when to use (look up ticker, address, notes) and mentions scoping. Does not explicitly exclude scenarios, 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?

The description discloses that setting mark_read:true flags events as read and alters future calls, which is a behavioral side effect. However, the annotation declares readOnlyHint=true, implying no state modification. This contradiction undermines transparency. The description adds useful context about the feed being persistent, but the contradiction is a critical issue.

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

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

The description is relatively concise with three sentences covering purpose, output details, filtering, mark_read behavior, and alternative access. There is slight redundancy between 'Pull fired events' and 'Returns the most recent alerts', but overall 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?

For a tool with 5 optional parameters and no output schema, the description covers the main aspects: what is returned, filtering, mark_read effect, and polling suitability. It lacks details on ordering (beyond 'most recent'), pagination, or error cases, but it is largely 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 baseline is 3. The description adds minimal extra meaning beyond schema: it explains that mark_read flags events read and unread_only returns null read_at. For type and since, it simply restates schema. No significant added 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 clearly states the tool 'pulls fired events from your subscription feed' and specifies it returns recent alerts. It mentions key fields (source, citation_uri, raw payload) and filters (type, since). However, it does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'recent_changes', so it slightly misses sibling distinction.

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 notes that polling works fine and provides an alternative REST endpoint for scripts/dashboards, indicating when to use the tool vs. direct API access. It does not mention explicit when-not-to-use scenarios or compare to other tools, but it gives good contextual guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description adds significant detail: it fans out to multiple sources (SEC EDGAR, GDELT, GNews, USPTO), describes fallback behavior (GDELT preferred, GNews when rate-limited or 5xx), and notes USPTO soft-fail. No contradiction with annotations.

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

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

The description is a single paragraph that packs a lot of information. It is front-loaded with example queries and then details behavior. While concise and informative, it could benefit from slight structuring (e.g., separate lines for parameters or sources) for easier scanning. Still, it earns its place with no wasted words.

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

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

Given the tool's complexity with multiple sources and fallback logic, the description covers all essential aspects: parameters, window specification, return structure (changes[] grouped by source + total_changes + citation URIs), and sibling differentiation. No output schema, but the description adequately explains the return format.

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

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

Schema coverage is 100% with descriptions. The description adds value beyond schema by explaining that 'since' accepts relative shorthand like '7d', '30d', '3m', '1y' and recommends '30d' or '1m'. It also clarifies that 'value' can be a ticker or CIK. This provides practical guidance for 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 provides a change feed for a company including SEC filings, news, and patents. It distinguishes itself from the sibling tool 'entity_profile' which provides a static profile. The verb 'change feed' and resource 'company' are specific.

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

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

The description explicitly tells when to use this tool versus 'entity_profile' for static profiles. It provides example queries like 'What's new with X' and 'latest on Y' but does not explicitly state when not to use it, though 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 indicate idempotentHint=true and destructiveHint=false. The description adds valuable context: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions 24 hours. No contradictions.

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

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

Three sentences, front-loaded with core purpose, each sentence adds value. No redundancy, perfectly 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 tool with 2 required params and no output schema, the description covers all needed context: purpose, usage, persistence, scoping, and sibling tools. Completely 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 covers both params with descriptions. The description adds examples for key (e.g., 'subject_property') and clarifies value as any text, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: saving data for later reuse, with examples like tickers, addresses, preferences. It distinguishes itself from sibling tools recall and forget by explicitly mentioning pairing.

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: 'when you discover something worth carrying forward'. Lists concrete examples and mentions the pairing with recall and forget, effectively communicating when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it mentions internal cascading through multiple lookup endpoints (implying multiple operations under the hood), auto-disambiguation, and citation URI generation. This enriches the agent's understanding of the tool's execution characteristics.

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 with a clear opening example, supported types section, and a closing note on efficiency. While it is longer than necessary, every sentence provides useful information (examples, return values, citation URIs). It is not wasteful, but the detail pushes it slightly beyond the two-sentence ideal.

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

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

With no output schema, the description fully compensates by specifying the return payload for both supported types (ticker, CIK, company name for company; RxCUI, ingredient, brand for drug) and citation URIs. It also covers accepted input formats and disambiguation behavior. This makes the tool's behavior sufficiently predictable for an agent to invoke it correctly.

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

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

The input schema already covers all parameters (type and value) with clear descriptions, so baseline is 3. The description goes beyond by detailing what each type returns (e.g., 'returns ticker + 10-digit CIK + company_name') and specific input formats (e.g., 'ticker (AAPL), CIK (0000320193), or name'). This adds meaning not fully captured by 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 that the tool resolves user-spoken names to canonical identifiers (ticker, CIK, RxCUI) and explicitly lists supported types (company, drug) with concrete outputs. It uses a specific verb ('resolve') and resource, and the examples ('What's the ticker for…') make the purpose unmistakable. This also differentiates it from sibling tools like entity_profile or compare_entities by focusing on identifier lookup.

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 explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups, implying it is a prerequisite step for other tools. However, it does not explicitly name alternative tools or state when not to use it, so it falls just 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density, plus the first entity is treated as the subject.

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 main action, and every sentence adds necessary information 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density) and covers behavior and parameters comprehensively. Annotations cover safety aspects.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context, such as the first entity being the subject and the relationship between models and _apiKey, which adds value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb and resource. It distinguishes from siblings like ai_visibility_check (single probe) and compare_entities (generic 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, with an example question. It implies when to use but does not explicitly state when not to use or list all alternatives, though it contrasts with ai_visibility_check.

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 show readOnly, idempotent, non-destructive. Description adds that it fans out across deps.dev and bundlephobia, mentions potential timeout for first bundlephobia measurement, and states graceful degradation with sources_failed.

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

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

Single paragraph is dense but clear, with no wasted words. Could be broken into sections for readability, but remains efficient.

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

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

No output schema, but description covers summary block, per-advisory detail, links, and alternative versions, plus partial failure behavior. Tool is self-contained with no overlapping siblings.

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% description coverage for both parameters. Description adds context that scoped packages are accepted and version defaults to latest, but does not significantly extend schema knowledge.

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 performs a composite check for adding npm packages, covering license, advisories, version history, bundle size, and ESM/tree-shake support. It specifies the ecosystem and contrasts with other package managers.

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 to use when an agent asks about safety, popularity, or size of a package, and mentions partial failures and alternatives for other ecosystems.

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 embedding model (BGE-base-en), chunking strategy (500-char overlapping windows, cosine similarity), and input cap (200K chars, truncated and flagged). Adds context beyond idempotent and read-only 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?

Single paragraph, front-loaded with purpose, then usage, then technical details. Every sentence adds value; 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?

Covers all important aspects: functionality, use case, technical details, pairing with sibling tool, and what is returned. No output schema, but description sufficiently explains outputs.

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 description adds value: clarifies max length for 'text', gives example queries for 'query', and specifies range and default for 'limit'.

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 performs semantic search inside a fetched record, describing input (text, query) and output (top-N passages with offsets and similarity scores). Distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly advises use when the record is too large for the prompt, explains benefits (saves context, returns only relevant passages), and mentions alternative workflow with ask_pipeworx_grounded.

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

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

Description contradicts idempotentHint annotation by stating 'Returns the new subscription id', implying each call creates a new subscription (non-idempotent). Additionally, describes side effects (creation) consistently with readOnlyHint=false, but the idempotency contradiction is critical.

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?

Front-loaded with main purpose, then elaborates details. Efficient for the complexity, though lengthy; every sentence adds necessary information 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?

Covers return value, account prerequisite, type-specific params, and delivery options. Lacks error handling or rate limits beyond SMS cap, but adequate for a subscription creation 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?

Adds significant value beyond schema: provides concrete examples for each type, details required/optional fields, explains delivery channel behaviors (e.g., webhook signing secret, auto-disable). Coverage is 100%.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Uses specific verb and resource, distinguishes from sibling tools like list_subscriptions and unsubscribe.

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 account requirements (OAuth), type-specific parameters, and delivery channel constraints (SMS limit, phone verification). Implicitly indicates when to use (to set up monitoring) but lacks direct comparison to 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?

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. Description adds behavioral context by describing the output format (category-bucketed examples with tool shapes) and that it's an exploratory onboarding tool, complementing annotations without contradiction.

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

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

Description is dense and front-loaded with query variants, then explains output and usage. Every sentence adds value, but it could be more structured (e.g., bullet points) for quicker scanning. Still efficient with no waste.

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, description adequately explains what the tool returns (category-bucketed example questions with tool+argument shapes). It covers usage, parameter semantics, and is contextualized as an onboarding tool. Complete for its purpose.

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 description for topic. Description adds value by listing example focus areas ('finance', 'pharma', etc.) and explaining that omitting topic gives a cross-category spread. 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?

Description clearly states it returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx by being the onboarding entry point and providing example queries rather than answering directly.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass topic vs omit. Does not explicitly state when not to use, but context is clear.

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

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

Discloses that the row is deactivated, not deleted, and historical events remain accessible via recent_alerts. This adds value beyond annotations (idempotentHint=true, destructiveHint=false) and explains non-obvious side effects.

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

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

Two sentences conveying action, constraint, and side effect. No extraneous words, front-loads 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?

For a single-parameter tool with no output schema, the description covers purpose, ownership constraint, and behavioral side effect. Adequately complete 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 already describes 'id' as subscription uuid. Description adds context that it is returned by subscribe, linking to another tool. With 100% schema coverage, this 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?

Description clearly states 'Cancel a subscription by id.' It uses a specific verb 'Cancel' and resource 'subscription', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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 ownership enforcement, guiding the agent to only cancel own subscriptions. While it doesn't mention alternatives, it provides clear context for appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: explaining the two processing paths (financial vs. other claims), the return verdict with citations, and the efficiency gain over sequential calls. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and trigger phrases, then efficiently covers processing paths, output format, and efficiency. Every sentence adds value without 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?

Despite lacking an output schema, the description fully explains the return value (verdict, actual value with citation, reasoning). Parameter coverage is complete via schema and description. The tool's moderate complexity is well-addressed.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond the schema by explaining the tolerance_pct default behavior and how it overrides claim wording, and provides concrete examples for the claim parameter.

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

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

The description clearly states the tool is for claim verification with natural-language triggers like 'Is it true that…' and fact-checking. It distinguishes itself from siblings by explaining it replaces multiple sequential calls and has specialized handling for company-financial claims via structured data versus other claims via grounded pipeline.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides example triggers. It does not explicitly state when not to use it or list alternatives, but the context strongly implies its niche.

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