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 readOnly/openWorld/idempotent behavior; the description adds beyond that: it internally routes and fills arguments, returns stable citation URIs, and is positioned as the default entry point with one fast call. It does not discuss failure modes or rate limits, but those are less critical for a read-only router.

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 'PREFER OVER WEB SEARCH' and organized with examples, but it is dense and somewhat repetitive: 'PREFER OVER WEB SEARCH', 'even if web search could also answer it', and 'START HERE for most questions' all make the same point. The alternatives section reads like an appended note rather than clean structure.

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 still explains the return shape (structured answer with stable citation URIs), enumerates covered data domains, gives representative examples, and routes to the relevant sibling tools. Nothing essential for invoking it correctly is missing.

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

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

Schema coverage is 100% and all six parameters are aliases of one natural-language question field. The description adds useful semantic context by showing the question can be a broad request ('Apple's latest 10-K') and explaining that the tool itself fills arguments, so the agent need not know sub-tool parameters.

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 names a precise verb and resource: it routes a natural-language question to one of 5,798 tools across 1,517 verified sources and returns a structured answer with pipeworx:// citation URIs. It also distinguishes itself from siblings by specifying when ask_pipeworx_grounded and deep_research should be used instead.

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 gives explicit, capitalized guidance to prefer this tool over web search, lists trigger phrases ('what is', 'look up', 'find', 'get the latest'), provides concrete example queries, and names the exact conditions for switching to ask_pipeworx_grounded or deep_research.

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 the tool as read-only, idempotent, and non-destructive. The description adds meaningful context: it is an experimental edge, candidate routing improvements may be live, no candidate is currently active, and it currently matches ask_pipeworx exactly. It also clarifies there is no fallback since this is a fully working router. No contradiction with annotations.

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

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

The description is front-loaded with the key identity statement and is mostly structured well. However, it repeats the idea that this matches ask_pipeworx exactly twice, and includes a specific retirement date that adds marginal value. It is informative but not as tight as it could be.

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

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

The description covers identity, experimental status, usage, and fallback behavior well. Since there is no output schema, it only says 'same response shape' without describing what that shape is, leaving the agent to infer response details from the sibling tool ask_pipeworx. For a router with simple parameters, this is adequate but not 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?

Schema description coverage is 100%, so all six parameters are already documented, including the alias relationship to question. The description only adds a generic statement that arguments are the same as ask_pipeworx, which is useful but not parameter-specific. Baseline 3 is appropriate because the schema carries the semantic load.

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 a beta version of ask_pipeworx and calls it a universal router with the same 5,798 tools, arguments, and response shape. It distinguishes the tool from the stable ask_pipeworx by noting candidate routing improvements. It does not fully spell out what ask_pipeworx itself does, but the purpose is reasonably 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 says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. This gives a concrete usage condition. It does not mention when not to use it or explicitly route to ask_pipeworx_grounded, but the guidance is otherwise 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses crucial behavior: it returns verbatim evidence, provides a structured refusal with specific reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and never invents facts. It also transparently mentions the extra cost relative to ask_pipeworx. 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 dense but every clause adds information: behavioral guarantee, routing mechanism, return contract, refusal contract, usage guidance, cost tradeoff, and alternative routing. It is front-loaded with the most decision-relevant trait ('hallucination-resistant') and stays structured and readable despite its length.

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

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

With no output schema, the description fully documents the success return shape and every refusal reason, making the agent's post-invocation handling predictable. It also covers when to use, when not to use, cost, and the grounding limitation ('data_truncated'), leaving no critical operational gap.

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

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

Schema description coverage is 100%, and the schema already documents the 'question' parameter and all its aliases (query, q, prompt, text, input). The tool description itself adds little parameter-level detail beyond saying the tool 'fills arguments' internally, so the schema carries the semantic weight.

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: 'hallucination-resistant answer mode for high-stakes reads' and explains exactly what it does: routes a question across 5,798 tools/sources, fetches data, and extracts an answer only from the tool result. It explicitly distinguishes itself from ask_pipeworx and ask_pipeworx_beta by emphasizing grounded, evidence-backed answers.

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 gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples like financial verdicts, legal claims, medical lookups, and public statements. It also states when NOT to use it: 'prefer ask_pipeworx for casual lookups,' and explains the tradeoff (one extra LLM call).

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

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

Annotations already 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 readOnly/openWorld/idempotent behavior, and the description adds rich details beyond that: parallel routing, a findings packet with evidence/confidence/source/fetched_at/citation, explicit gaps[] that are never invented, contradictions[] for standard and thorough, fetchable citation URIs, semantic excerpting, and latency expectations. It also discloses auth and plan gates not visible in annotations. There is no contradiction with 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 long but dense, and it front-loads the critical access gate: account sign-in, the unpaid fallback, and the paid depth requirement. Some repetition exists with the depth enum descriptions in the schema, and the parenthetical style makes scanning harder. Still, most sentences carry behavior worth documenting for a tool this complex.

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 having no output schema, the description covers the output contract in enough detail for an agent to know what to expect: per-finding fields, citation fetchability, gaps, contradictions, and latency. It also covers auth, plan limits, alternative tool selection, and depth semantics. Nothing needed for correct selection or invocation appears to be missing.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds meaningful context about depth tiers, the paid threshold, the default depth, and how multi-step questions resolve in one call. It also reinforces that natural-language multi-part questions are acceptable, which adds value beyond the raw schema text.

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

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

The description clearly states the tool's specific purpose: grounded multi-source research across 1,517 structured data sources, decomposing a question into facets and routing them to tools in parallel. It explicitly contrasts itself with open-web search and with ask_pipeworx/single lookups, making its scope easy to distinguish from siblings. The verb-resource pairing is specific and not a tautology of the name.

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

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

The description gives explicit when-to-use rules: it is 'Best for broad/multi-part questions over structured data' with concrete examples, and it says 'For a single lookup use ask_pipeworx instead.' It also instructs unsigned agents to use ask_pipeworx and specifies that the 'thorough' depth requires a paid plan. This level of alternative routing is unusually strong.

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

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

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 readOnly, openWorld, idempotent, and non-destructive. The description adds substantial context on top: fan-out across multiple sources, sources_used/sources_failed semantics, empty sections meaning real no-data, USPTO sunset soft-fail, GDELT→GNews fallback, and name-resolution behavior. 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 dense and run-on, but for a tool this complex, the details are mostly purposeful. It front-loads the intent with example queries and the 'ONE parallel call' promise, while the tail covers important edge behavior. Minor redundancy with the schema's type enum and a single unstructured paragraph keep it from a 5.

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

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

With no output schema, the description fully carries return-value documentation, enumerating every section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed). It also explains expected failures and empty sections, making the tool fully callable without further discovery.

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, so baseline is 3. The description adds value by providing concrete examples (AAPL, 0000320193, Moderna), clarifying that type accepts 'company' or 'ticker' interchangeably, and explaining that name values resolve via SEC EDGAR's company-name match. These enrich, rather than merely repeat, 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 names a specific verb (profile), a clear resource (US public company), and a distinctive mode (one parallel cross-source call). It explicitly contrasts itself with chaining single-pack SEC/XBRL/news lookups, making it easy to distinguish from sibling tools like search_court_filings or get_docket_filing.

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 'ALWAYS PREFER' guidance for holistic company views and names the alternative pattern to avoid (chaining single-pack lookups). It also states when not to expect success (private companies returning resolved:false) and notes person/place support is coming, providing concrete boundary conditions.

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 are all false, so the description carries the full disclosure burden. It reveals key behaviors: filing returns a claim_token for later lookup, it is rate-limited to 5 per identifier per day, and it is free with no quota impact. It also explains the follow-up workflow via pipeworx_feedback with claim_token. 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 longer than a typical two-sentence MCP tool, but each sentence earns its place. It is front-loaded with the purpose, then provides use cases, exclusions, content guidelines, and operational details. Minor redundancy exists (e.g., 'Not sure? Pipeworx tool names are the ones this connection lists.'), but overall it is well-structured and not bloated.

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

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

For a tool with 4 parameters, nested context object, no output schema, and no helpful annotations, the description is exceptionally complete. It covers selection criteria, exclusions, parameter-specific guidance, claim_token flow, rate limits, and even policy context (daily digest, roadmap influence). An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra semantics for the message parameter ('don't paste the end-user's prompt') and clarifies the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). This raises it above baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource (Pipeworx feedback), and distinguishes from siblings by enumerating the exact feedback categories (bug, feature/data_gap, praise) and scoping it to Pipeworx tools only.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an exclusion rule: if the tool came from a different MCP server, file it there instead. This is direct when/when-not guidance with a named 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 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 (readOnlyHint, idempotentHint, destructiveHint=false) already convey safety, but the description goes far beyond them: it discloses that matching is keyword/word-overlap based and not verified against a shared resolution source (pairing_unverified), that spreads are gross of Kalshi fees (fees_note), that 'unknown' legs are never paired, and that temporal_alignment null means 'could not be computed', not 'aligned'. 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 long, but it's organized into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and nearly every sentence carries a risk disclosure needed to avoid misinterpreting returned spreads. There is minor redundancy (e.g., 'pre-mapped ≠ tradeable' re-emphasizes the earlier warning), but for a tool with so many caveats the density 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 no output schema, the description carries the entire burden of explaining response semantics—and it does so thoroughly: top_spreads_pp sign convention, compatibility_codes, per-entry flags, skipped_unclassified and low_confidence_pairs, temporal_alignment semantics, fees_note, and skipped_cross_type/subtype counters. Both invocation modes are covered, and the null-vs-false distinction for temporal alignment is explicitly addressed. Nothing necessary to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema: it explains that topic maps to a pre-mapped event on each venue, that explicit ticker/slug override the mapped sides, and that 'BOTH modes run the identical token-overlap matcher, so the same disclosures apply to both.' This clarifies how the parameters interact rather than just restating their types.

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 first sentence names the specific resource ('cross-venue spread between Kalshi and Polymarket') and the question it resolves ('same resolving question'), with a clear verb and scope. The description distinguishes it from sibling Polymarket tools by emphasizing cross-venue comparison, compatibility warnings, and 'real signal' vs. non-equivalent bet-shape caveats.

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 specifies two modes and exactly when to use each: topic mode for 10 pre-mapped shortcuts, explicit mode for custom kalshi_event_ticker + polymarket_event_slug pairings. It also sets expectations by warning that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It stops short of naming sibling alternatives or giving explicit 'do not use when...' exclusions, so it doesn't fully 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?

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, and non-destructive, and the description adds rich behavioral detail: ambiguous matches return figi_candidates, unresolved identifiers are explicitly listed, LEI/FIGI enrichment degrades gracefully, and internal cascading lookups are disclosed. No contradiction with annotations.

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

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

The description is long but front-loaded with query patterns and the key 'Use FIRST' directive. Most sentences carry unique information, though the parenthetical about issuer names adding no single bond is somewhat redundant and the dense run-on structure could be tightened.

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

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

For a high-complexity tool with no output schema, the description covers ambiguous matches, unresolved identifiers, source provenance, enrichment failures, and supported resolution paths. An agent has enough context both to decide when to use it and to invoke it correctly.

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

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

Although schema description coverage is 100%, the description adds significant meaning beyond the schema: concrete value examples for company and drug, the explicit instruction to pass only the entity name, and the warning that trailing security-class words break FIGI matching. This materially improves invocation accuracy.

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 concrete user queries and a clear verb+resource statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes this tool from ID-consuming siblings by emphasizing that it produces identifiers required elsewhere, making its purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and notes that one call replaces two or three manual lookups. It does not explicitly name sibling tools or provide when-not-to-use conditions, but the primary trigger is unambiguous.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by adding behavioral details: it states that there is no rate limit, explains automatic fallback to a live search for certain cases, notes that results carry snapshot_date and opinion_ids, and candidly admits strengths (party names, judges, categories) and weaknesses (doctrine-only phrasing). There is no contradiction with annotations.

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

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

The description is front-loaded with the most crucial information (what it searches, scale, no API key/rate limit) and then expands with examples and limitations. Every sentence contributes actionable guidance—no filler. While longer than typical, it remains efficient and well-structured, with each clause justified for an agent's decision-making. The format uses concrete examples to illustrate usage without redundancy.

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

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

Given the tool's complexity (6 parameters, fallback behavior, multiple court types, output schema), the description is thorough. It explains filtering by jurisdiction and date, covers the fallback mechanism, clarifies the result payload (snapshot_date, opinion_ids), and provides usage examples. The presence of an output schema means return values need not be elaborated further, so nothing essential is missing 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% with all six parameters individually described. The description adds substantial semantic value beyond the schema: for 'court' it explains the fallback trigger; for 'query' it details query strengths and limitations; for 'date_after'/'date_before' it emphasizes the real filing date; and for 'jurisdiction' it notes that it is inferred from the reporter citation. This enriches the schema's baseline descriptions significantly.

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 precise statement of what the tool does: 'Search US court opinions from CourtListener — 8.3 million of them, with no API key and no rate limit.' It names the exact resource (CourtListener opinions), the scope (US courts), and gives concrete examples ('What did the Supreme Court hold in Air France v. Saks?'). It also distinguishes itself from siblings by explicitly noting when to use find_case instead, making the differentiation 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 provides explicit usage guidance, including when to prefer this tool over alternatives: 'use find_case when you know the party, and expect this to sometimes miss on doctrine-only phrasing.' It also clarifies when a fallback to live CourtListener search occurs (specific court code or out-of-window dates). This gives agents clear criteria for selecting this tool and what to expect from its results.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it details the two processing paths (SEC EDGAR vs grounded), lists all verdict types, and crucially distinguishes "could_not_verify" (check didn't happen) from "unsupported" (no source exists). It also warns callers not to treat could_not_verify as evidence, which is a meaningful disclosure beyond the annotations.

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

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

The description is long but appropriately so given the complexity of the tool. It is front-loaded with trigger phrases and a clear directive, then covers routing, return values, and critical caveats. Every sentence contributes information, though it could be slightly tightened without losing value. The structure flows well from purpose to usage to behavior.

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 must explain return values, and it does: it lists the possible verdicts, mentions the grounded/structured actual value with a pipeworx:// citation, and includes reasoning. It also explains error conditions (could_not_verify) and the meaning of unsupported. For a tool with this many behaviors and failure modes, the description is complete and self-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?

The input schema already provides full descriptions for both parameters (claim and tolerance_pct), so the baseline is 3. The description adds extra semantic value by explaining that tolerance_pct "Overrides the tolerance implied by the claim wording" and suggests setting 1–2 for hallucination detection, plus the default cap of 5. This goes beyond the schema and helps agents set parameters appropriately.

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 vivid natural-language triggers ("Is it true that…", "fact check") and immediately states the core function: "natural-language claim verification against authoritative sources." It separates financial claims (SEC EDGAR fast path) from other claims (grounded pipeline), making the tool's scope and behavior unambiguous and distinguishing it from sibling lookup tools.

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

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

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," which is clear when-to-use guidance. It also explains how the tool routes different claim types. It does not name a specific alternative tool to use instead, but it notes that it replaces 4–6 sequential calls, giving a strong sense of when this tool is the efficient choice.

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