Court Listener

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the return structure ('per-model {score, confidence, signals, raw_response} + a combined view') and the BYO key model for Anthropic. No contradictions.

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

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

The description is well-structured with a clear first sentence stating purpose, followed by details. It is slightly lengthy (5 sentences) but each sentence adds value. Could be trimmed slightly for conciseness.

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

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

Given the parameter count (4) and no output schema, the description adequately covers return structure and usage. It explains what the tool returns and when to use it. Complete enough for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the default model for the 'models' parameter, clarifying that '_apiKey' is passed to Anthropic directly, and that 'context' disambiguates common names. This goes beyond the schema descriptions.

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

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

The description clearly states the tool 'probes one or more LLMs for what they know about a business / brand / product / topic and scores visibility (0-100) per model.' It distinguishes itself from sibling tools by its specific function of AI visibility scoring, rather than general Q&A or entity resolution.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also notes the default model and optional API key for Anthropic. However, it does not explicitly state when not to use this tool or provide direct alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context: it routes to the right tool, fills arguments itself, returns stable citations, and makes one fast call. It does not mention rate limits or failure handling, but the coverage is solid.

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 information-dense, with every sentence contributing to purpose, usage, or alternatives. It is front-loaded with the key instruction and includes practical examples. A slightly tighter structure could earn a 5, but the level of detail is justified.

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 a simple schema, no output schema, and rich annotations, the description goes beyond minimum requirements. It explains what the tool does, when to use it, which alternatives exist, and what kind of output to expect (structured answers with citation URIs). It is complete for the tool's complexity.

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

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

The input schema covers all 6 parameters with descriptions, including aliases and the main 'question' parameter. Schema coverage is 100%, so the description does not need to add parameter details and is not penalized for omitting them. Baseline 3 applies.

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

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

The description explicitly states the tool routes questions to one of 5,462 tools across verified sources and returns structured answers with citation URIs. It clearly distinguishes itself from web search and ask_pipeworx_grounded by referencing its default routing behavior and specific use cases.

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 extensive when-to-use guidance, including a strong preference over web search, concrete trigger phrases ('what is', 'look up', 'get the latest'), and explicit alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also covers edge cases like breaking news.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context about the beta nature, live candidate routing experiments, the current inactive state, and that it is a fully working router rather than a fallback or stub. 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 efficiently structured, front-loading the core identification ('Beta version of ask_pipeworx') and then providing necessary details about current state and usage. Each sentence adds meaningful context, though the date and detailed comparison explanation could be trimmed slightly.

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 role as a beta variant of a universal router, the description covers what it does, how it differs, its current operational state, and how to use it. It also clarifies the response shape ('same response shape') and that it is a full router, making it complete for an agent to 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%, with all six parameters documented as aliases for 'question'. The description does not add parameter-specific semantics, but the schema fully covers the meaning and aliases. The 'same arguments' reference also points to the stable tool's interface, which is sufficient.

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 this as the beta version of ask_pipeworx, a universal router with the same 5,462 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by emphasizing its experimental role and current identity with the stable 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 explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also frames the alternative implicitly by comparison with the stable router and notes that results are compared to decide merges, giving clear context for choosing this variant.

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 read-only/idempotent annotations, the description discloses the refusal behavior with specific refusal_reason values, the return structure including evidence and confidence, the constraint that answers come only from tool results, and the cost of one extra LLM call. This provides substantial behavioral context beyond what annotations offer.

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 longer than ideal but is densely packed with valuable information. It front-loads the core purpose, then details the return format and refusal reasons, and ends with usage guidance. Every sentence contributes meaning, though the structured return examples could be trimmed for brevity without losing essential content.

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

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

For a tool of this complexity, the description covers all necessary aspects: purpose, usage vs alternatives, behavior (including refusal cases), return format, and cost. Without an output schema, the description fully explains the response structure. The lack of a concrete example is not a gap given the thorough textual explanation.

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%—all parameters are aliases for 'question' and are documented in the schema. The description does not add parameter-specific details beyond what the schema already states, so a baseline score of 3 is appropriate. No missing parameter information.

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: a hallucination-resistant answer mode for high-stakes reads. It specifies the mechanism (same routing as ask_pipeworx, then extracts answers only from tool results) and distinguishes it from the sibling ask_pipeworx by emphasizing the extraction behavior and extra LLM call cost.

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 is provided: use when answers will be quoted, cited, or acted on and when the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements). It also explicitly states 'prefer ask_pipeworx for casual lookups,' naming the alternative and providing a clear decision rule.

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. Description adds extensive behavioral detail: low-confidence resolution handling, closed market handling, wide spread warnings, cancellation rules, parent event extraction, and fan-out patterns. Goes far 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?

Description is lengthy and dense, covering many details. While every sentence adds value, it lacks clear section headings and is verbose. Could be more concise without losing information.

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

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

No output schema exists, but description thoroughly explains response structure (result.market, result.analysis, result.evidence, resolver contract, parent event, news fields, safety mechanisms). Covers all aspects needed for an agent to use 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?

Schema has 100% coverage with descriptions for all 3 parameters. Description adds examples and additional context (e.g., when to set include_raw to true for recomputing deltas). Provides value beyond schema.

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

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

Description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). Differentiates from siblings like polymarket_edges by focusing on data gathering and analysis.

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

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

Explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides examples per category. However, does not explicitly exclude scenarios or compare with sibling tools like polymarket_arbitrage or validate_claim.

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 extensive behavioral context beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of fiscal years, sorting by primary metric, and return of citation URIs. It aligns with readOnlyHint and other annotations. No contradictions.

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

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

The description is a single paragraph with front-loaded example queries and preference guidance. Every sentence contributes meaning: usage examples, data sources, sorting, return format, and efficiency claim. 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?

For a tool with 2 simple parameters, no output schema, and good annotations, the description covers all essential aspects: purpose, when to use, data sources, sorting, return format, and max entity count. It fully compensates for the lack of output schema.

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

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

Schema coverage is 100% with descriptions. The description adds valuable context: for the 'type' parameter, it explains what data is pulled per type; for 'values', it provides concrete examples (e.g., ['AAPL','MSFT'] and ['ozempic','mounjaro']). This goes beyond the schema's minimal 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 performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes from sequential single-pack lookups (likely done by tools like entity_profile) and explicitly says to prefer this tool when comparing entities.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides example queries that trigger the tool. While it doesn't mention specific alternatives by name, the guidance is clear.

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

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

Annotations already declare read-only/idempotent/non-destructive; description adds account/auth requirements, paid tier for thorough, decomposition into facets, parallel routing, gap reporting with 'never invented', depth-specific behavior, citation_fetchability, contradiction scans, semantic excerpting, and latency expectations. This goes far beyond annotation basics and gives the agent a realistic model of call outcomes.

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 wall of text but every sentence carries operational information—accounting, fallback, use cases, data source scope, output packet, depth semantics, citation rules, and latency. It is front-loaded with the most critical gate (account required) but could be broken into bullets for scanability; length is justified but borderline.

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

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

Given a complex tool with no output schema, the description fully specifies inputs, expected outputs (findings packet with evidence/confidence/source/fetched_at/citation/gaps), failure modes (gaps for uncovered topics), depth behaviors, and timing (15-90s). It leaves no significant ambiguity about what the agent should expect from a call.

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

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

Schema description coverage is 100% for both params, so the base is 3; the description adds value by giving example questions ('compare X and Y's regulatory + financial exposure') and clarifying that depth levels map to facet counts and hop behavior, reinforcing the schema's enum descriptions with concrete expected outcomes.

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?

States 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in one call, explicitly contrasting with open-web search. It also differentiates from ask_pipeworx for single lookups and breaking news, making the purpose unmistakable.

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

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

Explicitly instructs when to use: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also provides account-tier fallback: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds positive value by explaining that results include names, descriptions, full schemas with curated examples, and that each result is ready to call directly. This goes beyond what annotations provide, enhancing transparency about the output and readiness to use.

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

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

The description is front-loaded with the core purpose ('Find tools by describing the data or task') and is structured into clear functional parts: use case, return format, and placement advice. While slightly long (5 sentences), every sentence serves a purpose and there is no redundancy.

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

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

Given that there is no output schema, the description adequately explains what is returned: top-N tools with names, descriptions, full input schemas, and curated examples. It also notes that results are ready to call, which is crucial for a discovery tool. The description fully covers the context needed for an agent to understand the tool's output.

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

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

All 6 parameters are documented in the input schema (100% coverage), so the description's role is minimal. The description mentions the 'query' concept but does not add new meaning beyond the schema. Baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool finds tools by describing data or task, listing many data sources and indicating it returns top-N tools with full schemas. It also calls itself a discovery tool to be used first, distinguishing it from sibling tools that perform specific tasks.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for:' and advises to 'Call this FIRST when you have many tools available'. While it provides clear when-to-use context, it lacks explicit when-not-to-use guidance, but the use case is sufficiently narrowed.

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, destructiveHint=false. Description adds value by detailing the parallel call behavior, data sources (SEC, XBRL, USPTO, news, GLEIF), and specific constraints like patents sunsetting soon. This provides behavioral context beyond what annotations offer.

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 every sentence adds value: example queries, what it returns, limitations, and cross-source details. It is front-loaded with examples and then explains functionality. Could be slightly more concise but effectively communicates all 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?

No output schema, so the description must explain return values. It thoroughly lists what is returned: cik, company_name, recent_filings with URIs, fundamentals with specific fields and sorting, patents status, news source, and LEI. It also notes limitations like the USPTO sunset. This is complete for a tool with two simple parameters.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds context that 'value' can be ticker or zero-padded CIK, and reiterates that names are not supported (already in schema). This provides practical guidance on valid inputs, justifying a score of 4.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' with examples like 'brief me on Tesla' and specifies returns (CIK, filings, fundamentals, etc.). It distinguishes from siblings like 'compare_entities' and 'resolve_entity' by noting it should be preferred over chaining and that names require using resolve_entity first.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Provides when-to-use and when-not-to-use: names not supported, use resolve_entity first. This gives clear guidance relative to alternatives.

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

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

Annotations already declare the tool safe (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). The description adds valuable context beyond annotations: no API key, no rate limit, coverage of 8.3 million opinions across 3,361 courts, and ordering by citation count. This enriches the agent's understanding of scale and result ranking.

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 earning its place: purpose+return fields, scope+limitations, and when-to-use/alternative. No redundancy or filler. Front-loaded with the verb and resource, making it instantly scannable.

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 two-parameter tool with no output schema, the description provides sufficient context: what it returns, how results are ranked, scope of coverage, and usage boundary. The agent can invoke and interpret results without further clarification. No gaps that would cause mis-invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the purpose of the 'name' parameter (BY NAME) and mentions the ordering behavior, but does not add new parameter-level details beyond the schema. It neither hurts nor substantially improves schema 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 states a specific verb ('Find') and resource ('US court case BY NAME'), and clearly lists the returned attributes (citations, filing date, judges, citation count). It distinguishes itself from search_opinions by emphasizing name-based lookup versus topic-based 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?

Explicitly states when to use this tool ('when you know what the case is CALLED') and directs users to an alternative ('use search_opinions when you only know the TOPIC'). This is clear guidance with a named sibling alternative.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds usage context but no additional behavioral traits beyond what annotations convey.

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 purpose and usage, 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?

A simple one-parameter delete operation with no output schema; description fully covers purpose and usage.

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

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

Schema coverage is 100% with description per parameter. Description adds no further meaning beyond the schema's 'Memory key to delete'.

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 'Delete a previously stored memory by key' – specific verb and resource, distinct from siblings like remember and recall.

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

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

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

The description discloses the process: fetches the page, extracts title/description/key links, and emits standard markdown format. It aligns with annotations (readOnlyHint, idempotentHint, openWorldHint). No contradictions, but could add details on error handling or page size limits.

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

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

The description is very concise: four sentences covering purpose, process, output, and use cases. Front-loaded with the main action. No unnecessary words or repetition.

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

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

Given no output schema, the description adequately explains the return value as 'a single text blob' in standard llms.txt format. It mentions where to place the output. Could be more complete with a note on limitations (e.g., JavaScript-rendered pages) but is sufficient for most use cases.

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

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

Input schema has 100% description coverage, so baseline is 3. The description doesn't add extra meaning beyond the schema's parameter descriptions. It does not clarify URL format expectations or the effect of max_links beyond defaults.

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

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

The description clearly states it generates an llms.txt file for any URL, with specific verb+resource ('Generate llms.txt') and explains the output format and purpose. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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 lists three concrete use cases: getting a client's site indexed, drafting for your own project, or auditing competitor AI view. It does not explicitly mention when not to use or contrast with sibling tools, but the provided scenarios give clear context for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations, such as the exact return fields and the pdf_available false edge case when RECAP lacks the document itself. This exceeds baseline transparency.

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

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

The description is two sentences that efficiently lead with the core purpose, then list outputs, then provide usage context and an edge case. Every clause adds value with no redundancy.

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

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

For a single-parameter read tool with strong annotations, the description fully covers what the tool does, what it returns, when to use it, and a key edge case. No output schema exists, so the explicit return list is necessary and sufficient.

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

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

Schema description coverage is 100%; the parameter document_id is fully described in the schema as the RECAP document id from list_docket_filings or search_court_filings. The tool description repeats this without adding new semantic details, so no bonus is warranted.

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 gets one filing from a US federal court docket by document id, and enumerates the specific fields returned (entry description, date, page count, docket_id, text excerpt, PDF link). This distinguishes it from sibling tools like list_docket_filings and search_court_filings by emphasizing the singular, specific-document retrieval.

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 instructs to use this tool after list_docket_filings or search_court_filings to read a specific document, providing clear context for when it's appropriate. However, it does not mention exclusions or when NOT to use it, which would earn a 5.

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

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

Despite strong annotations (readOnly, openWorld, idempotent), the description adds meaningful behavior: coverage statistics (8.3M/71%), no API key needed, return fields, OCR provenance, data as-of date, and fall-through to live search. This goes well beyond the annotations and adds valuable context about data freshness and edge cases.

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 compact, front-loaded with the primary purpose, and every sentence adds useful context: what it returns, coverage, auth requirements, and data freshness. No filler or 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 single-parameter tool with a rich output schema and comprehensive annotations, the description covers the essential operational context: input origin, coverage, return fields, and fallback behavior. No critical gaps are evident.

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

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

The schema already describes the id parameter as a numeric CourtListener opinion ID (100% coverage). The description enhances this by specifying that the id is the one 'returned by search_opinions', providing provenance and disambiguating from other possible IDs. This adds meaning beyond the schema.

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

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

The description states a specific action ('Get the FULL TEXT of a US court opinion') and identifies the required resource (CourtListener opinion ID). It also distinguishes itself from sibling tools by referencing search_opinions and clarifying that it returns full text rather than search results or case lists.

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?

Clear context: the tool is used when you already have an opinion ID from search_opinions. It implies the workflow ('the opinion_id returned by search_opinions') but does not explicitly state when not to use it or mention alternative tools like lookup_citation or find_case. Thus, it provides clear context without 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 readOnlyHint and idempotentHint, but the description adds operational details beyond annotations: 'No API key, no rate limit' and the fact that it returns opinion_id for use with get_opinion. These add practical context that annotations do not cover.

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

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

Two sentences front-load the main purpose and then add workflow and operational details. Every clause earns its place with no redundancy or 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?

For a simple one-parameter tool with no output schema, the description sufficiently explains inputs, outputs, and workflow. It mentions all opinion types and the follow-up action, making the tool self-contained for an agent.

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

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

Schema coverage is 100% and the schema already describes cluster_id as coming from find_case or lookup_citation. The description does not add new parameter-level meaning beyond the workflow context, so 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 the tool lists every opinion in a case cluster, including majority, concurrences, and dissents. It also explains the return value provides opinion_id for get_opinion, distinguishing it from sibling tools like get_opinion and find_case.

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 the user to use this after find_case or lookup_citation and before get_opinion, providing a clear workflow and named alternatives. This guides the agent on when to select this tool versus others.

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 adds valuable behavioral context: it explains that RECAP holds docket text for more filings than it holds documents, so a missing PDF does not mean a missing record, and that each filing includes a pdf_available flag. This clarifies data semantics not evident from annotations alone.

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 yet reasonably concise for the information it conveys. It is front-loaded with the core purpose, followed by output fields, data caveats, and a clarification about opinions. The sentence 'This is the docket sheet: what was filed, when, and by which entry number' is somewhat redundant with the opening, but the overall structure is logical and 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it lists the fields, explains pdf_available semantics, and notes ordering. It also provides a clear source for the input parameter (search_dockets) and distinguishes from related content. The tool's complexity is modest, but the description covers all essential context for correct use.

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

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

The schema already documents both parameters (docket_id and limit) with clear descriptions, so the baseline is 3. The description reinforces that docket_id comes from search_dockets, but this is also in the schema. It does not add new syntax or formatting details beyond what the schema provides, but it does contextualize the docket_id's role.

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 a specific action ('List the filings on a US FEDERAL district or bankruptcy court docket') and names the key resources and output fields (document id, entry number, filing date, page count, PDF link). It explicitly distinguishes this from court opinions, which 'live in search_case_law / get_opinion', and notes the docket_id source, clearly separating it from sibling 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 clear context for when to use this tool (to see the docket sheet) and explicitly excludes court opinions, directing to sibling tools. It also states the prerequisite of obtaining docket_id from search_dockets. However, it does not explicitly mention when to use get_docket_filing (for a single filing) versus this list, though that is implied by the word 'list'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns specific fields and includes a parameter for inactive subscriptions, providing useful behavioral context beyond annotations.

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

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

Two sentences, no waste, front-loaded with purpose and additional usage guidance.

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

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

Given the simple nature of the tool, the description fully covers purpose, usage, return fields, and parameter behavior. No output schema needed.

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 mentions 'include_inactive' but doesn't add meaning beyond the schema's existing 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 'List the caller's active subscriptions' and lists specific return fields. It 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?

Provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies not to use when you need to subscribe or unsubscribe, but doesn't explicitly state 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful behavioral context beyond annotations: no API key, no rate limit, and the specific fields returned (name, filing date, judges, citation count). This provides clarity on what the agent can expect.

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

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

Two sentences, front-loaded with the core function, and every phrase earns its place (scope, output, usage trigger, access details). No filler or redundancy.

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

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

Given the simplicity (one parameter, no output schema) and strong annotations, the description covers the essential use case, expected output, and access constraints. It is complete for a straightforward lookup tool.

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

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

Schema description covers the single citation parameter fully with a format and example, so baseline is 3. The description adds the 'US' qualifier and another example, clarifying the exact scope and format of citations. This improves semantic precision 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 opens with a specific action—'Resolve a US reporter citation'—and clearly identifies the resource (reporter citations) and output (case name, filing date, judges, citation count). This distinguishes it from sibling tools like find_case or search_opinions, which handle broader search tasks.

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

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

The description explicitly states when to use the tool: 'Use when a brief, opinion or article cites a case by reporter and you need to know which case that is.' It also adds operational context ('No API key, no rate limit'). However, it does not explicitly mention alternatives or when-not-to-use, so it misses the highest bar.

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 no safety hints (readOnly=false, destructive=false, etc.), so the description carries the full burden. It discloses rate limiting ('5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), and the asynchronous nature of feedback ('The team reads digests daily'). These are meaningful behavioral traits beyond what annotations convey.

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 serves a distinct purpose: purpose, use cases, exclusions, message content guidance, team response behavior, and rate limits. It is front-loaded with the core action and efficiently packs nuanced rules without redundancy. The length is 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?

There is no output schema, so the description needn't explain return values. It covers all necessary context for a feedback tool: what to report, what not to report, how to write the message, rate limits, quota impact, and what the team does with it. This is complete for the tool's purpose and 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?

While the schema already describes all 3 parameters at 100% coverage, the description adds substantial value: it elaborates on the 'message' format ('1-2 sentences typical, 2000 chars max'), gives examples of what to include (which tool, what error, what data was missing), and clarifies the 'type' semantics by connecting them to user scenarios (e.g., bug = wrong/stale data). This exceeds the baseline 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 opens with a clear action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and scope (tools served by this Pipeworx connection), distinguishing it from sibling tools like ask_pipeworx or discover_tools. This is a specific verb+resource+scope, not a tautology.

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

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

The description explicitly states when to use the tool (bug, feature/data_gap, praise) and when NOT to use it (issues with tools from other MCP servers), even naming the alternative ('file it with that server instead'). It also instructs how to frame the feedback (in terms of Pipeworx tools/packs, not pasting user prompts). This is textbook 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, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: data source ('CF analytics-engine'), privacy (no PII), and caching ('Cached 5min-1h depending on window'). This goes well beyond the annotations.

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

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

The description is exceptionally concise: two sentences plus a bulleted list, no redundant words. Every sentence serves a purpose—defining output, use cases, and data provenance. Front-loaded with the primary function.

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 what the tool returns (top tools, top packs, total call volume), how data is derived, and caching behavior. For a simple parameterless tool with one optional param, this is fully 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?

With 100% schema description coverage for the single parameter 'window', the schema already provides enum values and a description. The tool description does not add additional parameter semantics beyond the schema, making the baseline score of 3 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 'What other AI agents are calling on Pipeworx right now' and lists specific returns (top tools, top packs, total call volume). Distinguishes itself from sibling tools like discover_tools or ask_pipeworx by focusing on aggregate usage trends rather than individual tool discovery or Q&A.

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

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

Provides three concrete use-case scenarios: discovering hot data sources, confirming canonical tools, and aligning use case with agent demand. While no explicit when-not or alternative tools are named, the scenarios offer clear guidance on when to invoke this tool.

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

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

The description discloses a wealth of behavioral traits beyond annotations: monotonicity checks, partition sum checks, semantic anchor with Jaccard similarity, partition filter for placeholder slugs, fill check against live depth. It explains response structure including opportunities array and partition_check fields. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false are all consistent with a scanning/analytical tool).

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-structured, with information front-loaded (purpose, modes). Every sentence adds value, though some technical details (e.g., Jaccard similarity threshold) could be slightly condensed. Still highly effective for its 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 no output schema, the description fully covers the response structure (opportunities array with fields, partition_check object in event mode) and explains edge cases (placeholder filter, fill check). The tool is complex but the description provides all necessary context for an agent to invoke it correctly and interpret results.

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

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

Schema description coverage is 100% with both parameters described. The description adds significant meaning beyond the schema: it explains exact usage patterns (slug format, example topics), how each mode works, and when to prefer one over the other. This fully compensates for any missing detail in the schema.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no-args trending scan, event mode for a specific market, and topic mode for cross-event scanning. Each mode is explicitly named and scoped.

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 on when to use each parameter: no args for a trending scan, event for a specific market (recommended), topic for cross-event scanning. It explains advantages of cross-event mode and provides examples of when to use each. Also mentions fill check and refers to another tool for custom sizing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds extensive behavioral detail: caching at KV level for 1h, the 24h-move warning, diagnostic funnel counters (filter_skips, category_counts), and specifics about how edge is computed (after slippage, Kelly fractions capped at 0.25). No contradiction with annotations.

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

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

The description is comprehensive yet well-structured: general purpose, three model families, edge details, knobs, and response format. Every sentence adds value. It is front-loaded with the main purpose and uses clear sectioning (by_segment, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). No redundancy.

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

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

Given the tool's complexity (9 parameters, three segments, no output schema), the description is extremely thorough. It explains caching, diagnostic counters, the 24h-move warning, partition-arbitrage filtering, and all knobs. For a read-only, open-world, idempotent tool, this provides all needed context for correct invocation.

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

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

Schema coverage is 100%, so all 9 parameters have descriptions. The description groups some parameters under 'TRADEABLE-EDGE KNOBS' and explains their purpose in the context of edge realizability, which adds value beyond the individual schema descriptions. However, it does not add per-parameter details beyond what the schema already provides.

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

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

The description begins with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly specifies the verb (scan/return), the resource (Polymarket markets with edge), and the three distinct segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). This distinguishes it from siblings like polymarket_arbitrage (cross-platform arb) and polymarket_edge_tracker (historical tracking).

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 states it is 'Built for "what should I bet on today"' and explains the three segments. It also describes tradeable-edge knobs and diagnostic counters for empty segments. However, it does not explicitly compare to siblings or state when not to use this tool versus others like polymarket_arbitrage or polymarket_fill_risk.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds behavioral context: snapshots are written on cache-miss, history depth bounded by 60-day TTL, decay numbers from daily closes not intraday. No contradiction with annotations. The disclosure is thorough beyond the annotations.

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

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

The description is dense but every sentence adds value. It front-loads the core purpose and progressively details parameters, response structure, and limitations. No filler or repetition. Appropriate length for a telemetry tool.

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

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

Despite lacking an output schema, the description fully explains the return structure: tracked[] with full time-series, expired[] with lifespan, and snapshot_dates[]. It also covers caveats (TTL, snapshot gaps, decay calculation) making it self-contained for an agent to understand the tool's 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 coverage is 100% for both parameters. The description adds value by explaining the default values and context: days lookback default 14 (clamped 2-30), window default '1wk' and its link to snapshot family. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. It uses a specific verb-resource combination and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis of edges across snapshots.

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 context for when to use the tool by contrasting a fresh wide edge with a 3-week-old one. While it does not list alternative tools or provide explicit 'when not to use', the usage is clearly implied in the telemetry purpose. The sibling list shows similar tools, but the description sets it apart.

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 annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with the description. The description goes beyond annotations by detailing behavior: walks order book ladder, returns verdicts (clean/degraded/cannot_fill), explains basket mode risks (forced directional risk), and warns about partial fills converting arb to directional position.

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 subheadings for modes, front-loading the purpose. It is somewhat long but every sentence adds value given the tool's complexity. Minor demerit for length, but overall appropriate for the content.

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

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

Despite lacking an output schema, the description thoroughly explains all return values for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, profit_usd, forced_directional_risk). Combined with clear input requirements and annotations, the description provides complete context for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, with all parameters described. The description adds significant meaning beyond schema: explains default behavior for 'side' in basket mode, clarifies 'size_usd' interpretation for single-market vs basket, and emphasizes the exclusivity condition between 'market' and 'event'.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making its unique purpose clear.

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 the requirement for either 'market' or 'event' parameter and explains when to use each mode. It gives specific conditions for use: 'before acting on any polymarket_arbitrage signal or polymarket_edges trade above ~$500', and warns about risks like thin books and partial fills, providing clear when-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 mark it as read-only, open-world, and idempotent. The description adds significant transparency by detailing the spread computation, safety fields, compatibility conditions, and temporal alignment, going well 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 lengthy but well-structured with section headers and clear separation of modes and safety fields. It is appropriately detailed for a complex tool but could be slightly more concise.

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

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

Despite no output schema, the description thoroughly explains the response format including venue prices, top_spreads_pp, safety fields, and edge cases. It provides complete context for the agent to understand and use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes, the topic list, and that explicit parameters override topics, providing semantics beyond the schema.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, with two modes and explicit output details. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on different venue pairs.

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 (topic shortcuts vs. explicit tickers), and includes warnings about compatibility warnings and temporal alignment, helping the agent decide 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, idempotentHint, and destructiveHint. The description adds scoping details (anonymous IP, BYO key hash, or account ID) and the listing behavior when key is omitted, complementing the 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 core action and resource, and contains no filler. 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?

For a simple tool with one optional parameter and no output schema, the description adequately explains behavior (value retrieval or key listing), scoping, and pairing with related tools. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with a description for the 'key' parameter. The description reinforces the dual behavior (retrieve vs. list) and adds context beyond the schema's minimal 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 verb-action ('Retrieve a value' or 'list all saved keys') and the resource ('previously saved via remember'), and distinguishes itself from siblings by referencing paired tools (remember, forget).

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

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

The description explains when to use ('look up context the agent stored earlier... without re-deriving it from scratch') and mentions scoping, but does not explicitly state when not to use or offer alternatives.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds key behaviors: mark_read flags events read so subsequent calls return only newer ones, and the events contain specific fields. This goes beyond what annotations provide, though no mention of rate limits or auth is needed given the 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?

Three well-structured sentences. The first sentence states the core purpose. The second lists payload fields and filtering options. The third explains mark_read and mentions an alternative endpoint. Every sentence earns its place with no fluff.

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

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

Given 5 optional parameters, no output schema, and zero required fields, the description covers behavior, filtering, mutation via mark_read, and an alternative access method. It lacks explicit pagination details or return format, but the listing of key fields (source, citation_uri, payload) provides sufficient completeness.

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

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

All 5 parameters have schema descriptions, so baseline is 3. The description adds specific examples for type ('sec_8k') and explains the effect of mark_read ('flag returned events read so the next call only shows newer ones'). This adds value beyond the bare 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 starts with a clear verb 'Pull' and specifies the resource 'fired events from your subscription feed'. It details what each event carries (source, citation_uri, raw payload). This distinguishes it from sibling tools like list_subscriptions or subscribe, which operate on different resources.

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

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

The description provides explicit usage guidance: filtering by type and since, setting mark_read, and notes that polling works fine. It also offers an alternative endpoint for scripts/dashboards. However, it doesn't explicitly state when not to use this tool versus siblings, though the context implies 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?

Discloses parallel fan-out to multiple sources (SEC, GDELT->GNews fallback, USPTO), failure modes, and return format with citation URIs. Annotations already indicate readOnly/idempotent, and description adds extensive behavioral context without 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?

Single dense paragraph that front-loads purpose with example queries. Includes key details on sources, fallback, and alternative tool. Could be slightly more structured, but it's efficient and well-organized.

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

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

Despite no output schema, description explains return structure (grouped changes, total count, citation URIs) and covers data sources, failure modes, and alternative tool. Comprehensive for a read-only query 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 covers all parameters. Description adds valuable context: explains 'since' accepts ISO date or relative shorthand with examples, 'value' can be ticker or CIK, and 'type' is limited to 'company'. Enhances understanding beyond schema.

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

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

The description clearly states the tool's purpose as a change feed for a company over a recent time window, listing example queries like 'What's new with X' and explicitly distinguishing from the sibling tool 'entity_profile'.

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

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

Provides clear context on when to use (recent changes over a window) and directs to 'entity_profile' for static profiles. Does not explicitly exclude other scenarios, but the distinction 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?

Discloses persistence scoping (authenticated vs anonymous, 24-hour retention) that annotations don't cover. No contradiction with readOnlyHint=false and destructiveHint=false. Could mention idempotency given idempotentHint=true but not required.

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

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

Single paragraph, front-loaded with purpose, every sentence adds value. 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?

Complete for a simple write tool with annotations and sibling context. Covers purpose, usage, persistence, and pairing with recall/forget.

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

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

Schema already has clear descriptions for key and value. Description adds context of key-value pair scoping and examples, providing extra 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?

Clearly states 'Save data the agent will need to reuse later' with concrete examples (ticker, address, preference). Distinguishes from siblings recall and forget.

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

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

Explicitly says when to use (discover something worth carrying forward) and provides examples. Also mentions pairing with recall and forget.

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, so the bar is lower. The description adds useful behavior context: internal cascading lookups, auto-disambiguation, and citation URI return format, all consistent 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?

Though longer than minimal, the description is well-structured with examples and a 'SUPPORTED TYPES' breakdown. Every sentence conveys needed information—no fluff.

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

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

The tool has no output schema, but the description compensates by describing output for each type, including citation URIs and disambiguation behavior. Given the 2-param complexity, this is sufficient.

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 both parameters completely (100% coverage) with detailed descriptions. The description reinforces this with concrete examples and explains what each type returns, 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?

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, lists supported types (company/drug), and clarifies its role versus other tools ('other tools require as input'). This makes it distinct from sibling lookup/search 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 trigger conditions ('Use FIRST whenever you have a name but need an ID') and explains the tool replaces 2-3 manual lookups, giving clear when-to-use guidance. However, it does not explicitly list exclusions or 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that it probes each entity via ai_visibility_check, ranks by score, and returns score, confidence, and signal density. 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?

Four sentences, no fluff, front-loaded with main action and output. Every sentence adds useful information without redundancy.

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

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

Given no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It covers all four parameters, usage scenario, and behavioral details, making the tool 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 has 100% coverage for parameter descriptions. The description adds value by explaining that the first entity is treated as the subject and that probes use ai_visibility_check, which is not in the schema. It also clarifies the purpose of 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 compares AI visibility across multiple entities, probes with ai_visibility_check, and ranks results. It distinguishes from ai_visibility_check by focusing on side-by-side comparison and from compare_entities by specifying the AI-visibility domain.

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

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

The description explicitly states usage in competitive AI-marketing audits with an example question. It explains first entity as subject and the range of entities (2-8). However, it does not explicitly say when not to use this tool versus alternatives like ai_visibility_check.

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

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

Discloses partial failure behavior (bundlephobia timeouts) and graceful degradation, which goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). 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 fairly long but is front-loaded with the core purpose and returns. It includes important details, though some could be slightly condensed.

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 is provided, but the description fully details the return structure (summary block, per-advisory detail, links, alternatives) and handles edge cases like partial failures.

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

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

Schema coverage is 100%, but the description adds value by clarifying scoped package syntax and default version behavior, which is not present in the schema.

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

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

The description clearly states the tool's purpose as a composite check for deciding whether to add an npm package, specifying the data sources and return structure. It distinguishes itself from sibling tools by being specific to npm ecosystem in v1.

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

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

Explicitly says 'Use whenever an agent asks...' and provides concrete examples. Also notes limitations (NPM only in v1) and hints at alternatives for other ecosystems.

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

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

Beyond read-only annotations, it discloses 'no API key and no rate limit,' describes the return payload (opinion ids, relevance score, citation count), and notes the extra fetch cost of include_snippets. These are not 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?

Each sentence has a distinct purpose: main capability, output and snippet option, usage context and alternatives, and phrase query reminder. No redundant or vague 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?

For a read-only search tool with no output schema, the description fully covers input method, result contents, snippet cost, and related tools for follow-up. Annotations cover safety, 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?

The input schema already documents all three parameters, including quote-phrase guidance and snippet cost. The description adds no new parameter-level meaning; it repeats some schema details without going beyond.

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 'Search the FULL TEXT of US court opinions by subject matter' – a specific verb, resource, and scope. It explicitly contrasts with sibling tools: 'To find a case by NAME use find_case; by reporter citation use lookup_citation.'

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 states 'Use this when you know the TOPIC' and names alternatives for name/citation searches. It also advises when to omit include_snippets due to cost and when to call get_opinion for full text.

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 read-only, idempotent, and non-destructive behavior. The description adds context about searching full text vs. metadata, returning a matching excerpt, exact-phrase quoting, and the corpus size (9.7M documents), which enrich behavioral understanding without contradicting annotations.

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

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

The description is four sentences, each serving a distinct purpose: action + scope, use cases + alternative, return fields, and usage tip. It is front-loaded and information-dense without being bloated, though a bit longer than strictly necessary.

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

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

With no output schema, the description compensates by listing the exact return fields (filing description, date, excerpt, PDF link, docket_id) and relating them to a sibling tool for deeper access. It also covers search behavior and scope, making it sufficiently complete for an agent to invoke correctly. Minor omissions like result ordering are not critical.

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 descriptions already cover all three parameters with 100% coverage, including the exact-phrase tip for query. The description restates this tip but adds no new parameter-level detail, so it does not exceed the baseline expected when schema coverage is complete.

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 the text of US federal court filings, enumerates document types (complaints, motions, briefs, orders, exhibits), and specifies the source (PACER/RECAP). It also explicitly contrasts with search_case_law, distinguishing it from a key sibling.

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

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

Provides concrete use cases with examples (e.g., finding specific legal topics, defendant names, contract terms) and explicitly names the alternative for appellate opinions (search_case_law). Also suggests following up with list_docket_filings, giving clear guidance on when to use this tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context about the archival coverage (PACER and RECAP) and details the retuned fields, which provides behavioral insight beyond the annotations. No contradictions with annotations exist.

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

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

The description is two sentences long, front-loaded with the primary purpose, and efficiently conveys scope and result structure without wasted 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?

For a search tool with a clear input schema, annotations, and an output schema, the description sufficiently covers what the tool searches, what archives it covers, and what the results contain. No major gaps are evident.

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

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

Schema description coverage is 100%, so the baseline is 3. The description references 'keyword' but does not add meaning to the parameters beyond what the schema already documents. The limit parameter's pagination behavior is described in the schema, not the description.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Search US court dockets by keyword.' It also distinguishes itself from sibling tools by noting coverage of PACER and RECAP archives and enumerating the result fields, which differentiates docket search from opinion 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 implies usage by stating the search scope and result contents, but it does not explicitly state when to use this tool versus alternatives like search_opinions. No exclusions or alternative recommendations are 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?

Beyond the readOnly/idempotent annotations, the description discloses that the tool uses an internal mirror, has no API key/rate limit, automatically falls back to live CourtListener for certain queries, and returns snapshot_date and opinion_ids. These are meaningful behavioral traits not inferable from annotations alone.

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 every sentence earns its place: scope, strengths/limitations, filters, fallback conditions, and result pointers. It is front-loaded with the primary action and structured logically, making it easy to scan.

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

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

Given the tool's complexity (large corpus, mirror vs live, multiple filters), the description covers all essential aspects for selection and invocation: what it searches, its limitations, filter meaning, fallback rules, and where to read results. With the output schema present, no further detail is needed.

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?

Although the input schema already covers 100% of parameters, the description adds interpretive depth: jurisdiction is 'inferred from the citation reporter', date_filed is 'the real ruling date', and a court code triggers fallback to live search. This adds meaning beyond the raw 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 opens with a specific verb and resource: 'Search US court opinions', and adds scope details ('8.3 million', '71% state case law'). It clearly distinguishes itself from siblings by naming find_case as an alternative for party searches and referencing get_opinion for reading results.

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 when to use the tool vs alternatives: 'use find_case when you know the party', and warns about weakness on doctrine-only phrasing. It also states when a fallback to live search happens (specific court code or recent filing), helping the user anticipate behavior.

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 cover safety (readOnlyHint, idempotentHint, etc.), and the description adds rich detail: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char windows), character cap (200K, with truncation flag). No contradiction.

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

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

The description is front-loaded with the core purpose and includes only informative sentences. It is appropriately sized with no redundancy.

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

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

Despite no output schema, the description explains the return format (passages with offsets and similarity scores) and cap behavior. It covers all essential aspects for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving example queries for the 'query' parameter, clarifying the default and range for 'limit', and explaining the 'text' parameter's purpose and max length.

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 performs semantic search inside a fetched record, provides examples (SEC 10-K, article), and distinguishes from siblings by pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use ('when record is too big to cram into prompt'), provides an alternative (ask_pipeworx_grounded), and explains the benefit of character offsets for verification.

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

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

The description discloses important behavioral traits: requires Pipeworx OAuth account, supported subscription types, delivery channels, rate limits (10/day SMS), and webhook HMAC signing. However, it does not address idempotency as indicated by idempotentHint=true; the phrase 'Returns the new subscription id' implies each call creates a new subscription, contradicting the 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 well-structured and front-loaded with the core function, followed by requirements, types, and delivery options. It is relatively long but each section provides necessary detail; could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description adequately covers input semantics, requirements, and behavior. It specifies the return value (new subscription ID) but lacks details on error handling and does not clarify idempotency, which is a minor gap.

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

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

The description significantly enriches the input schema with concrete examples and usage guidance for each parameter, such as sec_8k items codes, polymarket_edge topics, and delivery channel details. Schema coverage is 100%, and the description adds substantial value beyond the structured definitions.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a new subscription ID. It uses a specific verb ('Create') and resource ('proactive monitoring subscription'), distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description does not explicitly state when to use this tool versus alternatives like list_subscriptions or unsubscribe. It provides detailed usage instructions but lacks direct comparison or exclusion guidance.

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

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

Annotations already declare safe read operations (readOnlyHint, idempotentHint, etc.). The description adds behavioral context: returns category-bucketed example questions with exact tool+argument shapes, and explains effect of passing vs omitting topic. 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 somewhat lengthy but well-structured with example questions, use cases, and parameter guidance. Every sentence adds value, though could be slightly more concise.

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

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

Given no output schema, the description fully explains the return format (category-bucketed examples with tool+argument shapes). It covers purpose, usage, parameter, and output, making it complete for a simple tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining that omitting topic gives a cross-category spread, and listing example values like 'finance', 'pharma', etc., which are not in 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's purpose as an onboarding entry point for learning what Pipeworx can do, listing example questions and output format. It also contrasts with sibling meta-tools like ask_pipeworx, making the purpose distinct.

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 the agent to use this FIRST when it doesn't know what Pipeworx can do, or to learn how to call meta-tools. It also describes optional topic focus for narrowing, providing clear when-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?

Adds value beyond annotations by detailing ownership enforcement, deactivation (not deletion), and availability of historical events via recent_alerts. Aligns with annotations (destructiveHint=false, readOnlyHint=false).

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

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

Two sentences with no wasted words, front-loading the core purpose and key constraint.

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

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

Covers all essential aspects: action, ownership, side effect, and relationship to historical data. Complete for a simple tool with one param.

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

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

Schema already fully describes the single parameter (id) with a description. Description does not add new details beyond mentioning 'by id'.

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

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

Description clearly states the verb 'cancel' and the resource 'subscription', distinguishing from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement and the deactivation behavior, providing context for when to use and what to expect, though no explicit alternatives are named.

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 safe, read-only behavior. The description enhances transparency by detailing the dual pipeline (SEC EDGAR for financial claims, grounded pipeline for others), the return format (verdict, actual value with citation, reasoning), and the efficiency gain (replacing 4-6 calls). 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 relatively long but well-structured with a clear front-loaded purpose. Every sentence contributes meaningful information. While it could be slightly more concise, it remains effective and organized.

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 values: verdict types, actual value with citation, and reasoning. It covers both processing paths and parameter behavior, leaving no major gaps for an agent to understand the tool's capabilities.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the tolerance_pct override behavior and its typical use cases (e.g., hallucination detection with 1-2%). This goes beyond the schema's description of the parameter.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific example queries and distinguishes between financial and other claims, making the purpose crystal clear. While it doesn't explicitly compare to siblings, the unique function is well-articulated.

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 clearly indicates when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It outlines two distinct pipelines for different claim types, providing context on how the tool operates. However, it does not explicitly state when not to use or suggest alternatives, which would strengthen this dimension.

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