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?

The annotations already convey read-only, open-world, and idempotent behavior. The description adds meaningful beyond-annotation detail: the tool routes to 5,798 tools across 1,517 verified sources, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This gives the agent a clear model of what happens at invocation, with no contradiction to the annotations.

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

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

The description is well-structured and front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. Each section (scope, mechanics, trigger phrases, examples, priority) serves a purpose. However, it is fairly long, and the final sentence about breaking-news packs is slightly awkward, so it falls short of perfect conciseness.

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

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

For a tool with one required parameter, no output schema, and read-only/idempotent annotations, the description is complete. It explains what the tool does, how it behaves, when to use it, and what the return format looks like (structured answer with pipeworx:// citations). Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%: every parameter is documented as an alias for 'question', and the schema already says it accepts natural language. The description reinforces that with examples and trigger phrases, but it does not add significant new meaning about the parameter itself. Baseline 3 is appropriate given the schema already carries the semantic load.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing to thousands of verified data sources and returns structured answers with citations. It explicitly distinguishes itself from web search, but it does not directly differentiate from sibling tools such as ask_pipeworx_beta, ask_pipeworx_grounded, or deep_research. The phrase 'START HERE for most questions' provides some implicit differentiation, but not the explicit sibling contrast that would earn 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?

Usage guidance is explicit and prominent: 'PREFER OVER WEB SEARCH' appears at the start, followed by a list of query triggers ('what is', 'look up', 'find', etc.) and example questions. The 'START HERE for most questions' sentence establishes priority among the broader toolset. This is strong when-to-use guidance, including the condition that web search could also answer the question.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds significant behavioral context: it is a live experimental edge, candidates may be enabled at any time, currently no candidate is active so it matches ask_pipeworx exactly, and it is a full working router with no fallback. This goes well beyond the annotations.

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

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

The description is front-loaded with 'Beta version of ask_pipeworx' and every sentence contributes useful information such as current state, usage condition, and comparison against the stable router. The exact date and tool count add precision but make it slightly denser than strictly necessary.

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

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

The description tells the agent the tool is interchangeable with ask_pipeworx and shares the same response shape, which compensates for the missing output schema. Since ask_pipeworx appears as a sibling tool, the agent can retrieve its details. It is not fully standalone, but sufficiently complete in context.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description only says 'same arguments' as ask_pipeworx and adds no param-specific detail, which is acceptable but not additive beyond the 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 identifies the tool as a beta variant of ask_pipeworx: an identical universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by its experimental routing improvements, so an agent can tell them apart.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This states a clear condition and names the stable alternative, though it does not explicitly spell out 'use ask_pipeworx when you need stable behavior.'

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

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

The description adds substantial behavioral context beyond the annotations: it reveals the refusal mechanism, enumerates refusal reasons, discloses the extra LLM call cost, and explains that the tool will not invent facts. This goes well beyond the readOnly/idempotent hints already provided.

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

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

The description is dense and front-loaded: purpose first, then behavior, then usage guidance and trade-off. Every sentence adds decision-relevant information — including the refusal taxonomy and cost comparison — with no filler or repetition.

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

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

For a tool of this complexity with no output schema, the description is remarkably complete: it specifies the success return shape, the refusal shape, all refusal reason enum values, and the exact scenarios for use. The parameter layer is already covered by the schema, so nothing necessary for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents the question parameter and its aliases. The description does not need to repeat parameter details; it stays at baseline because it contributes no additional parameter-specific semantics beyond implying that a natural-language question is expected.

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

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

The description states a specific purpose ('hallucination-resistant answer mode for high-stakes reads') and clearly differentiates from ask_pipeworx by emphasizing extraction grounded only in tool results. It names the exact behavior — returning an answer with evidence or an explicit refusal — so an agent can distinguish it from sibling tools without inspecting them.

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 ('whenever an answer will be quoted, cited, or acted on') with concrete examples. It also gives an exclusion rule ('prefer ask_pipeworx for casual lookups') and names the alternative directly, making routing 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?

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?

Annotations mark the tool read-only and idempotent, and the description goes well beyond them: it discloses parallel tool routing, findings-packet structure, gaps[] never-invented behavior, contradiction scans, semantic excerpting, citation fetchability, and latency. No surprising side effects are hidden.

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; nearly every sentence contributes operational detail, and the most important routing/auth guidance is front-loaded. It loses a point because the depth-tier discussion partially duplicates the schema description and the whole thing is a single dense paragraph that could be structured more cleanly.

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

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

There is no output schema, so the description must carry the return-value contract on its own. It does so thoroughly: findings packet fields, hop and citation_uri behavior, gaps[], contradictions[], semantic excerpting, expected latency, auth requirements, and fallback tool. The agent has everything needed to invoke correctly.

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

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

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds one critical piece beyond the schema: depth:'thorough' requires a paid plan, which directly affects invocation success. It also reinforces the meaning of quick/standard/thorough and question decomposition, so it earns 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 states a specific action: grounded multi-source research across Pipeworx's structured data sources in one call, with decomposition, parallel routing, and a findings packet. It also explicitly distinguishes itself from open-web search and from ask_pipeworx, 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?

Usage guidance is explicit: use ask_pipeworx when not signed in, use ask_pipeworx for single lookups, and use deep_research for broad/multi-part structured-data questions. This gives clear when-to-use and when-not-to-use direction rather than leaving it to inference.

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?

Annotations already set readOnly/openWorld/idempotent/nondestructive, and the description adds substantial behavioral context: fan-out across many sources, soft-failure of the USPTO API, resolved_from/resolved_to for name lookups, sources_used/sources_failed semantics, and 'an empty section is a real no-data, not a bug.' 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?

Front-loaded with intent examples and a clear 'ALWAYS PREFER' directive, then a logically structured explanation of fan-out, output sections, failure modes, and parameter forms. It is long, but most clauses carry distinctive information; minor redundancy and length prevent a 5.

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

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

For a multi-source tool with no output schema, the description enumerates every major return group, source, failure mode, and input form, and explains how to interpret empty sections, soft-failed sources, and private companies. This is sufficient 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%, so baseline is 3; the description adds meaningful value by clarifying that 'type' is interchangeable, that 'value' can be a ticker, zero-padded CIK, or company name, that names resolve via SEC EDGAR, and that private companies yield resolved:false with notes. This goes beyond the schema, though a few formatting edge cases remain unspecified.

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 concrete user intents ('Tell me about X', 'research Acme', 'brief me on Tesla') and states it returns a 'full cross-source profile of a US public company in ONE parallel call,' using specific verbs and naming the resource. This clearly distinguishes it from single-pack lookups and sibling tools like resolve_entity or compare_entities.

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

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

Explicitly frames when to use it: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' with concrete query examples. It also specifies boundaries — US public companies, accepted input forms, and private-company behavior — giving an agent both selection and exclusion criteria.

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 declare readOnly/openWorld/idempotent/non-destructive, so the description only needs to add value beyond that. It adds conceptual context about what granules are and what the call returns, though it does not mention pagination behavior despite pagination parameters existing.

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

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

The description is a single, information-dense sentence with front-loaded purpose, concrete examples, and a return-value note. There is no wasted text or repetition of schema content.

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

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

Given the output schema and fully described input schema, plus safety annotations, the description is complete enough for correct tool selection. It explains the domain concept (granules) and the output shape at a high level; pagination details are already available in the schema and 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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds no parameter-level detail beyond saying the operation is within a package, but it does not need to compensate for any schema gaps.

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 and resource ('List granules within a package') and clarifies what counts as a granule with concrete examples from CFR titles and Federal Register issues. It also states the return payload (granule IDs + titles), which distinguishes it from sibling tools like get_package or get_granule.

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 use context: call this when you already have a package_id and want the granules inside it. It does not explicitly name alternatives or when-not-to-use cases, but the context is strong enough for an agent to select it over search/list siblings.

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

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

Annotations already declare readOnlyHint 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?

The description goes far beyond the readOnly/idempotent annotations by disclosing pairing methodology (keyword overlap, not shared resolution source), the meaning of null temporal_alignment, gross-vs-net fee treatment, unverified pairing flags, and the behavior for unknown metric types. It explicitly tells the agent that compatibility fields can be non-empty even when matched_pairs > 0, preventing a dangerous false sense of validity. No contradiction with annotations exists.

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 aggressively front-loaded with the core purpose and modes, and nearly every sentence carries substantive behavioral guidance. However, it is extremely long and dense, with all-caps labels, nested parentheticals, and repeated code categories that would be easier to parse as structured bullets or a shorter field glossary. It is thorough but not concise.

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

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

With no output schema and only basic annotations, the description carries the full burden of explaining return semantics, safety fields, compatibility codes, fee treatment, and skipped-comparison counters. It covers all of these in enough detail that an agent can interpret results even without ever having seen an actual response. For a tool of this complexity, the description is effectively 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 already provides 100% description coverage for the three optional parameters, so the baseline is 3. The description adds value by explaining the mode relationship between `topic` and the explicit overrides, clarifying that explicit tickers/slugs override the topic-mapped side, and giving concrete examples. The topic parameter's enumerated values are also restated, reinforcing what the shortcut list means.

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 opening sentence identifies the exact computation and venues: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' The two modes, response description, and safety-field notes further clarify what the tool does. It does not explicitly differentiate itself from the closely related sibling polymarket_arbitrage, so purpose is clear but sibling differentiation is left 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?

The description clearly distinguishes the two invocation modes — pre-mapped `topic` shortcuts versus explicit `kalshi_event_ticker` + `polymarket_event_slug` — and explains that both run the same matcher. It also warns that pre-mapped topics often produce compatibility warnings and that returned spreads are not necessarily tradeable. However, it does not explicitly say when to use this tool instead of sibling tools such as polymarket_arbitrage or bet_research.

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

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

Annotations already 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?

Annotations already mark it read-only/idempotent/non-destructive, and the description adds materially beyond that: internal cascade of lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, ambiguous matches returning figi_candidates rather than asserting, and explicit unresolved identifiers.

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 unusually long, but nearly every sentence earns its place and the key message ('name to ID, use first') is front-loaded. A minor structural clean-up could tighten the middle section, but it remains organized by purpose, supported types, and fallback behavior.

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

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

For a tool with no output schema, it is remarkably complete: it covers accepted inputs, supported entity types, ambiguous-match behavior, enrichment failure modes, and what gets returned (identifiers, sources, unresolved list, figi_candidates). An agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, but the description goes further by listing accepted input forms (ticker, CIK, ISIN, name), giving concrete examples, and warning to pass only the issuer name because trailing security-class words break the FIGI lookup. This is practical guidance the schema alone does not provide.

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 phrasings ('What's the ticker for…', 'find the CIK for…') then states a specific verb+resource: resolve a user-spoken name to canonical/official identifiers. It differentiates from sibling tools by positioning itself as the first step whenever a name needs to become an ID, which separates it from entity_profile/compare_entities.

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

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

Gives an explicit trigger ('Use FIRST whenever you have a name but need an ID') and says it replaces 2-3 manual lookups. However, it does not name siblings as alternatives or state when NOT to use it, leaving some inference to the agent.

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 mark the tool as read-only, idempotent, and non-destructive, so the bar is lower. The description adds useful behavioral context by explaining that collection codes search the union of collections and by listing the fields returned, complementing the annotations without contradicting them.

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

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

Two sentences carry the entire functional description: the operation, the filters, the union nuance, and the return values. There is no filler, and the core action is 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 output schema is present and the annotations cover safety, the description is sufficiently complete for invoking the tool: query, filters, and result fields are all stated. It could marginally improve by noting pagination behavior, but that is already covered by the schema's page_size and offset_mark parameters.

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

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

Schema coverage is 100%, and the schema already describes each parameter in reasonable detail, including the union behavior for collections. The description adds high-level meaning such as 'date range' and 'congress' but does not substantially extend the schema's parameter-level explanations.

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-text + faceted search across GovInfo', which names a specific verb, resource, and scope. It goes on to enumerate the filter dimensions (collection codes, date range, congress, free-text) and the return shape (package IDs, titles, collection and issue dates), making it clear how this differs from more targeted package tools.

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

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

The description clearly establishes the intended use: searching across GovInfo packages by facets like collection, date, and congress. It does not explicitly name alternative tools or exclusion conditions, but the context is strong enough that an agent can infer when to prefer this tool over package-listing or granule-level 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?

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.