Linear

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: the default model, the requirement for an API key for Anthropic, and the return format (per-model score, confidence, signals, raw_response + combined view). This goes beyond annotations.

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

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

The description is two sentences covering purpose, default behavior, optional parameters, return format, and use cases. Every sentence adds value; no fluff. Front-loaded with the core action.

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 4 parameters, no output schema, and rich annotations, the description covers input details, output format, and typical use cases. It doesn't discuss error handling or rate limits, but those are not critical for this tool. Adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning: it explains the default model for the 'models' parameter, the purpose of '_apiKey' (BYO key, cost to user), and the disambiguation role of 'context'. This is helpful but not essential given 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 probes LLMs for knowledge about an entity and scores visibility. The verb 'probe' and resource 'LLMs' are specific, and the output 'visibility score (0-100)' is defined. It distinguishes itself from sibling tools like deep_research or ask_pipeworx by focusing on AI visibility measurement.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use which models (default free workers-ai, optional anthropic with API key) and the cost implication for Anthropic. While it doesn't explicitly state when not to use, the context is sufficient.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive traits. The description adds valuable behavioral context beyond this: it routes to thousands of tools, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier with one fast call. No contradictions and useful operational details.

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 front-loaded with the most important guidance ('PREFER OVER WEB SEARCH', 'START HERE'). It earns its length through concrete examples and alternative tool comparisons, though a few phrases are repetitive and could be tightened.

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 there is no output schema, the description adequately covers return behavior ('structured answer with stable pipeworx:// citation URIs'). It also covers a wide range of domains, usage triggers, and escalation paths to sibling tools, making it sufficiently complete for a tool of this 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 coverage is 100% and all aliases are documented. The description enhances parameter semantics by providing trigger phrases and numerous real-world example queries, helping the agent construct effective 'question' values. This goes beyond the schema's basic alias 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 the tool's function: it routes questions to 5,529 tools across 1,455 sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique role 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 when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives for different scenarios. Also lists trigger phrases and concrete examples, giving clear decision rules.

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, and idempotent hints, and the description adds valuable behavioral context beyond those. It discloses the beta nature, the possibility of candidate routing changes being active, the current inactive state (retired 2026-07-26), and that it is a full working router. This goes beyond annotations without contradicting them.

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

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

The description is a bit long but front-loaded with the essential fact that this is a beta router. Every sentence adds useful context about the identical nature, candidate routing, and experimental status. There is slight redundancy in repeating 'identical' and 'exactly like ask_pipeworx', but overall it remains structured and informative.

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 provides a complete picture for a beta router: what it does, its relationship to the stable version, when to use it, and the experimental evaluation process. Since there is no output schema, it mentions the same response shape as ask_pipeworx, which is adequate. It could elaborate more on the response format, but the reference to the stable tool covers the gap.

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

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

The input schema fully covers all parameters, including the 'question' field and its aliases (q, text, input, query, prompt), with detailed descriptions in the schema itself. The description only says 'same arguments' as ask_pipeworx, which does not add additional meaning beyond the schema's coverage. With 100% schema coverage, the baseline 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 clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by highlighting the experimental candidate routing improvements. This is a specific verb+resource with clear sibling differentiation.

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 to use it 'exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It provides clear context for when to choose this over the stable version, though it does not directly mention alternatives like ask_pipeworx_grounded or explicitly 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the return format including success fields and refusal reasons, the guarantee of using 'ONLY what the tool result contains,' and the additional LLM call cost. This gives the agent a clear behavioral model.

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 dense but well-structured: states purpose, defines return behavior, then gives usage guidance and cost tradeoff. No redundant sentences.

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

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

For a tool with no output schema, the description fully specifies the success and refusal response shapes, typical use cases, and relationship to the sibling tool. It leaves no ambiguity about invocation expectations.

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 provides 100% coverage with descriptions for all aliases and the main 'question' parameter, so the description adds no additional parameter information. 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 is a 'hallucination-resistant answer mode for high-stakes reads' and explains its extraction behavior. It explicitly distinguishes from sibling 'ask_pipeworx' by noting same routing but grounded extraction and refusal modes.

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

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

It provides explicit usage context: 'Use whenever an answer will be quoted, cited, or acted on...' and contrasts with 'ask_pipeworx' with 'prefer ask_pipeworx for casual lookups.' It also explains the cost tradeoff of an extra LLM call.

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 extensive behavioral context: fan-out examples by category, response shapes with specific fields, resolver contract (confidence levels, alternatives, suggestions), parent event extractor, news fallback behavior, safety short-circuits for low-confidence and closed markets, wide-spread handling, and cancellation rule analysis. 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 thorough but verbose. It uses structured headings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) which helps readability, but many details could be condensed. The first sentence clearly states the purpose, but the rest is a dense specification. Some redundancy exists (e.g., fan-out examples are elaborate). A more concise version would improve efficiency for AI parsing.

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 (3 input types, classification, fan-out to multiple data sources, dynamic response shapes, multiple edge cases), the description covers virtually everything. It explains response shapes, resolver contract, parent event extractor, news fields with error handling, multiple safety mechanisms, and cancellation rules. No output schema exists, so the description fully compensates.

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

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

Schema coverage is 100% with good descriptions for all three parameters. The description adds further value by providing examples for 'market' (slug, URL, question text), explaining the 'depth' enum values and default, and detailing the 'include_raw' behavior (summarized vs full payloads, with size estimates). This goes 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 explicitly states the tool researches Polymarket bets using Pipeworx data, with clear verb 'Research' and resource 'Polymarket bet'. It specifies multiple input formats (slug, URL, question text) and gives concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It distinguishes itself from siblings through its unique scope of combining market resolution, classification, and parallel data fan-out.

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 use cases and context for when to use the tool. It mentions 'Use for' explicitly and includes caveats like inspecting market_match_confidence before trusting analysis. However, it does not explicitly state when NOT to use it or compare directly to sibling tools, which would be a minor improvement.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: for companies, it pulls latest 10-K data from SEC EDGAR with proper fiscal year handling; for drugs, it pulls FAERS, FDA approval counts, and trial counts. It also states results are sorted by primary metric 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?

The description is a single dense paragraph but contains all essential information efficiently. It uses imperative statements and examples. It could be slightly more structured (e.g., bullet points), but overall it is concise and well-front-loaded.

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

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

Given the tool's complexity (two entity types, distinct data sources, sorting, citation URIs), the description covers all key aspects. It mentions replacing 8-15 lookups, and although there is no output schema, it describes the return format adequately.

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

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

Schema coverage is 100% with clear descriptions. The description goes beyond the schema by providing examples (e.g., tickers like 'AAPL', drug names like 'ozempic') and explaining the data pulled for each entity type, adding significant 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's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It lists various natural language triggers ('compare', 'vs', 'rank') and explicitly distinguishes itself from sequential single-pack lookups.

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 advises to always prefer this tool over sequential lookups when comparing entities. It also specifies the entity types (company, drug) and the data sources for each, giving clear context on when 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?

Annotations provide a read-only, idempotent, non-destructive hint. The description adds significant behavioral context beyond those hints: account/signup requirements, not open-web search, parallel tool routing, gap[] reporting, contradictions[] in standard/thorough, citation-uri behavior, semantic excerpting, and expected latency (15-90s). 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 long and packs many details, but every sentence delivers distinct, valuable information. However, it is not optimally front-loaded: the first two sentences focus on account requirements and fallback guidance rather than the core purpose, which appears later. Still, the density and organization earn a strong score.

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 complex tool with no output schema, the description fully covers how it works (decomposition, parallel routing, findings packet), return fields (evidence, confidence, source, fetched_at, citation_uri, gaps[]), limitations (structured data only, current-news caveat), depth trade-offs, auth needs, and timing. No critical contextual 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 already provides comprehensive descriptions for both parameters, including the depth enum (quick=3, standard=5, thorough=8) and question guidance ('Broad/multi-part is fine'). The description largely repeats this information (e.g., 'standard re-angles unanswered gaps', 'thorough chases leads'), adding little beyond the schema. With 100% schema coverage, 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 opens with a very specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It clearly distinguishes deep_research from siblings by explicitly naming ask_pipeworx as the alternative for single lookups and current news. The purpose is unmistakable and differentiated.

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 and when-not-to-use guidance: use ask_pipeworx for single lookups, for breaking/current-news, or when not signed in; use deep_research for broad/multi-part structured-data questions. It also details depth-level behavior (standard vs thorough) and account prerequisites. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds detailed return behavior: top-N relevant tools with names, descriptions, full input schemas, ready to call directly.

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, fairly dense but every sentence adds value. Could be slightly more structured, but front-loads purpose and usage. Not verbose.

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

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

No output schema, but description fully explains return content (tool names, descriptions, schemas with examples) and that results are executable. Covers all necessary context.

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

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

Schema coverage is 100% with all parameters described. Description adds value by explaining the 'query' parameter's aliases and the 'limit' parameter's purpose (default 20, max 50).

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

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

The description clearly states the tool finds tools by describing a data or task, listing many example domains. It distinguishes from sibling tools as a meta-tool for discovery.

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 guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Clear when-to-use and implied when-not.

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, etc.), description adds behavior: fans out across multiple sources, mentions specific data sources, patents API sunset soft-fail, and fallback mechanism. 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?

Description is front-loaded with examples and purpose, but slightly verbose with redundant references to name resolution. Still efficient and well-structured overall.

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 compensates by listing return fields, data sources, and limitations (patents sunset). Lacks pagination/error handling but sufficient for decision-making.

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

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

Schema coverage is 100%, and description adds meaning by explaining type constraints, value format (ticker or CIK), and explicit warning that names not supported. Enhances schema guidance.

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

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

Description provides numerous example queries, specifies it returns a full cross-source profile of US public companies, and distinguishes from chaining single-pack lookups. Clear verb+resource+scope, differentiates from sibling tools like resolve_entity.

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 (holistic view), recommends preferring over chaining, and warns against using with names (referring to resolve_entity as alternative). Provides clear context and 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 set destructiveHint=true and readOnlyHint=false, but description adds context like 'clear sensitive data' and 'Delete', confirming destructive behavior 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, each serving a purpose: first declares the action, second gives usage conditions. 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?

For a simple one-parameter destructive tool with full schema coverage and clear annotations, the description provides all needed context (usage, pairing, safety). Output schema is absent but unnecessary for a delete operation.

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

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

Schema coverage is 100% and the single parameter 'key' is described as 'Memory key to delete' in both schema and description. The description adds no significant extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' It specifies a precise verb (Delete) and resource (memory by key), and distinguishes from siblings by mentioning 'remember' and 'recall' as paired tools.

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

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

Provides explicit when-to-use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember' and 'recall', indicating alternative 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds useful context: it fetches the page, extracts content, and outputs standard markdown, which aligns with annotations and provides extra behavioral detail.

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

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

The description is a single paragraph that efficiently covers purpose, behavior, output format, and use cases. It is front-loaded with the main action and remains concise without unnecessary details.

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 two parameters and no output schema, the description is complete. It explains the input, process, output, and typical usage scenarios, leaving no significant 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 coverage is 100%, so parameters are well-defined. The description adds value by explaining the purpose of max_links (with default and max values) and implying the URL parameter's role in fetching the page.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the exact output format and target AI crawlers. It differentiates itself from sibling tools, none of which perform this specific function.

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

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

The description provides explicit use cases (client indexing, personal projects, competitor auditing) and implies when to use it. It does not explicitly state when not to use, but given the tool's narrow purpose, this is acceptable.

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=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description does not add behavioral context beyond stating 'create'. It does not mention idempotency, side effects, or any constraints not already in 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 sentence that front-loads the purpose. It is concise but could benefit from a clearer separation of input and output.

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?

Includes return values and mentions optional description. Given the presence of an output schema and 100% parameter coverage, the description is fairly complete. However, lacks siblings differentiation and usage context.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description mentions 'title' and 'optional description' but does not add meaning beyond the schema for teamId or priority. Baseline score of 3 applies due to high coverage.

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

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

The description clearly states the verb 'create', the resource 'new issue in Linear', and the return values (issue ID, key, title, URL). This distinguishes it from sibling tools like linear_get_issue or linear_list_issues.

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

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

The description implies usage for creating issues but provides no explicit guidance on when to use this tool versus alternatives like linear_search or linear_get_issue. No when-not-to-use information 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 indicate readOnlyHint, idempotentHint, destructiveHint=false. Description adds no behavioral context beyond the return fields, and does not disclose auth requirements, rate limits, or side effects.

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

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

Single sentence, 20 words, front-loaded with action and key details. 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 an output schema exists, the description is fully adequate: it explains purpose, input format, and return contents. For a simple read tool with one parameter, it is 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% with one parameter described as 'Issue identifier (e.g., "ABC-123")'. The description reinforces the format with an example, adding value beyond the schema.

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

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

Description clearly states it gets full details of a Linear issue by ID, listing specific return fields (title, description, state, etc.). It distinguishes from sibling tools like linear_create_issue and linear_list_issues.

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

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

No explicit guidance on when to use this tool vs alternatives like linear_search. The description implies use when you have an issue ID, but lacks exclusions or context for 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?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds that it returns specific fields and supports JSON string filters, but does not discuss pagination behavior or error handling. It adds some value beyond annotations without contradiction.

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

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

The description is two sentences, front-loaded with the purpose. Every word is relevant and no extraneous information. Highly concise and well-structured.

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

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

Given the presence of an output schema, 100% parameter coverage, and safety annotations, the description is largely complete. Minor gap: no mention of error cases for malformed filters, but adequate for a straightforward list 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 coverage is 100% with both parameters described. The description mentions filters by state/priority/assignee, which aligns with schema but does not add new semantic information. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool browses Linear issues with optional filters and lists returned fields. It is specific about verb and resource, but does not explicitly differentiate from sibling tool 'linear_search', which also deals with issues.

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

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

No guidance is provided on when to use this tool versus alternatives like linear_get_issue for single issues or linear_search for more complex queries. The description lacks context on appropriate usage scenarios and exclusions.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already declare the tool's safe, read-only nature. The description adds no additional behavioral context (e.g., pagination, performance, or rate limits) beyond what annotations provide.

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 efficient sentences that front-load the purpose and return fields. No extraneous 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 simplicity (no parameters, clear output with schema), the description fully covers what an agent needs to know 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?

No parameters exist, so the description does not need to add parameter details. Baseline 4 for 0-parameter tools is appropriate.

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

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

Description clearly states 'List all teams in your Linear workspace' with a specific verb and resource, and specifies return fields. It is distinct from sibling tools which focus on issues or other domains.

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

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

No guidance on when to use this tool vs. alternatives. The description only states what it does without providing context for selection among siblings or 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 declare the tool as read-only, idempotent, and non-destructive (readOnlyHint, idempotentHint, destructiveHint). The description adds no further behavioral context beyond the stated return fields, but does not contradict 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 two sentences, each serving a clear purpose: first sentence states the action and resource, second lists return fields. No extraneous words, well front-loaded.

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

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

Given the presence of an output schema and annotations, the description covers core functionality and return structure. Minor gaps exist (e.g., result ordering, case sensitivity), but overall it is complete for a straightforward search 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 coverage is 100%, so the description adds no additional meaning beyond what the schema provides. The description mentions 'by keyword or text' which aligns with the query parameter, but does not elaborate on the first parameter or provide new semantic context.

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

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

The description clearly states the tool searches Linear issues by keyword or text, and lists the return fields (ID, title, state, priority, URL). This distinguishes it from related tools like linear_get_issue, but does not explicitly differentiate from linear_list_issues, which also returns issues.

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

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

No guidance is provided on when to use this tool versus alternatives such as linear_list_issues or linear_get_issue. The description does not mention any conditions, exclusions, or preferences, leaving the agent to infer usage context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by detailing the specific return fields and the optional include_inactive parameter.

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

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

Two sentences, no filler. Every sentence adds necessary 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?

For a simple list tool with one optional parameter and no output schema, description fully explains return structure and usage context.

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

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

Schema description coverage is 100% (include_inactive is documented). Description adds no additional semantic meaning beyond the schema.

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

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

Clearly states it lists the caller's active subscriptions and enumerates return fields (id, type, etc.). 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 tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context.

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

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

Annotations only provide generic hints (readOnlyHint=false, etc.), so the description carries the burden of behavioral disclosure. It reveals concrete behaviors: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, team reads digests daily, and the claim_token workflow for retrieving resolution status. These are valuable beyond any structured annotation.

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 every sentence contributes value: purpose, usage criteria, exclusion, message guidance, claim_token mechanics, rate limits, and roadmap impact. It is front-loaded with the core function and maintains logical flow. It could be slightly tightened, but it is not verbose for the amount of important context it conveys.

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 feedback tool with no output schema, the description is exceptionally complete. It covers what to report, when, when not to, how to write the message, how to track a report via claim_token, rate limits, and the fact that it's free. The sibling list includes other feedback-adjacent tools (linear_create_issue), but the description preemptively resolves ambiguity about which server's tools are eligible.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and a concrete usage example for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which enriches the schema's terse 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 opens with a specific verb-plus-resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates this from siblings like ask_pipeworx (asking questions) and linear_create_issue (creating a tracked issue), by emphasizing it is exclusively for feedback about Pipeworx tools.

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

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

The description explicitly states when to use the tool: '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 provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This gives both positive and negative guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by revealing data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). No contradiction.

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

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

Three sentences: main purpose, use cases, technical details. Front-loaded, no fluff, every sentence 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?

For a simple 1-param tool with no output schema, the description covers purpose, usage, behavioral traits, and parameter semantics 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 semantic guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond enum labels.

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 ('returns') and resource ('top tools, top packs, and total call volume') with time windows. It distinguishes itself from sibling tools like 'discover_tools' by focusing on trending data rather than general discovery.

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, and the description contrasts short vs. long windows. No when-not-to-use or alternatives provided, but context is strong.

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 the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details internal logic: monotonicity checks, partition sum verification (>3pp triggers signal), semantic anchor (Jaccard >=0.30), placeholder filtering, and fill check against CLOB depth. This provides deep behavioral transparency without contradicting 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 quite long but well-structured: it opens with a clear purpose statement, then breaks into modes, followed by technical details and response format. Every sentence adds value, and the structure (bullets, modes, technical details) aids comprehension. Slightly verbose, but justified by the tool's complexity.

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 completely documents the response format (opportunities[] with fields, partition_check structure, fill check results). It also covers error handling (skipped_low_similarity, placeholders_filtered) and references related tools. Given the tool's complexity, the description covers all necessary context for an agent to use 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?

Both parameters (event and topic) have detailed descriptions in the schema, and the tool description adds significant extra context: event accepts slugs or URLs, topic accepts seed questions, and explains how each mode changes behavior. With 100% schema coverage and additional enrichment, the description fully clarifies parameter semantics.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, making it easy to understand what the tool does and how it differs from sibling tools like polymarket_edges or 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 explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also includes fill-check instructions and recommends polymarket_fill_risk for custom sizing, effectively helping the agent decide the appropriate invocation 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?

Description extensively details behavioral traits beyond annotations: three model families, edge computation formulas (e.g., lognormal barrier from FRED, GDELT article-volume ratio, partition_overround with sport-specific α), slippage handling, tradeable-edge knobs, response structure with diagnostics, and caching. No contradiction with readOnlyHint/idempotentHint 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?

Description is long but well-structured: front-loaded core purpose, then segment details, response structure, knobs, and caching. Every sentence adds necessary information for this complex tool. A minor reduction due to overall length, but it earns its space.

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 9 parameters, no output schema, and complex internal logic, the description is remarkably complete. It covers all response segments including diagnostics, caching, tradeable-edge knobs, model formulas, and caller-facing behavior to handle empty segments.

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, baseline 3. Description adds significant value by explaining how parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly interact with the model logic and response segments, and by describing the response structure that parameters control (e.g., category_filter).

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 explicitly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly defines the verb (scan/return), resource (Polymarket markets with Pipeworx data), and differentiates from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on disagreement-based 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?

Description includes 'Built for 'what should I bet on today'' and explains the three segments, providing clear context for when to use. However, it does not explicitly state when NOT to use or directly compare to siblings, though the specificity implies appropriate use cases.

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

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

The description provides extensive behavioral details beyond annotations: data source (daily snapshots), limits (60-day TTL, gaps explained), decay computation method, and full response structure. This enriches the agent's understanding beyond the readOnly and idempotent hints.

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 fairly long but well-structured, starting with purpose, then parameters, then response format, then limitations. It packs useful information without being overly verbose. Minor improvement possible by trimming redundant phrasing.

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

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

Given the tool's complexity (2 optional parameters, no output schema), the description covers all aspects: input usage, response structure with fields explained, and limitations. No gaps identified.

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 some extra context (e.g., default lookback of 14 days, snapshots written on cache-miss) but does not significantly alter parameter semantics. The schema already provides adequate details.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking 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 explains usage context (fresh vs. old edges, time-series analysis) and implicitly guides when to use this tool over siblings. It does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds details: walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage, and warns about partial fills and unhedged directional risk. 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 lengthy but well-organized with clear sections for single-market and basket modes. It front-loads the core purpose and uses formatting (bold, caps) to highlight key usage instructions. Minor verbosity keeps it from a perfect score.

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 thoroughly lists return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict; theoretical_sum, capture_ratio, thin_legs, forced_directional_risk). It covers behavioral outcomes and edge cases, making the tool's behavior fully understandable.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains single-market vs basket mode, defaults for side and size_usd, and how size_usd is interpreted differently for buys vs sells and for baskets. This aids correct 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 states the tool does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage by specifying this check should be performed before acting on arb signals.

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 instructs to use before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. Explains why: theoretical overround on thin books is not capturable, and partial basket fills convert arb into unhedged directional 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?

The description details the tool's behavior beyond annotations: it explains the two modes, the response structure (leg-by-leg prices, spread array, top_spreads_pp), and the safety fields (compatibility_warning scenarios, temporal_alignment, skipped counters). It also notes that the tool auto-fetches matching events for topics. No contradictions with annotations (readOnlyHint, openWorldHint, etc.).

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

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

The description is detailed and well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). While it is relatively long, every sentence adds value and no information is redundant. The structure aids quick comprehension, though it could be slightly more compact without losing clarity.

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

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

Despite lacking an output schema, the description fully explains the response structure and edge cases, including compatibility_warning conditions, temporal alignment, and skipped cross-type/subtype counters. It addresses what the agent needs to interpret results correctly, making it complete for this tool's complexity.

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

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

Schema coverage is 100%, and the description adds contextual meaning: it lists the exact topic values and provides examples for explicit tickers. It explains the override logic and the relationship between parameters. The description enhances understanding beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the function (comparing prices across venues) and distinguishes it from siblings by focusing on cross-venue spreads. The two modes (topic shortcuts and explicit tickers) further clarify its scope.

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

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

The description provides explicit guidance on when to use each mode: use `topic` for pre-mapped macros, or explicit tickers for custom pairings. It also warns that most pre-mapped topics return compatibility warnings and are not tradeable, helping the agent avoid misuse. The safety fields (compatibility_warning, temporal_alignment) give clear conditions for when spreads are meaningful.

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, destructiveHint=false, idempotentHint=true. Description adds valuable context: scoped to identifier, relationship with remember/forget, and that omitting key lists all. 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, each serving a purpose: first states action, second explains use case, third scopes and pairs. No wasted words, front-loaded with key verbs.

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 1 optional parameter and no output schema, the description covers behavior (retrieve/list), scoping, use case, and pairing with sibling tools. Complete and self-contained.

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

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

Only one parameter (key) with 100% schema description coverage. Description adds meaning beyond schema: 'omit to list all keys' clarifies the optional behavior.

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 ('retrieve', 'list') and resource ('value saved via remember', 'all saved keys'). It distinguishes from siblings 'remember' and 'forget' by specifying the lookup function.

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

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

Explicitly says when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' Mentions scoping and pairing with remember/forget. 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?

Adds value beyond annotations by explaining the mark_read behavior (flagging events read so future calls return only newer ones) and listing key fields in the response. Annotations already cover read/idempotent hints.

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

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

Concise, front-loaded with the main purpose, each sentence adds value without verbosity. Well-structured.

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

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

Despite no output schema, the description adequately describes return content (source, citation_uri, payload), mentions polling suitability, and provides an alternative endpoint. Complete for effective use.

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

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

With 100% schema coverage, the description still adds meaning: explains type and since filter, clarifies limit range (1-200, default 50), and distinguishes mark_read from unread_only. Significantly enriches parameter understanding.

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

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

Description clearly states 'Pull fired events from your subscription feed', a specific verb+resource. It distinguishes itself from sibling tools like list_subscriptions and subscribe by focusing on reading events.

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?

Mentions 'Polls work fine; the same feed is also at ... for scripts and dashboards', providing context for when to use this tool and an alternative. Could be stronger with explicit 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?

Beyond annotations (readOnly, idempotent, etc.), the description explains multi-source fan-out (SEC, GDELT/GNews, USPTO), fallback behavior (GDELT→GNews), and soft-fail for USPTO. 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, well-structured paragraph front-loaded with user-intent examples. Every sentence adds meaningful detail without redundancy. Approximately 100 words, 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?

Despite no output schema, the description specifies return format (structured changes[] grouped by source, total_changes count, citation URIs). It addresses error handling (soft-fail) and provides context on data sources. Complete for a tool of this 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 covers all parameters with descriptions (100% coverage). The description adds practical examples for 'since' (e.g., '7d', '30d') and clarifies 'value' accepts ticker or CIK. This improves usability beyond 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 provides a change feed for a company over a time window, with examples of queries. It distinguishes from entity_profile by explicitly contrasting static profiles vs. change feeds.

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 guidelines on when to use this tool (dynamic change feed) vs. entity_profile (static profile), and specifies input formats for 'since'. However, it doesn't exhaustively list all alternative tools or cases when not to use.

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

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

Annotations already indicate mutation and idempotency; description adds value by explaining scope (per-agent) and persistence duration (24h vs permanent). 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?

Concise, well-structured: purpose first, then usage guidance, 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?

For a simple key-value tool with two parameters and no output schema, the description covers purpose, usage, behavior, retention, and pairing. Fully adequate for its 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 coverage is 100%, so baseline is 3. Description adds examples of key values ('subject_property', 'target_ticker') which aids understanding but doesn't go beyond schema details.

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

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

The description clearly states the tool saves data for later reuse, using a specific verb-resource pair. It distinguishes from siblings by mentioning pairing with 'recall' and 'forget', establishing its unique role.

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 discovering something worth carrying forward, with concrete examples. Though it doesn't state when not to use, it provides clear context and alternatives via sibling tools 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 establish read-only/idempotent behavior, but the description adds valuable behavioral context: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), explicit handling of unresolved identifiers, source labeling, and cascading internal lookups. This substantially exceeds what annotations provide.

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 front-loaded purpose and clearly labeled SUPPORTED TYPES. The opening string of example queries is somewhat extensive, but each section earns its place and there is no filler.

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?

Since there is no output schema, the description compensates by thoroughly explaining return categories, degradation behavior, and input/output mapping for both supported types. It provides enough detail for an agent to select and invoke the tool 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 schema provides basic type/value definitions, but the description greatly enriches parameter semantics. For 'company' it lists the identifiers returned (CIK, ticker, LEI, FIGI) and acceptable inputs; for 'drug' it specifies RxCUI, ingredient, brand, and citation. It also clarifies how unresolved identifiers are reported, adding meaning well beyond the schema.

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

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

The description explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and provides multiple concrete example queries. It clearly distinguishes from sibling tools by positioning this as the 'FIRST' step for name-to-ID lookup, unlike profile/compare tools.

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

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

The description gives a clear directive: 'Use FIRST whenever you have a name but need an ID.' It also explains the supported entity types and acceptable input formats for each. However, it doesn't explicitly state when not to use the tool or name alternatives, so it lacks explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds that it calls ai_visibility_check per entity, ranks results, and returns score, confidence, signal density. 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: first defines the action, second adds context and output details. Front-loaded, no fluff, every sentence 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?

Despite no output schema, the description clearly describes the return format (ranked list with score, confidence, signal density per entity). It also notes the entity count limit (2-8). Sufficient for safe 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 coverage is 100% with parameter descriptions. The description adds value by explaining the roles of the entities array (first as subject, rest as competitors) and that models default to 'workers-ai' if omitted.

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 an internal probe. It distinguishes itself from the sibling 'ai_visibility_check' by being a multi-entity, ranking version.

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example question. It implicitly guides when to use this over single-entity checks, but does not explicitly state when not to use it or list alternatives.

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

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

Description adds valuable behavioral context beyond annotations: composite nature, partial graceful degradation with 5-30s measurement delay for bundlephobia, and sources_failed field. Annotations already indicate read-only, idempotent, non-destructive.

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 informative and well-structured, starting with purpose, then usage, then behavioral notes. It is slightly verbose but each sentence adds value. No unnecessary fluff.

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

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

Given no output schema, the description fully explains the return structure (summary block fields, per-advisory detail, links, alternative versions) and covers edge cases like partial failures and timing. Complete for an agent to understand tool behavior.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds the default behavior for version (latest when omitted) and acceptance of scoped packages. Very good but not perfect because it could specify that version is optional.

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 a composite check for npm packages covering deps.dev and bundlephobia. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes itself from sibling tools by focusing on npm ecosystem.

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: for questions about safety/popularity/size of npm packages. Also specifies limitations (NPM only, alternative for other ecosystems via deps.dev) providing clear 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 indicate read-only, idempotent, non-destructive behavior. The description adds significant technical detail: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation and flagging, and character offsets for verification. No contradictions.

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

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

The description is concise and front-loaded. Every sentence adds value: purpose, use case, paired tool, technical details. No unnecessary words.

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

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

Despite no output schema, the description explains return format (passages with offsets and scores). It covers limits, technical model, and use cases. For a complex semantic search tool, this is highly 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% with good descriptions, so baseline is 3. The description adds context (e.g., 'text you already pulled') but does not provide new syntactic or semantic information beyond what the schema already conveys.

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 does semantic search inside a fetched record, with specific examples (SEC 10-K, article) and outputs (passages with offsets and scores). It distinguishes itself from sibling tools by explicitly pairing with ask_pipeworx_grounded and contrasting with full-document search.

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: when the record is too large for the prompt. It also explains pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use or list alternative tools beyond the one sister tool.

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

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

Annotations already indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds critical details: returns new subscription ID, requires OAuth, details on delivery channels with constraints (phone verification, 10/day SMS cap, webhook auto-disable after 10 failures), and type-specific params. 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 dense paragraph that efficiently conveys essential information. It starts with purpose, then prerequisites, then types with examples, then delivery channels. While effective, slightly more structure (e.g., bullet points) could improve readability without adding length.

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 three parameters (one required), the description covers all aspects: purpose, return value (subscription ID), prerequisites, type-specific filters, and delivery options. It adequately compensates for the lack of output schema by explaining what the tool returns and side effects.

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%, providing baseline 3. The description significantly enhances understanding by explaining the purpose of each type and offering concrete examples (e.g., sec_8k items param, fred_series series_id). It also clarifies constraints on delivery fields (phone verification, 10/day cap), exceeding the schema's description.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It lists specific supported types (e.g., sec_8k, polymarket_edge), which distinguishes it from sibling tools like list_subscriptions or 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?

The description explicitly requires a Pipeworx OAuth account, noting that anonymous/BYO cannot persist subscriptions. It also provides context for when to use this tool (creating subscriptions) and implicitly contrasts with list_subscriptions and recent_alerts. However, it does not explicitly 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?

Annotations already convey read-only, idempotent, and non-destructive nature. The description adds value by detailing the output format (category-bucketed example questions with tool/argument shapes) and behavior variation with/without the 'topic' parameter. 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 front-loaded with user-facing prompts, followed by the tool's purpose and output details. It is somewhat long but well-structured and each sentence adds value. Minor redundancy in listing categories could be trimmed, but overall 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?

Given the rich annotations, full schema documentation, and no output schema, the description covers all necessary context: purpose, usage guidance, parameter behavior, and output nature. It explains what the tool returns and how to tailor it, making it complete for an onboarding 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?

Input schema covers the single optional parameter with 100% description. The description enriches this by providing concrete examples of topic values and explaining that omitting it yields a full cross-category spread, adding clarity 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 identifies the tool as an onboarding entry point for agents new to Pipeworx, listing trigger phrases like 'What can I ask Pipeworx?' and specifying it returns category-bucketed example questions. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by focusing on orientation and discovery of what the system can do.

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

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

The description explicitly states when to use it ('first when you do not yet know what Pipeworx can do') and how to use optional parameters to focus on a topic. It also references learning meta-tools. It lacks explicit 'when not to use' guidance, but the context is clear and practical.

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 provide destructiveHint=false and readOnlyHint=false, but the description adds critical behavioral details: ownership enforcement, deactivation (not deletion), and that historical events remain available via recent_alerts. 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?

Two concise sentences front-load the core action and immediately address important constraints (ownership, deactivation). No unnecessary words; every sentence adds value.

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

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

Given the simple tool (1 param, no output schema), the description covers all necessary context: action, ownership, data lifecycle impact, and relationship to recent_alerts. It is complete for effective use.

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

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

With 100% schema coverage, the description adds little beyond 'by id' which mirrors the schema. The schema already explains the parameter sufficiently, so the description does not add new meaning. 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 clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like subscribe (opposite action) and list_subscriptions (listing active ones), and mentions the effect on historical events via recent_alerts, which sets it apart.

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 tells when to use (to cancel a subscription) and implicitly when not to use (if you want permanent deletion, but it's deactivated). It lacks explicit exclusions or alternatives, but ownership enforcement ('only your own subscriptions') provides clear context.

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

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

The description adds substantial behavioral context beyond the annotations: the two execution paths, the full set of possible verdicts, and the critical caveat that could_not_verify means the check did not happen and must not be treated as evidence for or against the claim. It also explains the meaning of unsupported. This goes well beyond the readOnlyHint/openWorldHint 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 long but information-dense. It is well-structured, starting with trigger phrases, then use cases, then routing, then return values, and then error semantics. Every sentence contributes useful details, though it could be tightened slightly without losing critical caveats.

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 covers the return values (verdicts, actual value with citation, reasoning) and distinguishes the two failure cases (could_not_verify vs unsupported). Combined with the annotations, this gives an agent everything it needs to select, invoke, and interpret the tool's results 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 schema covers both parameters, but the description enriches the semantics: claim gets natural-language examples, and tolerance_pct is explained as overriding the implied tolerance and being useful for hallucination detection. This provides meaningful guidance on how to set and interpret the parameter beyond the schema's basic 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 identifies the tool as natural-language claim verification against authoritative sources, with explicit examples of trigger phrases like 'fact check' and 'verify the claim that'. It also distinguishes itself from sibling research tools by focusing on returning verdicts like confirmed/refuted, and by noting it replaces 4–6 sequential calls.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides detailed routing guidance (SEC EDGAR for company-financial claims, grounded pipeline for any other factual claim). However, it does not name alternative tools or explicitly state when not to use it, so it stops short of a full when/when-not/alternatives breakdown.

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