Regulations Gov

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

Annotations already indicate readOnly/idempotent/non-destructive behavior. The description adds valuable context beyond annotations: the default model is free, passing _apiKey involves BYO key with direct payment to Anthropic, and it discloses the per-model response structure. 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 three sentences, front-loaded with the main purpose, and every sentence earns its place: it covers the action, output format, model options, key requirement, and relevant use cases. No filler 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?

With no output schema, the description compensates by specifying the exact per-model return structure ({score, confidence, signals, raw_response}) and a combined view. It covers model selection, free vs paid defaults, and typical use cases, making it sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning by naming the specific default model (Workers AI Llama-3.3-70b) and clarifying that _apiKey is passed through to Anthropic, which provides cost/usage semantics beyond the schema's simple 'required for anthropic' note.

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 ('probe') and resource ('one or more LLMs'), and clearly defines the output (visibility score 0-100 per model). It also distinguishes itself from sibling tools like scan_competitor_ai_presence by covering any business/brand/product/topic, not just competitors.

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 use cases are given ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and it explains when to pass _apiKey (to also probe Anthropic). However, it does not explicitly mention alternatives or when not to use the tool, so it falls short of a 5.

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

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

Description discloses that the tool is fast, works on all tiers, and returns structured answers with citation URIs. It explains routing behavior and fallback options. Annotations (readOnlyHint, openWorldHint, idempotentHint) are fully consistent with the described non-destructive, read-only behavior. 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 provides many examples. It is somewhat longer than necessary, but every sentence earns its place by adding guidance or alternatives. Minor redundancy in examples could be trimmed.

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, rich annotations, and complete schema, the description is remarkably complete. It explains when to use it, what it returns, and what to do for advanced cases. No output schema is needed because the description covers citation URI format.

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

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

With 100% schema coverage for parameters, the baseline is 3. The description adds meaningful context by listing example queries and explaining the natural language usage, but parameter documentation is already complete in the schema. The score is 4 because the examples and aliases are helpful 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 that ask_pipeworx routes questions across a vast index of 5,563 tools across 1,462 verified sources for authoritative structured data. It enumerates specific domains (SEC, FDA, FRED, patents, etc.) and contrasts with web search, making its purpose highly specific and distinguishable from siblings.

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

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

Explicit guidance is given: prefer over web search, use for factual queries, and step up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad/multi-part questions. Examples of when and when not are provided, including breaking-news handling.

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 key behavioral traits beyond annotations: it's a working router (not a wrapper), falls back to nothing, has candidate routing improvements that may be live or not, and its results are used for comparison to the stable router. The annotations already state readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, and the description adds crucial context about experimental nature and fallback behavior without contradiction.

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

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

At three sentences, the description is efficient and front-loaded. Every sentence adds distinct value: identity, behavior, usage guidance. No filler.

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

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

Given the tool's complexity (5,563 tools routed), the description adequately covers purpose, usage, and behavioral nuance. No output schema exists, but the description states same response shape as ask_pipeworx, which compensates. Minor gap: doesn't explain the candidate improvement mechanism in detail, but sufficient for selection and 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% and the description notes it uses the same arguments as ask_pipeworx. While the schema documents all parameter aliases, the description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states this is a universal router identical to ask_pipeworx but with candidate routing improvements under test. It specifies it has the same 5,563 tools, same arguments, and same response shape. This differentiates it from its sibling ask_pipeworx by noting it's the experimental edge version.

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

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

Provides explicit guidance to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router to decide what merges. It also says no candidate is active right now, so it currently matches ask_pipeworx exactly, which helps the agent decide when to pick 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true—but the description adds critical behavioral specifics beyond these: the two-phase routing (tool selection + extraction), the return format (answer, evidence, confidence, source, fetched_at, refusal_reason), and five explicit refusal reasons. This is comprehensive additive context, not redundant.

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 essential purpose in the first sentence. Every sentence adds value: mode purpose, routing behavior, return format, refusal reasons, use cases, and cost tradeoff. No wasted words—it is dense but fully accessible.

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 and explicitly documents the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all five refusal reasons. It also covers routing paths and cost implications. For a complex, high-stakes tool, this is exceptionally complete.

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

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

Schema description coverage is 100%, so the description does not need to elaborate on parameters. The baseline is 3. The description does not add usage context for the aliases (q, text, input, query, prompt), but since the schema already documents them, no penalty 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 a specific verb-resource pair: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly distinguishes itself from ask_pipeworx by describing the extraction-only behavior and refusal mechanism. The scope (high-stakes, quoted/cited answers) is precise and differentiates it from siblings.

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 when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a concrete when-not-to-use and alternative: 'prefer ask_pipeworx for casual lookups.' The cost tradeoff (one extra LLM call) is stated transparently.

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=true, destructiveHint=false), the description discloses extensive behavioral details: resolver contract with confidence levels and alternatives, parent_event extraction for partition markets, news fallback handling, safety short-circuiting for low-confidence matches, closed-market handling, wide-spread tradeability notes, and cancellation-rule risk. This far surpasses the annotation coverage.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) that make it scannable. While it is wordy and contains some redundancy (e.g., repeating that low-confidence matches are blocking via two routes), each section adds essential value for such a complex tool, so it earns a 4 rather than a 3.

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?

Because there is no output schema, the description must cover return values, and it does comprehensively: result.market fields, result.analysis with model_probability/edge, result.evidence keying, resolver contract fields, parent_event structure, news fallback fields, and status conditions (low_confidence_match, market_closed_or_inactive). It also covers resolution-rule risk and illiquidity warnings, making it highly complete for an agent to invoke 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%, so the schema already documents all three parameters (market, depth, include_raw). The description reinforces the market parameter's input forms but doesn't add new meaning for depth or include_raw beyond the schema. The baseline of 3 is appropriate because the schema carries 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 opens with a specific and clear statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further explains the pipeline (resolve, classify, fan-out to data packs, return evidence packet and market-vs-model comparison), making it easy to distinguish from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

It explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides many concrete examples and classifier categories that indicate appropriate contexts. However, it does not explicitly state when *not* to use the tool or name direct alternatives, so it misses the top score for 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?

Beyond the readOnly and idempotent annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS), special handling (off-calendar fiscal years like AAPL Sep), sorting behavior ("Results sorted by primary metric"), and output format (paired data + citation URIs). This significantly enriches the agent's understanding beyond the structured 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: trigger phrases, usage preference, per-type data details, sorting, and output. It is front-loaded with the core purpose and uses compact but clear phrasing 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 tool with no output schema, the description fully explains what the agent will receive (paired data, citation URIs), how results are ordered, and covers both entity types. It also conveys the efficiency benefit (replaces 8-15 lookups).

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 critical semantics: for "type=company" it lists specific financial metrics pulled (revenue, net income, cash, long-term debt), and for "type=drug" it lists FAERS counts, FDA approvals, and trial counts. It also provides concrete examples for the values array (["AAPL","MSFT"], ["ozempic","mounjaro"]).

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 comparisons of 2-5 companies or drugs in a single call, with explicit trigger phrases ("X vs Y", "which is bigger", "rank these companies"). It distinguishes itself from siblings like entity_profile by focusing on multi-entity comparison and mentioning it replaces sequential lookups.

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

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

It provides explicit guidance: "ALWAYS PREFER over sequential single-pack lookups when comparing entities". It also differentiates between type="company" and type="drug" use cases, specifying what data each returns, which helps the agent decide 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: account requirements, parallel processing, return format (findings packet with verbatim evidence, confidence, source, gaps, contradictions), time expectations (15-90s), semantic excerpting, hop fields, and citation URIs. There is no contradiction with annotations; the description enriches the agent's understanding beyond what annotations convey.

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

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

The description is front-loaded with the account requirement, then explains the tool, usage guidance, and details. It is verbose but well-structured and informative. Each sentence adds value; however, the length could be slightly trimmed without losing clarity. The structure is logical and easy to follow.

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

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

Given the tool's complexity (2 params, no output schema), the description is remarkably complete. It covers the tool's mechanics, when to use, return format, time expectations, edge cases (breaking news, sign-in requirement), and second-hop iteration behavior. It also explains citations and hop fields. The agent has all necessary context to correctly select and invoke this 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% for both parameters. The description adds significant meaning: for 'depth', it explains the enum values in detail (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop) and mentions the contradictions[] feature for standard and thorough. For 'question', it clarifies that broad/multi-part questions are fine and decomposition is the point. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call.' It distinguishes itself from the sibling ask_pipeworx, specifying that deep_research is for broad/multi-part questions over structured data, while ask_pipeworx is for single lookups or breaking news. This provides a specific verb-resource pairing with clear differentiation.

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

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

The description explicitly provides when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and alternatives (ask_pipeworx for different scenarios, and noting that if not signed in, use ask_pipeworx). It also explains the depth options and their behavior, giving clear context for selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'no second schema lookup needed.' This is useful behavioral context beyond the annotations, though it doesn't cover edge cases like rate limits or error behavior.

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 efficient but packs a lot: purpose, domain list, return format, and usage guidance in four sentences. It is front-loaded with the core purpose and ends with actionable guidance. The domain list is a bit long, but it earns its place by clarifying the tool's breadth.

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

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

Given the tool's meta-nature (discovering other tools) and the absence of an output schema, the description covers what the agent needs to know: what it returns, how results are ready to use, and when to invoke it. It does not need to explain return values beyond that because the description itself explains the return format. The only minor gap is no mention of failure behavior for unknown queries, but this is adequately covered for a discovery 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% (all six parameters have descriptions, including aliases). The description adds little beyond the schema—'describing the data or task' mirrors the query parameter description. It does not add syntax, constraints, or examples beyond what the schema already contains, so the baseline 3 is appropriate.

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

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

The description opens with a clear verb+resource construction: 'Find tools by describing the data or task.' It enumerates a broad range of domains (SEC filings, FDA drugs, FRED, etc.), which clarifies scope, and explicitly names synonyms like 'browse, search, look up, or discover' that distinguish it from sibling tools. It positions itself as the first-step discovery tool, setting it apart from more focused search tools.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent the ideal context and implies not to use it when a specific tool is already known, making the usage boundary clear relative to siblings.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, GDELT/GNews, GLEIF), discloses that patents soft-fail due to API sunset, describes the fallback chain, and outlines exact return fields. 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 dense but well structured, front-loaded with user intent examples and followed by a clear return-value list. The seven example queries are somewhat redundant, but they aid recognition; the rest of the text is information-dense and earns its place. Minor length deduction.

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 burden of explaining what the tool returns, and it does so thoroughly: CIK/name, recent filings with URIs, fundamentals sorted by period, patents with sunset caveat, news fallback, and LEI. It also covers required input format and limitations. This is complete for tool selection and 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?

The input schema fully documents both parameters ('type' enum and 'value' with examples and name restriction), so schema coverage is 100%. The description restates the ticker/CIK requirement and the resolve_entity caveat but adds no new parameter semantics beyond the schema; baseline 3 is appropriate.

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

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

The description opens with multiple user-phrase examples and clearly identifies the action as creating a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by explicitly stating preference over chaining single-source lookups and by focusing on holistic profiles rather than entity resolution or comparison.

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

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

It explicitly says to use this tool when the user asks for a holistic view, and to prefer it over chaining single-pack SEC/XBRL/news lookups. It also gives a when-not-to-use: if only a name is available, first use resolve_entity, because names are not supported.

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 destructiveHint=true and idempotentHint=true, and the description consistently says 'Delete' and 'clear sensitive data', adding context about when deletion is appropriate. There is no contradiction, and the description adds value by explaining why deletion might be needed.

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, focused sentence that front-loads the action, then provides use cases and related tools. Every phrase is useful, 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?

This is a simple, one-parameter destructive tool with rich annotations. The description covers purpose, usage, and relationships with siblings, while the schema fully documents the parameter. No output schema exists, so return value details are not expected.

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 only parameter 'key' is described as 'Memory key to delete' in the schema. The description merely repeats 'by key' without adding new semantic details, so it meets the baseline but does not enhance understanding beyond the schema.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key', making the primary action unmistakable. It also names sibling tools (remember, recall) to distinguish its role in the memory workflow.

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

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

The description gives explicit use cases ('context is stale, the task is done, or you want to clear sensitive data'), providing clear situational guidance. It also mentions pairing with remember and recall, but does not explicitly state when not to use it or alternatives for deletion.

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 disclose read-only, idempotent, and non-destructive behavior. The description adds useful behavioral details beyond that: it fetches the page, extracts specific elements, and produces a single text blob suitable for site-root/llms.txt. 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 three sentences long, front-loaded with the core purpose and process. Every sentence carries meaningful information (what, how, output, use cases) without redundancy or fluff.

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

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

Even without an output schema, the description explicitly states the output format (llms.txt markdown) and intended deployment location. Combined with the schema and annotations, the tool is fully specified: the agent knows what it does, how it behaves, and what to expect.

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

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

The schema provides complete descriptions for both parameters (url and max_links), so the description does not need to compensate. The description mentions extracting 'key links' but does not explicitly discuss max_links, though the schema already covers its default and max values. This is a solid baseline-3 case.

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: generating a production-ready llms.txt file for any URL. It specifies the process (fetches page, extracts title/description/key links, emits markdown) and distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on analysis rather than file generation.

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

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

The description provides clear use cases: getting a client's site indexed, drafting llms.txt for one's own project, or auditing a competitor. This gives solid context for when to use the tool, but it does not explicitly mention alternatives or when not to use it, stopping short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context by noting the comment is 'public' and lists the returned fields (text, submitter, posting date, attachments), which goes beyond the annotations without contradicting them.

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

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

The description is two sentences with no filler. The first sentence states the core purpose immediately, and the second succinctly lists the return contents, making it highly efficient and well-structured.

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

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

Given the low complexity, rich annotations, full schema coverage, and presence of an output schema, the two-sentence description is complete. It conveys the essential usage (by comment ID) and expected return fields without needing further elaboration.

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

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

Schema coverage is 100%, with both comment_id and include_attachments having descriptions in the schema. The tool description does not add new parameter-specific semantic detail beyond confirming ID-based lookup, 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 opens with 'Single public comment by comment ID', clearly stating the verb (retrieve) and resource (a comment) with a specific selector. This distinguishes it from sibling tools like search_comments, which handle broader search, making the purpose unambiguous.

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 phrase 'Single public comment by comment ID' clearly implies that this tool should be used when the agent has a known comment ID and needs one specific comment. It does not explicitly mention alternatives or exclusions, but the context is sufficiently clear for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by specifying the return content ('full metadata + summary counts') and providing a concrete docketId format example.

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?

One concise, front-loaded sentence with zero waste. The core action and resource are immediately clear.

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 read-only tool with an output schema and strong annotations, the description adequately covers purpose, return content, and example. The only minor gap is the lack of explicit usage guidance, but this is not critical given the tool's simplicity.

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

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

The schema covers 100% of the single parameter with a description. The description reinforces with an example, but no additional semantic detail is needed 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 clearly states the action ('Single docket detail') and resource ('by docketId'), with an example. This distinguishes it from sibling tools like search_dockets (list) and get_comment (a different resource).

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 use when you have a specific docketId and need full metadata, but it does not explicitly state when to use it versus alternatives or mention any exclusions. This is adequate for a simple lookup but lacks explicit guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds transparency about the output contents (title, type, comment counts, posted date, document ID) without duplicating annotations. It does not contradict any annotation and provides useful behavioral context.

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

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

The description is two sentences long, front-loaded with the core purpose, and immediately lists return fields. Every word contributes value; there is no redundant or filler content.

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

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

Given the rich input schema (all parameters documented), output schema availability, and annotations covering safety, the description is sufficiently complete for a listing tool. It covers the operation's scope and return values, leaving no critical gaps for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so each parameter already has a clear description. The tool description only reiterates the docket/query scoping and does not add new semantic detail such as pagination behavior, filtering nuances, or defaults beyond what the schema provides. This matches the baseline for full schema coverage.

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

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

The description clearly states the tool lists documents within a docket or matching a free-text query, and enumerates the returned fields. This distinguishes it from sibling tools like get_comment or search_dockets by focusing on the document entity and its scoping options.

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

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

The description implies usage context by mentioning docket or query-based retrieval, but does not explicitly contrast with alternatives such as search_dockets or get_docket. The agent must infer when to prefer this tool over others based on the resource type, and no exclusionary guidance is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral detail by listing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and specifying the scope ('caller's'), which goes beyond the high baseline. 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 three concise sentences: what it does, what it returns, and when to use it. Every sentence carries useful information with no redundancy or filler, making it highly efficient and well-structured.

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

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

The tool is simple: one optional parameter, no output schema, but the description explicitly enumerates the return fields, covering the return contract. Combined with annotations that fully disclose safety and usage guidance, the description is complete for an agent to invoke correctly without ambiguity.

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 single optional boolean parameter 'include_inactive' clearly documented as 'Include cancelled subscriptions in the response (default false).' The description does not add extra meaning beyond the schema, 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 uses a specific verb 'List' and identifies the exact resource: 'the caller's active subscriptions.' It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on reviewing existing subscriptions and finding an id to cancel, making its purpose unambiguous.

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 this to review what you're monitoring before adding more or to find an id to cancel.' This implies alternatives (subscribe/unsubscribe) and provides clear context, making it easy for an agent to decide 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?

The disclosure goes well beyond annotations: it mentions rate-limiting (5 per identifier per day), the claim_token flow when no account is present, the ability to pass the token back later to read whether it was fixed, and that the team reads digests daily. It also states it is free and doesn't count against quota, all valuable operational context.

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

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

The description is dense but every sentence earns its place: purpose, usage triggers, exclusions, token flow, rate limit, and quota note. It is front-loaded with the core purpose and then layers necessary details without fluff or repetition of schema content.

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

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

For a 4-parameter tool with one nested object and no output schema, the description covers the critical behaviors: what feedback types are valid, how to report correctly, what happens when filing without an account (claim_token), and how to check resolution later. It also explains the team's daily review process and rate limits, making the tool's behavior fully understandable without an 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?

The input schema already covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds meaning beyond the schema by explaining the claim_token lifecycle (returns it without account, can be passed back later to read resolution) and clarifying that context is optional structured context. However, most parameter semantics are already 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 uses a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates feedback types (bug, feature, data_gap, praise) and distinguishes this tool from siblings like ask_pipeworx or discover_tools by focusing on reporting issues directly to the Pipeworx team.

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: use for wrong/stale data, missing tools/data, or praise. It also provides a clear when-not-to-use rule: only for tools served by this Pipeworx connection, and explicitly directs users to file with another MCP server if the tool came from elsewhere. It further advises not to paste end-user prompts, adding practical context.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond this: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window' disclose data source, privacy, and caching behavior. It doesn't describe failure modes or exact response structure, but the additional context is solid.

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

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

The description is concise and front-loaded: the first sentence immediately states what the tool returns, the second lists specific use cases, and the third delivers key caveats. Every sentence earns its place with zero fluff 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 one-parameter read-only tool with strong annotations and a full schema, the description is complete. It covers output contents ('top tools, top packs, total call volume', 'pack, tool, count'), caching behavior, data source, privacy (no PII), and use cases. The absence of an output schema is compensated by the explicit enumeration of returned data.

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 the 'window' parameter with enum values and explains short vs. long windows. The description adds marginal value by restating windows in the first sentence and contributing the novel insight that caching varies by window ('Cached 5min-1h depending on window'). Since schema coverage is 100%, the baseline is 3, and this extra nuance raises it to 4.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It distinguishes itself from siblings like discover_tools by focusing on aggregate usage signals from other AI agents, not static capability discovery.

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

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

The description provides explicit use cases via 'Useful for: (1) ... (2) ... (3) ...', guiding when to invoke the tool for trend discovery, canonical tool confirmation, and alignment checks. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a full 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral traits: the semantic anchor (Jaccard ≥0.30), partition filter placeholder rules, and the fill check limitation that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' This adds substantial context about failure modes and expected behavior 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 long but every sentence is purposeful. It uses clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the primary purpose. The density is justified by the tool's complexity; 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 no output schema, the description compensates by outlining the response structure (opportunities[], partition_check fields) and explaining edge cases like skipped_low_similarity and placeholder fractions. It covers all parameters, usage modes, and real-world constraints, making it fully 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?

Although the schema already covers both parameters, the description enriches them with concrete examples ('fed-decision-may-2026', 'when-will-bitcoin-hit-150k'), explains what happens with no args, and details the internal workflow (walking child markets, flattening, union comparator). This is far 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings like polymarket_edges by focusing on arbitrage across related markets, and details the three invocation modes (no args, event, topic). This is a textbook example of purpose clarity.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'pass event for a specific market', 'topic for cross-event scanning.' It also provides decision guidance (event recommended for specific markets) and cross-references polymarket_fill_risk for custom sizing, effectively differentiating from 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?

Beyond the read-only annotations, it discloses caching behavior (1h KV cache), response structure with diagnostics, the exclusion and unreliability of Fed bets, and a warning when a 24h move may have already absorbed the edge. It also notes historical parameter changes, adding rich context.

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

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

The description is a dense, single-paragraph wall of text with no bullets or sections. It is front-loaded with the purpose and every detail is relevant, but the lack of structure and length make it harder to parse.

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

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

With no output schema, the description thoroughly specifies the response structure (by_segment, fed_note, diagnostics) and explains when and why segments may be empty. It covers caching, filtering knobs, model behavior, and execution caveats, making it complete for correct invocation and interpretation.

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

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

With 100% schema coverage, baseline is 3, but the description adds meaningful interactions: e.g., why min_kelly does not filter partition arbs and how min_partition_leg_kelly addresses per-leg Kelly. It also provides real-world slippage/liquidity context beyond the 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 first sentence clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly frames the use case ('what should I bet on today') and enumerates three distinct model families, making it distinct from generic market scanning 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 clearly states the intended use case ('built for what should I bet on today') and provides detailed guidance on tradeable-edge knobs and filtering. It does not explicitly name alternatives or exclusions among sibling tools, but it makes the primary context obvious.

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, and non-destructive behavior. The description adds significant behavioral context: snapshot TTL limits history, snapshots are written on cache-miss, gaps mean no scan, and decay is computed from daily closes of edge_pp_net. This goes beyond the annotations and provides real operational insight.

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

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

The description is well-structured with clear sections for purpose, args, response, and limitations. Every sentence adds useful information, and the formatting makes it easy to scan even though it is lengthy.

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 must explain return values and does so thoroughly: tracked[], expired[], snapshot_dates[], and their interpretations. It also covers limitations like TTL and calculation methodology, making the tool fully usable without additional research.

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

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

The schema covers 100% of parameters with descriptions. The description repeats defaults and adds the 'snapshot family' concept, but does not significantly extend the schema's meaning. Baseline is appropriate since schema already handles 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's purpose: tracking edge persistence and decay from daily snapshots, answering whether an edge is new or shrinking. It distinguishes from siblings like polymarket_edges by focusing on historical telemetry rather than current edges.

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

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

The description provides strong contextual guidance, explaining that a 3-week-old edge is a different trade than a fresh one, which implies when to use this tool. However, it does not explicitly name alternative tools or state exclusions, so it stops short of perfect guidance.

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

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

Beyond annotations (readOnlyHint, idempotent, non-destructive), the disclosure adds critical behavioral traits: it walks the order-book ladder, computes slippage, and warns about partial fills converting an arb into unhedged directional risk. It even names the dominant loss mode, giving the agent a strong safety picture.

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 long, but every sentence contributes: it uses uppercase mode labels (SINGLE-MARKET, BASKET) to structure content and packs essential output fields and warnings. It is not overly verbose for the tool's complexity, though it could be trimmed slightly without losing meaning.

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. It lists all key outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc.) and adds risk context. This is complete enough for an agent to invoke the tool properly.

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

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

Schema covers all parameters with full descriptions, so baseline is 3. The description adds extra value by clarifying that exactly one of `market` or `event` is required, and by explaining how size_usd is interpreted differently in single-market vs basket mode (max spend vs settlement notional). This goes beyond the schema's room-level detail.

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 ('checks realizable-vs-theoretical edge against live CLOB order-book depth') and resource, making it clear what the tool does. It also distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by explicitly targeting fill risk rather than theoretical edge.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also describes when to use single-market vs basket mode and warns against relying on thin books, offering a clear decision framework.

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 annotations already declaring read-only and non-destructive behavior, the description adds substantial behavioral context: compatibility_warning conditions (bet-shape equivalence, unrelated events), temporal_alignment semantics, and skipped_cross_type/subtype counters. This goes far beyond what annotations alone provided.

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 well-structured with uppercase headings (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every section carries necessary caveats and field explanations, though it could be slightly tighter without losing 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?

No output schema exists, so the description compensates by specifying the response structure (leg-by-leg prices, matched spread[].top_spreads_pp) and all safety fields. It covers input modes, output, and edge-case warnings comprehensively for a tool of this complexity.

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

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

With 100% schema coverage, the baseline is 3, but the description adds significant meaning: it explains that 'topic' auto-fetches matching events, that explicit params override topic-mapped sides, and the interaction between the three params. It also lists all 10 pre-mapped topics, exceeding the schema's terse descriptions.

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

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

The description clearly states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling Polymarket tools by focusing on cross-venue comparison rather than single-venue analysis, and the scope is specific with modes and safety fields.

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

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

The description explains two explicit usage modes: topic shortcuts vs explicit ticker/slug pairings, and when each is appropriate. It also warns that most pre-mapped topics return compatibility_warning, but does not explicitly name alternative tools or state when NOT to use this tool relative to siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the read-only safety profile. The description adds valuable context about scoping ('Scoped to your identifier...') and the dual-mode behavior (retrieve vs. list), which goes beyond the structured 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?

Three sentences, each earning its place: the core action, the use case, and scoping/pairing relationship. It is front-loaded with the action, concise, and free of 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?

For a simple, single-optional-parameter read-only tool with strong annotations, the description covers both modes, identifier scoping, and linkage to remember/forget. No output schema, but the return behavior is simple and adequately implied.

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

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

The schema provides 100% parameter coverage, and the description reinforces the omission behavior ('omit the key argument') for listing. It adds semantic richness with examples of typical stored values (target ticker, address, research notes), helping the agent understand the key's meaning and usage.

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

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

The description uses a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from siblings by explicitly referencing remember and forget, making the tool's role in the memory workflow unambiguous.

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

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

It explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names complementary tools and the workflow: 'Pair with remember to save, forget to delete.' This provides clear context and alternative actions.

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 contradicts the annotation readOnlyHint=true by stating 'Set mark_read:true to flag returned events read', which is a write operation. This is a clear annotation contradiction, so the description earns the minimum score per the rubric.

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 information-dense but every sentence earns its place: main purpose, return content, filtering, mark_read side effect, polling note, and alternative endpoint. It is front-loaded with the core function and avoids 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?

With no output schema, the description compensates by detailing what each alert carries (source, citation_uri, raw payload). It covers filtering, side effects, polling, and an alternative access method. Despite the annotation contradiction, the description itself is thorough for a read-heavy tool with 5 parameters and no required ones.

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, but the description adds meaningful context beyond the schema: it explains the effect of mark_read ('so the next call only shows newer ones') and gives a concrete type example. This elevates 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 specific action 'Pull fired events from your subscription feed', identifying both the verb and resource. It mentions filtering by type and since, and marks the feed as persisted, distinguishing it from siblings like list_subscriptions or recent_changes by focusing on fired alerts.

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

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

The description provides clear context for when to use the tool: pulling fired events, filtering, and marking read. It also mentions polling works fine and provides an alternative HTTP endpoint, giving practical usage guidance. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail: it describes the fan-out to SEC EDGAR, GDELT→GNews fallback with specific conditions (rate-limited or 5xx), USPTO with PatentsView sunset caveat, and the return structure (changes[] grouped by source, total_changes, citation URIs). This far exceeds the minimum needed and is consistent with annotations.

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

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

The description is dense but every sentence carries useful info: example queries, source list, fallback logic, parameter guidance, return format, and sibling pointer. It is front-loaded with user-facing phrases. However, it is a bit long and could be trimmed without losing value, so not a perfect 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?

For a complex tool with no output schema, the description covers all necessary aspects: what sources are involved, fallback behavior, time window formats, return value structure, and a pointer to an alternative tool. It is sufficiently complete for an agent to select and 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 coverage is 100%, so baseline is 3. The description adds extra depth beyond the schema: it explains the 'since' parameter with both ISO and relative shorthand examples, and recommends '30d' or '1m' for typical monitoring. It also clarifies that 'value' can be a ticker or zero-padded CIK, reinforcing the schema but with added context. This is more than minimal but not exhaustive.

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: it provides a change feed for a company over a time window, with example queries ('What's new with X', 'latest on Y') that immediately convey intent. It also distinguishes itself from sibling entity_profile by explicitly stating when to use that alternative 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?

The description gives explicit usage context: it lists typical queries, explains the parallel fan-out across sources, and provides a clear exclusion: 'Use entity_profile instead when you want the static profile... regardless of window.' This is a strong when-to-use vs alternative 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 declare idempotentHint=true and destructiveHint=false, so the description doesn't need to state these. It adds value by disclosing scoping ('by your identifier') and persistence semantics (authenticated persistent vs anonymous 24-hour retention), which enriches the agent's mental model 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?

Three sentences, front-loaded with the core action, no filler. Each sentence adds essential information: purpose, use case, and lifecycle details.

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

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

For a simple 2-parameter tool with full schema and annotations, the description covers the full lifecycle (save, scope, retention, related tools). No gaps remain for an agent to decide when and how to invoke it.

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 fully describes both parameters (key and value) with examples and type details. The description only restates the key-value pair concept without adding extra syntax or formatting details, so it stays at the baseline for full schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Save') and resource ('data the agent will need to reuse later'), and explicitly distinguishes it from siblings via 'Pair with recall to retrieve later, forget to delete.' Concrete examples (ticker, address, preference) reinforce clarity.

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

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

It provides explicit guidance on when to use ('Use when you discover something worth carrying forward...') and distinguishes from alternatives by naming recall (retrieve) and forget (delete). This is clear contextual direction.

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 significantly adds to annotations by detailing internal cascading behavior, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR still returns), output structure (source-labelled identifiers, unresolved listed explicitly), and special handling of ISINs. This goes well beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is front-loaded with a clear purpose statement and example queries, but it is overly verbose with multiple paragraphs and detailed internal logic. While every sentence adds value, the length could overwhelm an agent, making it less concise than ideal.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description is exceptionally complete. It covers input variations, resolution behavior, output format (source-labelled, unresolved list), and failure modes. An agent can fully understand what to expect without needing to infer from the 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?

The description adds rich meaning beyond the schema, explaining what 'company' resolution includes (CIK, ticker, LEI, FIGI, ownership) and what 'drug' returns (RxCUI, ingredient, brand). It also expands the 'value' parameter by listing acceptable inputs (ticker, CIK, ISIN, name for company; brand/generic name for drug), which is not in the schema 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 resolves names to canonical identifiers, with a specific verb ('resolve') and resource ('names to identifiers'). It distinguishes from siblings by positioning itself as a prerequisite ('Use FIRST whenever you have a name but need an ID'), implicitly setting it apart from tools like entity_profile that likely operate on already-resolved 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 'Use FIRST whenever you have a name but need an ID', providing a clear when-to-use directive. It also notes that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use it or directly compare to alternatives like entity_profile, leaving a small gap.

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 known. The description adds valuable behavioral detail: it states the tool probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loading the purpose, then method, use case, and return value. Every sentence contributes new information with no fluff or repetition. It is concise yet comprehensive.

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 compensates by explicitly stating the return format ('ranked list with score, confidence, signal density per entity'). It covers the purpose, methodology, and use case. With annotations covering safety and schema covering parameters, the description is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already explains all four parameters, including the special role of the first entity. The description adds minimal extra meaning beyond what the schema provides, so a 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 a specific action ('Compare AI visibility across multiple entities side-by-side') and differentiates from the sibling tool ai_visibility_check by explaining that it probes each entity with that tool and ranks results. It identifies the resource (AI visibility) and the comparative scope, leaving no ambiguity.

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 a concrete use case ('competitive AI-marketing audits') with an example question, giving clear context for when to use this tool. It does not explicitly mention alternatives or exclusions, but the scenario is distinct enough to guide selection. A score of 4 is appropriate because while the context is clear, it does not reference when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that: 'Partial failures degrade gracefully', notes that 'bundlephobia's first measurement on a new version can take 5-30s', and explains that sources_failed will list timeout cases. This informs the agent about latency and resilience 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?

Though lengthy, the description is efficiently structured: it opens with the core purpose, then gives when-to-use, a compact bullet-like list of returned fields, ecosystem scope, and failure behavior. Every sentence adds necessary detail for a composite tool, 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 the tool's complexity (composite, multiple data sources, no output schema), the description fully covers return values (summary block fields, per-advisory detail, links, alternatives), partial failure modes, and ecosystem limitations. No critical operational detail 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 description coverage is 100%, and the description restates what the schema already covers (e.g., defaults to latest version when omitted, scoped packages accepted). It does not add meaning beyond the schema, so a 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 verb ('check') and resource ('npm package'), and differentiates it from siblings by describing it as a 'composite' check that fans out across multiple data sources. It explicitly mentions deps.dev and bundlephobia, making its scope obvious.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a clear exclusion ('NPM ecosystem only in v1') and directs to an alternative ('fall under deps.dev:version directly').

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 minimal behavioral context, noting the comments are public and showing an example document ID. It does not explain pagination, result limits, or how filters interact, but the annotations lower the burden.

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, compact sentence that front-loads the main purpose and includes a helpful example. No wasted words.

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

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

With 7 optional parameters and an output schema, the description gives a high-level overview but does not explain how filters combine (e.g., docket_id vs document_id) or provide guidance on result handling. The example is useful, but the interaction between filters is left to schema inference.

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 value by providing a concrete document ID format example and grouping filters into free-text and date categories, which helps clarify parameter usage beyond the schema's individual 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 identifies the resource as 'public comments' and indicates the tool filters by docket, document, free-text, or date. It is clear this is a search tool, but it does not explicitly distinguish it from sibling tools like get_comment, so it lacks sibling differentiation.

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

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

The description implies usage by listing filter criteria and providing an example, but it does not explicitly state when to use this tool over alternatives or mention exclusions. The guidance is implied rather than directly stated.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by enumerating filter types and the exact fields returned (title, agency, type, status, document counts), which supplements the annotations without contradicting them.

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

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

Two concise sentences, front-loaded with the core action, and then dense with relevant details about filters and returns. No redundant phrases 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?

With a rich output schema and full parameter documentation, this description covers the essential purpose, filters, and return shape adequately. It does not mention open-world behavior or pagination, but those are either annotated or captured by the schema, so the overall context is sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters. The description restates agency and docket_type semantics but does not add meaningful detail beyond the schema, such as pagination behavior or date format specifics.

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

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

The description uses a specific verb ('Search') and resource ('regulatory dockets'), followed by concrete filtering dimensions and return fields. It clearly distinguishes from sibling tools like search_comments and get_docket by targeting dockets specifically.

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

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

The description clearly indicates this is for searching regulatory dockets with optional filters, giving a clear use context. However, it does not explicitly state when to prefer this over search_comments or search_within, so no exclusions or alternatives are mentioned.

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

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

Annotations already cover read-only/open-world/idempotent, so the description adds beneficial technical context: embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and hard limit (200K chars with truncation flag). This goes beyond structured data and sets clear expectations.

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, then expands with use case, pairing, and technical details. Every sentence earns its place; it is dense but not verbose. Structure is logical and 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 tool with no output schema, the description adequately covers return values (top-N passages with offsets and similarity scores), input constraints, and failure behavior (truncation flag). It also explains the integration with ask_pipeworx_grounded. The tool is fully comprehensible from the description alone.

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 provides 100% parameter coverage with descriptions for text, limit, and query. The description adds useful examples ('SEC 10-K body, article') and clarifies the 'too big to cram' use case, but does not fundamentally deepen each parameter's semantics beyond the schema. Slight enrichment justifies a 4.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes itself from sibling tools by focusing on searching within already-pulled text, and further differentiates by pairing with ask_pipeworx_grounded rather than replacing it.

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

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

Provides explicit 'Use when' guidance (record too big for prompt), explains the value proposition (saves context, returns only relevant passages, offsets for verification), and names a complementary tool (ask_pipeworx_grounded) with a suggested workflow. This is actionable and context-rich.

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:false, idempotentHint:true, openWorldHint:true, destructiveHint:false) indicate a non-read, non-destructive, state-changing operation. The description adds valuable context: persistent subscription requirement, phone verification, SMS cap, and the feed being always-on. These behavioral details go beyond what annotations alone convey.

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

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

The description is a single well-organized paragraph that front-loads the purpose, then covers requirements, supported types, and delivery channels. Every sentence carries needed information without fluff or repetition, achieving high information density while remaining readable.

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

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

The tool has 3 params with nested objects and no output schema. The description covers return value (subscription id), auth requirements, delivery options, and examples. However, it omits the webhook delivery channel (though the schema covers it), and doesn't explain behavior on duplicate subscriptions. Still, for the complexity, it's fairly 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?

Input schema has 100% coverage with detailed per-parameter descriptions. The description adds extra semantic meaning beyond the schema, such as interpreting 'items:["5.02"]' as 'officer change' and giving concrete examples for each subscription type, which helps the agent choose proper 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 clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb (Create) and resource (subscription to a live-data event stream), and distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and returning the new subscription id.

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

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

The description provides clear usage context: it requires a Pipeworx OAuth account (anonymous + BYO cannot persist), explains how to consume alerts via the feed or recent_alerts, and notes SMS verification and caps. It doesn't explicitly say 'when not to use' or name alternatives, but the context makes the intended use 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 declare read-only, idempotent, non-destructive. The description adds that it draws from the live catalog, returns category-bucketed questions, and supports optional topic filtering—valuable context beyond 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?

Single well-structured paragraph front-loads example queries and states purpose immediately. While long, every sentence conveys useful information about response format, call variations, and usage guidance; no filler.

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

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

No output schema, so description must explain return value—it does, detailing category-bucketed example questions with tool and argument shape. It also covers optional topic and links to meta-tools, making it complete for an agent's decision.

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 describes topic with a full list of enum-like values and omit behavior. Description only adds a few examples ('finance', 'pharma', 'betting') without new semantics; schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description states the tool returns category-bucketed example questions with the exact tool and argument shape, serving as the onboarding entry point. It clearly distinguishes from siblings like ask_pipeworx and discover_tools by positioning it as the first step to learn what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and explains how to call with or without a topic. It also mentions learning to call meta-tools, giving clear context for when to use it versus alternatives.

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

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

The description goes beyond annotations by explaining that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. This adds valuable behavioral context that annotations (idempotentHint, destructiveHint) do not fully capture.

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

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

The description is concise, with two sentences that front-load the core action and follow with important details. No wasted words.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description fully covers the needed context: ownership enforcement, deactivation vs deletion, and the impact on historical events. Nothing critical 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% with the parameter already described as 'Subscription id (uuid) returned by subscribe.' The description adds no additional meaning beyond that, 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 cancels a subscription by ID, using a specific verb and resource. It also distinguishes itself from siblings like subscribe and recent_alerts by noting the deactivation behavior.

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

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

The description implicitly indicates when to use the tool (when you want to cancel a subscription) and enforces ownership ('you can only cancel your own subscriptions'). It doesn't explicitly mention alternatives or exclusions, but for a simple cancellations tool, the context is sufficient.

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

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

Annotations already provide readOnlyHint/openWorldHint/idempotentHint, and the description adds valuable behavioral nuance: the dual fast-path vs. grounded pipeline, the exact verdict taxonomy, and critically the semantics of could_not_verify (with verification_error) and unsupported, including the warning not to show could_not_verify as evidence. 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 long but every sentence carries operational information, from usage trigger to routing to return semantics. It is front-loaded with purpose, then systematically covers error handling. Slightly verbose but justified by the tool's complexity; no redundant 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?

Despite no output schema, the description fully explains return values (verdict types, actual value with citation, reasoning) and error states (could_not_verify, unsupported). It covers the two main routing tracks and the caller-facing implications, making the tool self-contained for an agent. Sibling context not 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 description coverage is 100%, but the description adds extra meaning for tolerance_pct: it explains how to use it for hallucination detection (set 1–2) and that the default is implied by claim wording. It also gives realistic examples for claim, enhancing the schema. This exceeds the baseline for fully described 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 clearly states a specific verb+resource: 'natural-language claim verification against authoritative sources' and is explicit that it checks whether something a user said is factually correct. It distinguishes itself from sibling tools by detailing the claim-verification workflow and noting it 'Replaces 4–6 sequential calls.'

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

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

The tool instructs 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear context. It also explains the routing rule: company-financial claims go through SEC EDGAR/XBRL, any other factual claim falls through to grounded pipeline. It does not explicitly name alternative tools for non-claim queries, but the context is sufficient.

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