Govinfo

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds meaningful behavioral context: the default free Workers AI model, the BYO-Key direct-billing mechanism for Anthropic, and the exact return shape (per-model {score, confidence, signals, raw_response} + combined view). This goes beyond the annotations and is genuinely helpful.

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, then covering default model, key handling, return format, and use cases. Every sentence earns its place with no 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?

Despite lacking an output schema, the description specifies the return payload structure and lists realistic use cases. It covers the key nuances (free vs BYO, multi-model probing) sufficiently for a read-only tool with 4 parameters. Minor unclarified terms like 'signals' do not hinder understanding.

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 semantics by explaining that omitting `models` uses the free default and that `_apiKey` is only needed for Anthropic with direct cost implications, which is not fully captured in the schema. This added context 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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools by focusing on AI visibility scoring for marketing audits and brand checks, not generic questions or deep research.

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 provides use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional Anthropic model and BYO key. It doesn't name alternatives or when-not-to-use, but the context is strong enough for an agent to select this tool appropriately.

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 non-destructive behavior. The description adds valuable behavioral context beyond that: it routes to 5,529 tools across 1,455 sources, returns stable citation URIs, and works on every tier with 'one fast call'. This enriches the agent's understanding without contradicting annotations.

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

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

The description is longer than average but front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH'). It is well-structured with examples and escalation paths, and every sentence serves a purpose. Slightly verbose, but the density of information justifies the length.

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

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

For a routing tool without an output schema, the description is remarkably complete. It covers what the tool does, when to use it, when to escalate, what types of questions to ask, and what the response will contain (structured answer with citations). This is more than sufficient given the moderate complexity.

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

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

The input schema already provides 100% coverage with descriptions for each alias, so the baseline is 3. The description adds meaning through example questions and explains that the parameter accepts natural language requests, clarifying the expected format and scope beyond the schema's terse 'Your question or request'.

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

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

The description clearly states the tool's function: it routes questions to authoritative data sources and returns structured answers with citations. It uses a specific verb ('ask') and identifies the resource (Pipeworx), while distinguishing itself from siblings like ask_pipeworx_grounded and deep_research by emphasizing it is the default entry point for most factual questions.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', providing clear when-to-use guidance. It also names alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions) and gives concrete examples, making the appropriate context unmistakable.

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, non-destructive, idempotent, and open-world hints. The description adds valuable context about the beta status, the live testing of candidate routing improvements, the retirement of the last candidate, and that it is a full working router with 'experimental edge.' It 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 with the most important fact ('Beta version of ask_pipeworx') leading. Each sentence adds relevant context: identity, current state, and usage instruction. Slight redundancy in clarifying it is a full working router, but overall 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 tool's complexity and the absence of an output schema, the description covers key aspects: what the tool is, its relationship to ask_pipeworx, the current candidate status, and the response shape. It does not detail return values in depth, but 'same response shape' suffices. It is complete enough for an agent to decide and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question.' The description only says 'same arguments' without adding further meaning, so it does not compensate beyond what the schema already provides. 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 specifies this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and response shape, and explicitly distinguishes it from the stable ask_pipeworx. It clearly identifies the tool's purpose and its unique experimental role.

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

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

It states exactly when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide what merges, and notes the current state (no candidate active), giving clear context and alternative comparison.

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

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

The description goes well beyond annotations by disclosing that it uses 'ONLY what the tool result contains,' details the success response structure with evidence and refusal_reason:null, and enumerates explicit refusal reasons (not_in_source, no_tool_match, etc.). It also notes the one extra LLM call cost. This rich behavioral context fully complements the readOnlyHint and idempotentHint annotations without contradiction.

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

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

The description is front-loaded with the core purpose, then provides essential behavioral details and usage guidance in three dense sentences. Every sentence carries value—no filler, and the structure supports quick comprehension.

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 fully explaining both success and refusal return structures. It also covers routing scale, the extraction guarantee, and cost implications, making the tool wholly understandable and actionable.

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% (complete aliases for 'question' are documented). The description adds no additional parameter semantics, but the schema already fully explains the parameters, 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 identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and details its process (same routing as ask_pipeworx, then extracts answer only from tool result). It differentiates from the sibling ask_pipeworx by noting the extra LLM call and preferred use cases, making the purpose unmistakable.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also says when not to use: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff. This is strong guidance 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?

Despite the readOnly/openWorld/idempotent annotations, the description discloses extensive behavioral traits: parallel fan-out, classifier list, resolver confidence contract, blocking low-confidence/closed-market statuses, news fallback behavior, and cancellation-rule risk. This substantially exceeds the information provided by annotations.

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

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

The description is long but front-loaded and highly structured with labeled sections, examples, and enumerations. Each section adds non-redundant information, though some fan-out examples could be trimmed without losing essential guidance.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does so comprehensively, covering response shapes, resolver contracts, parent-event extraction, news fields, safety statuses, and cancellation-rule risk — a complete operational picture.

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

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

The schema already covers all three parameters, and the description adds practical semantics: accepted forms for 'market', quick vs thorough depth behavior, and when to set include_raw. It doesn't fully enumerate all output implications per parameter, but it adds meaningful value beyond the schema.

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

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

The first sentence states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' — a specific verb and resource. The description adds concrete use cases ('should I bet on X') and response-shape details that distinguish it from sibling tools like polymarket_arbitrage or validate_claim.

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 trigger phrases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and detailed input-form instructions are provided. It does not name specific alternative tools to use instead, but the context is clear enough to know 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 description goes far beyond the annotations by detailing data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling (AAPL Sep, NVDA Jan), field specifics (revenue, net income, cash, debt), sorting behavior, and citation URIs. This rich context is not present in annotations and substantially aids correct invocation.

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 long, every sentence carries unique value: trigger phrases, preference rule, data sources, sorting, citations, and efficiency gain. The content is front-loaded with examples and structured around key details, with no fluff or redundancy. The length is justified by the tool's complexity.

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

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

The description fully covers the tool's behavior for both entity types, explains the results format (paired data + citation URIs), states the count limits (2–5), and gives performance context. With schema and annotations covering the rest, nothing critical is missing 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 already covers parameters well, but the description adds crucial meaning: type='company' pulls specific financial fields, while type='drug' pulls FAERS/trial counts. It also clarifies the 'values' array meaning (tickers vs drug names, 2–5 items) with examples, enriching what the schema provides.

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

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

The description clearly states a specific verb ('compare') and resource (companies/drugs) with explicit scope ('side-by-side comparison of 2–5 companies or drugs'). It distinguishes from sibling tools by emphasizing 'ONE parallel call' vs sequential lookups, and the trigger phrases make the purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists concrete trigger phrases ('X vs Y', 'rank these companies') and contrasts with the 8–15 sequential lookups it replaces, giving clear decision criteria 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?

Despite annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, the description adds substantial behavioral context: account requirements/sign-in, the parallel decomposition and routing approach, the never-invented guarantee with explicit gaps[], the difference between quick/standard/thorough behavior (hop and contradictions[]), the excerpting strategy for large records, and expected latency. It also explains the citation_uri resolvability guarantee. No contradiction with annotations; the description enriches 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 long but information-dense, with every sentence earning its place. It is front-loaded with the critical account requirement, then flows logically through use cases, behavior, depth semantics, and output details. Some redundancy exists (repeated mention of ask_pipeworx alternatives, contradictions[] described in two places), and the length could be tightened slightly, but the structure is clear 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 complex tool with no output schema, the description covers the essential context: prerequisites (account, paid tier for thorough), use cases, alternatives, behavior guarantees (gaps[], never invented), latency expectations, and output format semantics (hop field, citation_uri, contradictions[]). It even handles edge cases (breakting news returns empty gaps). Given the tool's complexity and the absence of an output schema, this is remarkably complete.

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

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

Schema coverage is 100% and both parameters have descriptions, so the baseline is 3. The description adds meaningful context beyond the schema: it explains how the 'question' parameter benefits from being broad/multi-part ('decomposition is the point'), and it clarifies the practical meaning of depth values ('quick=3', 'standard=5', 'thorough=8', paid plan, gap recovery) in more operational terms than the schema's enum descriptions. This nudges above baseline but doesn't fully redefine the 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 identifies the tool as a grounded multi-source research tool across 1455 structured data sources, distinguishes it from open-web search, and contrasts it with sibling ask_pipeworx. It specifies the resource (Pipeworx structured data), the action (decomposes question into facets, routes to tools in parallel), and the output (findings packet with evidence, confidence, source, citation). This strongly differentiates it from siblings like ask_pipeworx and bet_research.

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

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

The description explicitly states when to use this tool ('Best for broad/multi-part questions over structured data'), when NOT to use it ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and names the alternative (ask_pipeworx). It also explains depth-level usage (standard re-angles unanswered gaps, thorough chases leads) and warns about timing expectations. This is exemplary usage guidance.

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

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

Annotations already cover readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond annotations: it returns top-N tools with names, descriptions, and full input schemas, ready to call directly without a second schema lookup. No contradiction with annotations.

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

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

The description is well-structured with three sentences: purpose, when to use, and return behavior. It front-loads the core action, uses a colon list for categories, and every sentence earns its place. No redundant wording.

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?

Although there is no output schema, the description clearly explains what the tool returns (names, descriptions, schemas, curated examples) and that results are directly callable. For a discovery tool with a simple query input, the description is complete and self-sufficient.

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

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

The input schema has 100% parameter description coverage, including aliases and default/max for limit. The description does not add additional parameter-level meaning; it merely reinforces the query semantics. Baseline 3 is appropriate since the schema carries the full burden.

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 'Find tools by describing the data or task' with a specific verb and resource, and distinguishes this meta-discovery tool from siblings by listing diverse domains it covers. It avoids tautology and provides concrete examples of tool categories.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and includes 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance and implicitly contrasts with directly invoking a known 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses parallel execution, multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), a known failure mode (USPTO patents API sunset May 2025 soft-fail), a fallback chain (GDELT→GNews), and exact return structure (CIK, up to 5 filings with URIs, latest 10-K metrics). 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?

Though long, every sentence earns its place. The core purpose is front-loaded, followed by return structure, examples, and edge cases. The dense formatting (semicolon-separated key returns) keeps it readable while maximizing information density.

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 enumerates every output component, lists constraints (US public company, ticker/CIK only), mentions a soft-fail behavior, and provides a fallback news source. Coverage is thorough for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds essential context beyond the schema: ticker vs zero-padded CIK, the fact that names are not supported, and the explicit pointer to resolve_entity as an alternative. This meaningfully enhances the agent's ability to correctly populate the 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 opens with 'full cross-source profile of a US public company in ONE parallel call,' which is a specific verb+resource statement. It also explicitly differentiates from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.'

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

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

Provides explicit when-to-use guidance ('ALWAYS PREFER...') and when-not-to-use ('names not supported — use resolve_entity first if you only have a name'). This clearly distinguishes from alternatives and tells the agent exactly when to invoke the tool.

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

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

Annotations already indicate destructive and idempotent behavior, and the description reinforces this with 'Delete' and 'clear sensitive data'. It adds context about appropriate usage scenarios, which goes beyond the raw annotations. No contradictions found.

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, highly concise, and front-loaded with the primary action. Every sentence contributes: the first states what it does, the second explains when and how it relates to other tools. No wasted words.

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

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

For a simple, single-parameter tool with no output schema and clear annotations, the description provides sufficient context: purpose, usage scenarios, and linkage to sibling tools. There are no obvious gaps that would confuse 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?

The input schema fully describes the single parameter 'key' with a clear description ('Memory key to delete') and coverage is 100%. The description merely repeats 'by key' without adding additional semantics, so the schema carries the informational burden.

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 ('Delete') and resource ('a previously stored memory by key'). It differentiates from sibling tools like remember and recall by focusing on deletion, 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?

It explicitly specifies when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. This provides clear situational guidance and even mentions pairing with remember and recall, which helps the agent understand the tool's role within the memory workflow.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds process transparency by explaining it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'. This goes beyond the annotations and helps the agent understand the tool's 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 three sentences, front-loaded with the core action, and includes a 'Useful for' list that is scannable. Every sentence adds value: purpose, process/output, and use cases. No filler or redundancy.

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

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

For a tool with only 2 parameters, no output schema, and strong annotations, the description is complete. It covers the workflow, output format, and practical use cases. The absence of error-handling details is acceptable given the tool's simplicity and the fact that annotations cover the read-only, idempotent nature.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the URL parameter implicitly ('for any URL') and refers to 'key links' (which maps to max_links conceptually), but it doesn't add detail about parameter types or defaults beyond what the schema already provides. It neither enhances nor harms parameter understanding.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL'. It specifies the exact output (a text blob for site-root/llms.txt) and differentiates from sibling tools by focusing on generation rather than scanning or checking AI presence. The verb 'Generate' plus the resource 'llms.txt file' makes 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 description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') and implies when to use it. However, it does not explicitly mention alternatives or when not to use it, so it lacks the 'when-not' guidance that would earn a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations by naming the 'GovInfo summary endpoint' and listing the returned fields ('title, class, and provenance'), which helps the agent set expectations without over-explaining.

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

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

The description is two sentences, front-loaded with the main action and scope, then efficiently details the inputs and return fields. No wasted words; every sentence contributes.

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 read-only tool with an output schema and strong annotations. The description covers the purpose, input provenance, and return fields, and no additional context (e.g., error behavior, rate limits) is necessary for correct agent usage.

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

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

The schema covers 100% of parameters with basic descriptions ('Granule ID', 'GovInfo packageId'), but the description adds meaningful context by stating both are 'from list_granules', clarifying where the agent should obtain these IDs. This enriches the bare schema info.

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 ('Fetch') and resource ('summary metadata for a single granule within a GovInfo package'), clearly distinguishing it from sibling tools like get_package or list_granules. It also specifies the return fields ('title, class, and provenance'), making the scope 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 explains that both package_id and granule_id should come from list_granules, establishing a clear workflow and context for when this tool should be used. It does not explicitly state when not to use it, but this is a minor gap since the workflow guidance 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral context by enumerating the returned data (title, dates, citations, granule count, download links). 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 two sentences, front-loaded with the core purpose, and then lists return items succinctly. Every word earns its place; no fluff or repetition.

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

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

With a single parameter, full schema coverage, an output schema present, and comprehensive read-only/idempotent annotations, the description is complete for the tool's simplicity. It covers the operation, input examples, and output highlights, leaving no critical gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples of valid package_id formats ('BILLS-118hr1234ih', 'FR-2024-05-12'), which clarifies the expected string format beyond the schema's generic 'GovInfo packageId'.

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 specifies a clear verb+resource: 'Metadata for a single package by packageId', and distinguishes from siblings like get_granule (granules) and search_packages (search). Concrete examples of package IDs further clarify the target 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 phrase 'for a single package by packageId' establishes clear context for when to use this tool: when you have a specific package identifier and need its metadata. It does not explicitly name alternatives or exclusions, but the single-package focus implicitly distinguishes it from search/list 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 readOnly, openWorld, and idempotent hints, so the description needs only to add behavior not captured there. It adds that the tool returns package counts per collection and lists known collection codes, which is useful context beyond the annotations. 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 exactly two sentences; the first states the core function and the second provides an actionable cross-reference. No wasted words, with the action front-loaded.

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

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

Given the tool's low complexity (no parameters), rich annotations, and the presence of an output schema, the description covers all necessary aspects. It tells the agent what will be returned (package counts) and how to use the output in a downstream call.

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

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

The tool has zero parameters, so parameter semantics are a non-issue. The description correctly focuses on the tool's purpose and output, and with schema coverage of 100% (vacuously), there is nothing for the description to add about 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 uses a specific verb ('List') and identifies both the resource (GovInfo collections) and the distinguishing output ('with package counts'). It also enumerates example collection codes (BILLS, CFR, USCODE, FR, etc.), making the scope clear and differentiating it from sibling 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 explicitly instructs the agent to 'Use the collection code with search_packages to filter,' providing a direct cross-tool usage pattern. While it does not describe when to avoid this tool, the sibling context and the nature of the operation make the primary use case evident.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds context by explaining what granules are (with concrete examples) and specifying the return fields (granule IDs + titles). This goes beyond annotations by clarifying the output shape and the semantic meaning of the resource, though it does not describe pagination behavior or other edge cases.

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

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

The description consists of two concise sentences. The first sentence states the action and gives examples, the second summarizes the output. Every word carries meaning, and the structure is front-loaded with the core purpose.

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

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

Given the tool's moderate complexity, full parameter coverage in the schema, safety annotations, and the presence of an output schema (confirmed by context signals), the description is sufficient. It explains what granules are, what the tool returns, and the scoping constraint, leaving no major gaps for the agent to understand 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 input schema already provides 100% coverage for all parameters: package_id, page_size, and offset_mark each have descriptions. The tool description adds no parameter-specific details beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('List granules within a package') and provides concrete examples (sections of a CFR title, entries in a Federal Register issue) that distinguish it from sibling tools like get_granule (single granule) or get_package (package metadata). The verb 'list' and resource 'granules' are specific and 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 'within a package' and the examples imply that this tool is for enumerating granules given a known package ID, rather than searching across packages. However, it does not explicitly name alternatives or state when not to use it, such as when to use search_within or search_packages. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by specifying the scope ('caller's active subscriptions') and enumerating the returned fields (id, type, params, etc.), which is useful since there is no output schema. No contradictions.

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

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

The description is two sentences with no wasted words. It front-loads the main purpose, then provides return fields and usage guidance—everything listed earns its place.

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

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

Given that this is a simple list tool with one optional parameter and no output schema, the description fully covers what the tool returns, the scope of results, and when to use it. The sibling tools and annotations provide additional context 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?

The single parameter include_inactive is fully described in the schema (100% coverage), so the description doesn't need to add parameter details. The phrase 'active subscriptions' softly relates to the parameter but doesn't enrich the schema meaning beyond 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 'List the caller's active subscriptions', providing a specific verb and resource. It gives the return fields, but does not explicitly distinguish from sibling tools like subscribe/unsubscribe, though the read vs. write distinction is implicit.

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 offers clear context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use the tool but does not explicitly address when not to use it or name alternatives.

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

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

Annotations are all false, so the description carries the full behavioral burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token return flow ('Filing without an account returns a claim_token; pass it back later...'), and team response cadence ('team reads digests daily'). These go well beyond the minimal safety hints and set 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 dense but every sentence earns its place. It is front-loaded with the core purpose, then systematically covers when to use, exclusions, token flow, and operational facts. There is no redundant filler; the length is justified by the need to disambiguate from other servers and explain the claim_token workflow.

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

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

The description is comprehensive for a feedback tool with no output schema. It covers selection criteria, exclusions, input guidelines, claim_token return behavior, rate limit, and cost. The only minor gap is a full response structure specification, but since there is no output schema and the claim_token is mentioned, this is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage context beyond parameter descriptions: it explains how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), and instructs message content ('don't paste the end-user's prompt'). This extra guidance earns a 4, though the schema already defines the parameters clearly.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team/tools) and distinguishes from sibling research/discovery tools by focusing on feedback submission. The verb 'tell' and the enumerated feedback categories make 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 description gives explicit when-to-use guidance (bug, feature/data_gap, praise), a clear when-not-to-use exclusion (tools from other MCP servers), and a fallback heuristic ('Not sure? Pipeworx tool names are the ones this connection lists'). It also instructs how to frame feedback (in terms of Pipeworx tools/packs, not user prompts) and how to use claim_token later, providing complete operational guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. Description adds non-obvious context: self-aggregating signal from CF analytics-engine, no PII, and cache TTL varying by window. No contradiction.

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

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

Three sentences, front-loaded with purpose, then use cases, then technical caveat. 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?

For a simple read-only tool with one optional param and no output schema, the description covers what is returned (top tools, packs, call volume), data provenance, privacy, and caching. Sufficient for an agent to decide and call.

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

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

Schema coverage is 100% for the single window parameter, which already explains the enum and tradeoffs. Description only reiterates the values and adds a caching dependency, providing marginal added meaning. Baseline 3 applies.

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

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

Description clearly states the tool returns trending tool/pack usage and call volume, using specific verbs ('Returns') and naming the resource ('top tools, top packs, total call volume'). It differentiates from siblings like discover_tools by focusing on real-time agent usage signal.

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

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

Provides an explicit 'Useful for' list with three concrete scenarios, giving clear context for when to use. It does not name alternative tools or exclusions, but the use cases serve as strong 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/idempotent annotations, the description discloses many behavioral traits: the semantic anchor (Jaccard similarity ≥0.30), placeholder filtering (>20% yields null arb signal), fill-check logic (realizable_edge_pp ≤ 0 means don't trade), and output fields (skipped_low_similarity, thin_legs). No contradictions with annotations.

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

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

The description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and is front-loaded with the core purpose. Every sentence adds value, though some examples and parentheticals could be trimmed without losing function. Still, for the tool's complexity, the length is justified.

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

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

Given no output schema and only two optional parameters, the description fully compensates: it explains the response shape (opportunities[], partition_check), covers edge cases (placeholders, similarity filter, thin books), and signals when to use a related tool. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

Although the schema already documents both parameters, the description adds substantial meaning: what values are valid (event slugs, full URLs, seed questions), examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and the mode-specific behavior each parameter triggers. This goes far beyond the schema's simple property descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes two modes (event vs topic) and explicitly references sibling tools like polymarket_fill_risk for custom sizing, making the tool's scope distinct.

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

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

Provides explicit when-to-use guidance: call with no args for trending_scan, 'event' for a specific market, 'topic' for cross-event scanning. It also names an alternative tool ('For custom sizing use polymarket_fill_risk') and explains trade-offs like how cross-event mode catches date-pattern differences that single-event misses.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral context beyond that: caching behavior, slippage assumptions, diagnostics for why segments are empty, the rare-by-design nature of concentrated longshots, and the 24h-move warning. This fully discloses operational traits the agent needs to interpret results correctly.

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

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

The description is comprehensive but very long, with dense all-caps section headers. It is well-structured but not concise; every sentence carries information, but the length may overwhelm an agent trying to quickly parse the core purpose. It earns a middle score because structure compensates for verbosity.

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

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

No output schema is present, so the description carries the full burden of explaining return values — and it does so thoroughly, specifying top-level keys (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and even the diagnostic funnel counters. This is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description significantly enriches parameter meaning. For example, 'min_partition_leg_kelly' is clarified with why parent-level Kelly is zero by design, and 'slippage_pp' receives context about Polymarket's fee structure and typical spreads. 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 opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which is a specific verb+resource+scope statement. It further distinguishes itself by detailing three model families and response segments, making its purpose and unique value clear.

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

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

Explicitly states the intended use case ('what should I bet on today') and explains when knobs like min_liquidity and max_spread_pp should be applied. It also provides a 'when not to rely' note about Fed bets being unreliable. However, it does not explicitly name alternative sibling tools or provide exclusion criteria, so it stops 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?

Beyond the annotations (read-only, idempotent, open-world), the description discloses meaningful behavioral traits: the 60-day snapshot TTL limit, snapshot gaps due to cache-miss behavior, decay computed from daily closes rather than intraday data, and the signed nature of edge_pp_net. It also explains what occurs for expired opportunities. This adds considerable transparency 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 well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence adds functional value, from the core question to response field semantics to operational limits. It is dense but appropriately so for a tool with this complexity, and it remains readable and front-loaded.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), including field meanings, edge signing, and the significance of median lifespan. It also covers limitations (TTL, snapshot gaps, data resolution), making it fully self-contained for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with clear parameter descriptions, so the baseline is 3. The description adds a little context (e.g., 'snapshot family' for window, the fact that lookback defaults to 14 and max 30), but it mostly repeats what the schema already states. No significant new parameter meaning is provided beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates itself from the sibling polymarket_edges by focusing on historical persistence/decay rather than current edge values.

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

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

The description gives clear context for when to use this tool: when you need to understand edge persistence and decay over time. It even provides a trade example ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly name alternatives or state when NOT to use it, so it stops 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, so safety is covered. The description adds meaningful behavioral detail: it walks the order-book ladder, returns fill metrics, identifies 'thin_legs', and warns about forced_directional_risk. It does not contradict annotations and provides context about what the tool returns, though it does not mention latency or data freshness.

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 long, the description is tightly structured with clear mode sections (SINGLE-MARKET / BASKET), and every sentence contributes necessary operational detail or risk context. It is front-loaded with the core purpose and uses capitalization effectively for key terms. No filler or redundancy exists.

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

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

With no output schema, the description compensates by listing the key returned values for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict; for basket: theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk). It also covers prerequisites (market/event slug), defaults, and failure modes. The description is fully self-contained for a complex two-mode 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%, so the baseline is 3. The description goes beyond the schema by clarifying mode-specific behavior: 'size_usd' is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode; 'side' has an 'auto' default in basket mode based on partition sum. This adds real interpretive value beyond the property descriptions.

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

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

The description opens with a precise verb-object statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the two modes (single-market vs basket) and explicitly differentiates from siblings by tying to polymarket_arbitrage and polymarket_edges, so purpose and scope are 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 includes an explicit 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' instruction, explains why (partial basket fills convert arb into an unhedged directional position), and covers mode selection, defaults, and size_usd interpretation. This is ideal when-to-use guidance with rationale.

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 cover only generic read-only and idempotent hints. The description goes far beyond by detailing compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type counters. It discloses edge-case behaviors and what results mean, providing substantial 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 long but densely informative, structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. While a bit lengthy, every sentence contributes useful details; minor reorganization into bullets could improve scannability.

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 thoroughly explains the response format (leg-by-leg prices, spread in pp, compatibility_warning, temporal_alignment, skipped counters). It accounts for edge cases and the probabilistic nature of the data, making it 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 coverage is 100% with each parameter described. The description adds value by explaining the mode relationship: how 'topic' serves as a macro shortcut and how explicit tickers override mapped sides. This relational semantics is beyond raw schema definitions, though not deeply detailed.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This identifies the exact function and distinguishes it from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. The two-mode explanation further clarifies scope.

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

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

The description explicitly describes when to use the tool ('for the same resolving question'), explains both input modes, and provides clear when-not cases (e.g., 'when the bet shapes are not equivalent... no arb exists'). It also warns that pre-mapped topics often return compatibility warnings, setting concrete expectations.

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 idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the dual fetch-or-list behavior. 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?

Three sentences, each with a distinct purpose: operation, usage rationale, scoping/companion tools. Every sentence earns its place and the description is front-loaded with the primary action.

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

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

For a single-optional-param read-only tool, the description covers operation, usage context, scoping, and related tools. It sufficiently conveys return behavior (a value or a list of keys) despite having no output schema.

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

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

The input schema already describes the 'key' parameter and states 'omit to list all keys,' so the description adds no new parameter-level meaning. The examples in the description ('target ticker, address') are illustrative but not semantically necessary 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 specifies 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly identifies the tool's operation and distinguishes it from sibling tools remember and forget. The verb 'Retrieve' and resource 'value' are explicit.

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

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

It states 'Use to look up context the agent stored earlier' with concrete examples like 'user's target ticker, an address, prior research notes.' It also names companion tools: 'Pair with remember to save, forget to delete,' providing clear alternatives for related operations.

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 explicitly discloses a mutating side-effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the annotation readOnlyHint=true, which asserts the tool does not modify state. The useful disclosure is negated by the contradiction, so this dimension scores at 1.

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: first states the purpose, second details return contents, third covers filtering and the mark_read side-effect, plus an alternative endpoint. Every sentence is purposeful, the information is front-loaded, and no words are wasted.

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 carries the responsibility of explaining return values, which it does (source, citation_uri, raw event payload). It covers filtering, polling, the persisted feed, and even an HTTP fallback. This is comprehensive for a read-focused tool with five optional parameters.

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

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

The input schema describes all five parameters, giving 100% coverage. The description adds value by explaining the impact of mark_read ('so the next call only shows newer ones'), which is not captured in the schema. It also provides an example of type filtering, but does not elaborate on all parameters—since coverage is high, the baseline is 3 and the added 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 opens with 'Pull fired events from your subscription feed,' a specific verb+resource combination. It clarifies the scope (subscription feed), the return contents (source, citation_uri, raw event payload), and distinguishes from sibling tools like list_subscriptions by focusing on events rather than subscription management.

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

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

The description gives a clear context for use: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This indicates when the MCP tool is suitable (polling) versus an alternative endpoint, though it does not explicitly compare with sibling MCP tools or state when not 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses real behavioral traits: fan-out to SEC EDGAR, GDELT preferred with GNews fallback on rate-limit/5xx, and USPTO soft-failure due to PatentsView API sunset. It also specifies return structure (changes[] grouped by source, total_changes, citation URIs) and date shorthand handling. No contradiction with annotations.

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

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

The description is long but information-dense: query examples, source fan-out details, fallback behavior, date formats, return shape, and an explicit alternative. Every clause contributes value; it is front-loaded with user-friendly intents and ends with a practical redirect, though slightly wordy.

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

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

Despite having no output schema, the description fully covers expected return elements (changes[], total_changes, citation URIs), source behavior, date parameter flexibility, and failure modes. It also names a concrete alternative tool. Given the tool's complexity, this is a complete and self-sufficient description.

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. The description adds examples for `value` (ticker vs. zero-padded CIK) and a usage hint for `since`, but largely repeats the schema rather than introducing new semantics. This aligns with the baseline of 3 for high schema coverage.

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

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

Description opens with concrete user-intent phrasings ('What's new with X' / 'latest on Y') then explicitly defines it as a change feed for a company in the last N days/weeks/months in ONE parallel call. It clearly identifies the resource (company change feed spanning SEC, GDELT/GNews, USPTO) and distinguishes from sibling entity_profile for static profiles.

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

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

The description tells when to use this tool ('What's new' / 'latest on Y' / 'updates on Acme') and explicitly directs users to entity_profile when a static profile is needed. It also clarifies `since` parameter choices ('Use 30d or 1m for typical monitoring') and describes the single-call fan-out behavior, giving clear context 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 adds behavioral context beyond annotations: key-value scope by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. This complements the annotations (readOnly=false, idempotent=true, destructive=false) without contradiction.

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

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

The description is four sentences, front-loaded with the core action, then moves to usage, behavior, and sibling pairing. Each sentence contributes new information without redundancy, making it highly efficient.

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

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

For a simple key-value store with full schema coverage and comprehensive annotations, the description provides all necessary context: what to save, when to use it, how long it persists, and how to retrieve/delete. No critical gaps remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context about the key-value pairing being scoped by the agent's identifier and gives usage examples that reinforce parameter purpose, though it doesn't substantially rename or reinterpret the 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 saves data for later reuse, with specific examples (ticker, address, preference) that illustrate the resource type. It also distinguishes the tool from siblings by explicitly mentioning recall (retrieve) and forget (delete), making the tool's role 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 gives direct usage guidance: 'Use when you discover something worth carrying forward' and provides concrete scenarios. It also instructs pairing with 'recall to retrieve later, forget to delete,' which effectively explains when to use this tool 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses valuable behavioral traits: it cascades through multiple lookup endpoints internally, degrades gracefully if GLEIF/OpenFIGI is unavailable, explicitly reports unresolved identifiers in an `unresolved` field, and labels identifiers with their source. This significantly enhances the agent's understanding of what happens during the call.

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 relevant user queries and clearly organized into usage directive and supported types. It is longer than the typical description, but every sentence contributes substantive detail (sources, degradation, unresolved handling). The structure could be slightly streamlined, but it's appropriately sized for the tool's complexity.

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

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

Given the tool has no output schema and only 2 parameters, the description thoroughly covers what the tool does, what inputs it accepts, what outputs to expect (including an `unresolved` field and citations), and edge-case behavior (graceful degradation). It provides complete context for an agent to select and invoke the tool correctly.

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

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

The schema already covers both parameters with detailed descriptions (100% coverage). The description adds context by explaining what each type returns (e.g., company yields CIK, ticker, LEI, FIGI; drug yields RxCUI, ingredient, brand) and gives input examples. This adds value beyond the schema, though some information is redundant with the schema's parameter 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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input,' which is a specific verb+resource. It also provides concrete examples like 'What's the ticker for…' However, it does not explicitly distinguish itself from sibling tools by naming alternatives, so it stops short of a 5.

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

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

The description gives a clear directive: 'Use FIRST whenever you have a name but need an ID.' It also notes that using it replaces 2-3 manual lookups, implying a preferred workflow. However, it does not list when not to use it or explicit alternative tools, so it lacks full exclusion/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 already declare readOnly, openWorld, idempotent. The description adds that it 'Probes each entity... with ai_visibility_check', 'ranks by score', and 'Returns ranked list with score, confidence, signal density per entity'—useful context beyond annotations.

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

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

Four sentences, front-loaded with the core purpose, followed by mechanism, use case, and output format—each sentence earns its place.

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

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

No output schema exists, but the description compensates by explicitly listing the return fields ('score, confidence, signal density'). Given the tool's moderate complexity and good annotations, the description 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 coverage is 100% and every parameter is described. The description adds minor context (e.g., 'your brand + N competitors' for entities) but doesn't meaningfully 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 states 'Compare AI visibility across multiple entities side-by-side' with a specific verb 'compare' and resource 'AI visibility across entities'. It distinguishes from sibling 'ai_visibility_check' by emphasizing multiple entities and side-by-side ranking.

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 identifies a clear use case: 'Useful for competitive AI-marketing audits' with an example query. It implies the tool is for multi-entity comparison but doesn't explicitly mention alternatives or when not to use it.

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

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

Beyond the readOnly/idempotent hints, the description discloses partial failure behavior, potential 5-30s latency on first measurement, and the sources_failed field. These are valuable behavioral details not present in annotations, helping the agent anticipate timeouts and degraded responses.

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?

A single dense paragraph front-loads the purpose, then covers when-to-use, return contents, ecosystem scope, and failure modes. Every sentence contributes a distinct piece of information; 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?

Despite the lack of an output schema, the description enumerates the summary block fields, per-advisory details, links, alternative versions, and failure handling. It fully covers the tool's behavior, constraints (NPM only in v1), and partial-success semantics, making it self-sufficient.

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

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

Schema coverage is 100% with clear descriptions for both 'package' (npm package name, scoped packages accepted) and 'version' (defaults to latest). The description adds high-level context (composite check, data sources) but does not add new meaning to individual parameters beyond schema, so baseline 3 is appropriate.

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

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

The description clearly states a composite check for 'should I add this npm package to my project' with specific verbs ('check', 'fans out') and resources (deps.dev, bundlephobia). It distinguishes itself from siblings like get_package and search_packages by detailing the combined sources and returned summary 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?

Explicitly provides when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also gives an alternative for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', making the guidance actionable.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds context about the tool's search nature (full-text + faceted), the court-specific filter (for USCOURTS), and the return of package IDs and titles. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and includes only necessary details. No filler or redundant information.

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

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

Given the comprehensive schema and existing output schema, the description adequately covers the essential search behavior and return value. It omits pagination details, but those are captured by the offset_mark parameter schema, so the description is complete enough for this moderately complex 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?

The input schema provides 100% parameter descriptions, so the baseline is 3. The description summarizes filter categories but does not add significant meaning beyond the schema; the only minor addition is the court filter nuance for USCOURTS.

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: 'Full-text + faceted search across GovInfo' with specific filters and output ('Returns package IDs and titles'). This distinguishes it from sibling tools like get_package (retrieve a specific package) and list_collections (list collections) by focusing on cross-corpus searching.

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

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

The description gives clear context on when to use the tool – for full-text and faceted search across GovInfo – and enumerates filter categories (collection codes, date range, congress, court). It does not explicitly name alternatives or exclusion cases, but the intended use case is evident.

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 readOnlyHint=true and destructiveHint=false, the description adds valuable behavioral details: the use of BGE-base-en embeddings with cosine similarity, overlapping 500-char windows, a 200K character limit with truncation flagging, and the fact that passages include character offsets for verbatim verification. These go beyond the annotations and give the agent confidence in the tool's internals and edge cases.

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

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

The description is three sentences long and front-loads the core purpose. The first sentence states what it does, the second gives the use case and benefits, the third provides technical details and limits. Every sentence adds necessary information without fluff, making it dense yet 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?

The description is complete for a search tool: it explains what outputs to expect (top-N passages with character offsets and similarity scores), mentions the truncation flag, and ties the tool to a sibling workflow. Given no output schema exists, the description compensates by describing the return format and the embedding/windowing behavior, so the agent has enough context to invoke and use the tool correctly.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds extra meaning by explaining the 'text' parameter as 'the text you already pulled' with concrete examples (SEC 10-K body, article), and gives illustrative queries for 'query' (e.g., 'supply-chain risk'). This enriches the schema definitions, though the 'limit' parameter is not elaborated further.

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 'Semantic search INSIDE a fetched record,' which clearly states the action (semantic search), the resource (a fetched record), and distinguishes it from siblings like ask_pipeworx_grounded (which grounds over the whole document) and get_granule/get_package (which fetch). The verb 'search' is specific and the scope 'inside a fetched record' is 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 this tool: 'Use when the record is too big to cram into the prompt.' It also provides a direct pairing with ask_pipeworx_grounded, explaining the workflow: fetch with the gateway, then ground over relevant passages. This gives clear guidance on the tool's role relative to alternatives.

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

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

The description discloses several behavioral traits beyond annotations: OAuth requirement, anonymous/BYO limitation, SMS phone verification and 10/day cap, and the always-on feed. It does not mention webhook delivery in the main description, but the schema details it; no contradiction with annotations exists. Idempotency and non-destructiveness are covered by annotations, so the added value is moderate but real.

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 not bloated; it packs type-specific examples, auth requirements, and delivery channels into a few sentences. The sentence structure could be tightened, but each clause carries useful information. It is longer than typical but proportional to the tool's complexity.

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

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

The description covers the tool's purpose, return value, prerequisites, and delivery channels, but it fails to enumerate two of the five supported types (patent_grant, clinical_trial) that appear in the schema. Webhook delivery is also absent from the description, though present in the schema. Given the moderate complexity and lack of output schema, the description is strong but not fully complete.

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

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

The input schema has 100% coverage, so the baseline is 3. The description adds concrete examples (items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE') and delivery channel constraints (email/sms verification, cap), enriching the schema's structured definitions. However, it omits patent_grant and clinical_trial examples, leaving those to the schema.

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

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

The description states 'Create a proactive monitoring subscription to a live-data event stream' with a clear verb and resource, and notes it returns the new subscription id. It distinguishes this from sibling tools like list_subscriptions and unsubscribe by focusing on creation. The supported types list is illustrative but omits two schema types, though the core purpose remains 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 provides context on when to use the tool: proactive monitoring of live-data events, with OAuth account requirement and delivery channel options. It does not explicitly contrast with alternatives like list_subscriptions or unsubscribe, but it conveys the subscription-creation context and prerequisites. The mention of pulling via recent_alerts or a registry URL suggests alternatives for consuming the feed, not for creating subscriptions.

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 behavioral context beyond this: returns category-bucketed example questions, draws from a live catalog, includes tool+argument shape per example, and supports both full-spread and topic-focused modes. No contradictions exist.

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

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

The description is effective and information-dense after the opening em-dash list, but the list of seven synonymous questions ('What can I ask Pipeworx? / what is Pipeworx good for? / ...') is redundant and adds little beyond pattern matching. Trimming that would make the description more concise while preserving its clarity.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description covers everything needed: what it returns (category-bucketed example questions with tool+argument shapes), how to invoke it (no args vs topic), when to use it ('FIRST'), and even which meta-tools it teaches. No gaps are apparent.

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 well-described 'topic' parameter, so the baseline is 3. The description adds value by providing concrete example values ('finance', 'pharma', 'betting') and the semantic meaning of omitting the parameter (cross-category spread), which enriches 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 ('suggest questions') and identifies a clear resource: an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It strongly distinguishes itself from siblings like ask_pipeworx (which answers questions) and discover_tools (which likely lists tools) by centering on what to ask and how to ask it.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and to learn how to call meta-tools. It also explains the optional topic parameter for focusing. However, it does not explicitly mention when NOT to use it or name alternative tools for other scenarios, 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?

The description adds important behavioral context beyond the annotations: the row is deactivated, not deleted, and historical events remain available via recent_alerts. This clarifies the softer side effects of an operation that already has destructiveHint=false and readOnlyHint=false, enriching the agent's understanding without contradiction.

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

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

The description is just two sentences, front-loaded with the action, and includes key caveats (ownership and deactivation) without unnecessary fluff. Every clause earns its place.

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

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

For a simple single-parameter mutation, the description covers the core action, ownership guard, and the important side effect (soft deactivation and history preservation). It does not specify return values, but the lack of an output schema makes that optional. The openWorldHint and idempotentHint are already in annotations, so the description is sufficiently complete for 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?

The input schema fully describes the id parameter as 'Subscription id (uuid) returned by subscribe.' The description adds little beyond saying 'by id', so it does not significantly enhance the schema's already clear semantic 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 action ('Cancel a subscription by id') and the resource (subscription), and the title clarifies it is for alerts. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation, not creation or listing.

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 context of when to use the tool is clear (to cancel a subscription), and the ownership constraint ('you can only cancel your own subscriptions') provides a useful prerequisite. It does not explicitly name alternatives like list_subscriptions for finding the id, but the main use case is unambiguous.

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

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

The description discloses the two execution paths, the meaning of each verdict (especially distinguishing could_not_verify from unsupported), and the requirement not to present could_not_verify as evidence. Annotations already declare readOnly and non-destructive, and the description adds substantial behavioral context beyond that, with 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?

Though lengthy, every sentence serves a function: trigger phrases, usage guidance, routing logic, verdict details, and caller warnings. The structure front-loads the most critical usage information and the length 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?

The description fully covers input expectations, processing paths, output format (verdict + value + citation + reasoning), and edge cases. It also explains the tool's role in replacing sequential calls, making it standalone sufficient for an agent to invoke correctly. No output schema exists, but the description compensates adequately.

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

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

Schema description coverage is 100% with both parameters thoroughly documented (claim with an example, tolerance_pct with range and default). The description adds no parameter-specific meaning beyond the schema, only restating the hallucination-detection use case already present. Thus 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 identifies the tool as a natural-language claim verification service, with explicit trigger phrases and a definition of its output (verdict + evidence). It distinguishes itself from search tools by stating it replaces 4–6 sequential calls and returns a judgment, making its purpose unmistakable.

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

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

It explicitly instructs to use whenever the agent needs to check factual correctness of a user's statement. It further provides conditional routing guidance (company-financial claims via SEC EDGAR, all others via grounded pipeline), giving the agent a clear decision framework. The warning about could_not_verify adds critical usage nuance.

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