Openstates

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable context: the default model is Workers AI Llama-3.3-70b (free), passing _apiKey enables Anthropic probing with direct charges, and the return structure includes per-model score, confidence, signals, raw_response, and a combined view. This goes beyond simply restating annotations.

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

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

The description is three sentences with no filler: it states the action and scoring, explains model defaults and API key usage, and closes with return format and use cases. It is front-loaded and every 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?

With no output schema, the description appropriately specifies the return fields (score, confidence, signals, raw_response, combined view). It also covers the default model, optional Anthropic key, and practical use cases, making the tool fully usable without further documentation.

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

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

The schema provides 100% coverage for parameters, so the baseline is 3. The description enhances this by naming the default model (Workers AI Llama-3.3-70b) and explaining the cost implications of _apiKey, adding meaning beyond the schema's descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. The specific verb 'probe' and resource (business/brand/product/topic) distinguish it from sibling tools like ask_pipeworx 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?

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not provide exclusions or direct alternatives, so it falls just 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, openWorldHint, idempotentHint, destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: routing to 5,529 tools, argument filling, stable citation URIs, one fast call, and broad coverage. No contradiction with annotations; a slight deduction for not mentioning limitations or failure modes.

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, front-loading the critical 'PREFER OVER WEB SEARCH' directive. It packs numerous examples and usage nuances without redundant filler. Minor repetition of the web-search preference, but overall it earns its length.

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

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

There is no output schema, so the description compensates by explicitly stating the response includes structured answers with stable citation URIs. It covers usage contexts, alternatives, examples, and even explains behavior for news queries. This is a complete and self-contained description for the tool.

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

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

Schema description coverage is 100%, with all parameters clearly defined as aliases for 'question'. The description reinforces natural-language usage and provides examples, but the schema already carries the meaning. Thus, the description adds only marginal parameter semantics 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 the tool's purpose: route factual questions to a large collection of verified sources and return structured answers with citations. It distinguishes itself from web search and from sibling tools like ask_pipeworx_grounded and deep_research by specifying its default, lower-latency nature.

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

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

The description provides explicit guidance on when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to step up to alternatives ('for a hallucination-resistant single answer use ask_pipeworx_grounded; for a broad/multi-part question use deep_research'). It also lists concrete example queries and notes that news is handled internally.

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

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

The description goes well beyond the annotations by disclosing the experimental nature: potential behavioral differences when a candidate is under test, the current state (no active candidate, so identical to stable), and the fallback behavior (full working router, not a partial implementation). It also explains how and why routing might change.

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 densely packed with useful information—identity, current status, usage, and a clarifying note about fallback. Each sentence serves a purpose, though the first sentence is somewhat long with a parenthetical. It is well-structured and not verbose, earning a high score.

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 a sibling (ask_pipeworx) and a beta context, the description is remarkably complete. It covers what the tool does, how it differs, its current operational state, usage instructions, and the fact that it is a full working router. No output schema exists, but the description references the same response shape as ask_pipeworx, which is sufficient for a router tool.

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

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

The schema already covers all parameters with descriptions and aliases, so the description does not need to add parameter-level detail. The mention of 'same arguments' reinforces that the question parameter works exactly as in ask_pipeworx, but this is redundant with the schema. Baseline 3 is appropriate given 100% schema coverage and no missing or ambiguous 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 explicitly identifies this as the beta version of ask_pipeworx, a universal router with the same tools and arguments. It clearly distinguishes it from the stable ask_pipeworx by noting it carries candidate routing improvements, and even provides specificity (5,529 tools, same response shape).

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

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

It states exactly when to use this tool ('when you want the newest routing') and explains the relationship to ask_pipeworx, including that results are compared against the stable router. It also notes the current inactive state, so no candidate is active, making usage identical to ask_pipeworx at this time.

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

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

The description goes beyond annotations by detailing return structure ({answer, evidence, confidence, source, fetched_at}) and specific refusal reasons (not_in_source, no_tool_match, etc.). It also discloses the extra LLM call cost and the constraint that answers are extracted only from tool results, which is valuable behavioral context.

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

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

The description is dense but well-structured, front-loaded with the core distinction ('Hallucination-resistant answer mode'), followed by mechanism, return format, and usage guidance. Every sentence adds value and there is no fluff.

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

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

Despite having no output schema, the description fully explains the return format, error/refusal cases, and expected use cases. It also covers the cost trade-off and relationship to ask_pipeworx, making it complete for high-stakes decision-making contexts.

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 detailed descriptions for the question parameter and its aliases. The description does not add parameter-specific details, but it implies the input is a natural language question and explains how the question is used (routing, fetching, extracting). This is sufficient given the schema's completeness; 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 uses a specific verb phrase ('Hallucination-resistant answer mode') and clearly states what the tool does: routes like ask_pipeworx, extracts answers using only tool results, and returns structured evidence. It distinguishes itself from sibling tools by emphasizing the refusal behavior and evidence-based output.

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 usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups' directly names the alternative and cost trade-off. This gives clear when-to-use and when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds extensive behavioral detail: resolver confidence levels, low-confidence short-circuits, closed-market handling, wide-spread illiquidity warnings, news fallback retry semantics, and cancellation-rule risk (e.g., refund_50_50). This goes far beyond what annotations provide.

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

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

The description is long but well-structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and every paragraph delivers distinct behavioral contract details. It is front-loaded with purpose, but the length and repeated examples could be trimmed to reduce token consumption.

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

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

With no output schema, the description must document return values, and it does so thoroughly: result.market fields, result.analysis with edge/kelly warnings, evidence keying, resolver alternatives and suggestions, parent_event partition data, status codes, and the cancellation-rule enum. It covers blocking routes, fallback behavior, and edge cases, making it complete for a complex research tool.

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

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

The input schema has 100% coverage with detailed descriptions and examples for market, depth, and include_raw. The description adds little beyond restating market input forms (slug/URL/question) and describing response shapes, so it does not meaningfully extend parameter 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 opens with a specific verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also enumerates target use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which clearly differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges that focus on narrower concerns.

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

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

The description provides explicit usage context via the 'Use for' list and concrete fan-out examples, giving the agent clear guidance on when to call the tool. However, it does not name exclusions or directly contrast with alternatives in the sibling set, so it stops short of full when-not guidance.

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

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

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description discloses rich behavioral details: data sources (SEC EDGAR/XBRL for company, FAERS for drug), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and output format (paired data + citation URIs). This exceeds what annotations provide and accurately represents 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 long but every clause serves a purpose: trigger examples, parallel-call emphasis, type-specific data sources, fiscal year handling, output sorting, and efficiency gains. It is front-loaded with direct examples, and while dense, it remains scannable. A few minor redundancies exist (e.g., repeating 'parallel call'), but overall it is well-structured for an AI agent.

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 explaining the return format ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. It also covers edge cases (off-calendar fiscal years) and both entity types, making the tool's behavior fully understandable. There are no missing critical pieces for a comparison 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% (type and values both documented), so baseline is 3. The description adds significant value by explaining the meaning of each type ('company' pulls latest 10-K metrics, 'drug' pulls FAERS counts) and clarifying the values format (tickers/CIKs for company, drug names for drug). This extra contextualization goes beyond the schema's simple enum and array description.

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

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

The description uses specific verbs and resources: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes from siblings like entity_profile by emphasizing the comparative, multi-entity focus and the 'head to head' use cases. The explicit trigger phrases ('X vs Y', 'rank these companies') make the tool's purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists example queries that should trigger this tool. It also mentions it 'Replaces 8–15 sequential lookups,' reinforcing the context for use. It does not explicitly name alternatives, but the contrast with single-pack lookups is clear.

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

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

Despite annotations already declaring readOnly/openWorld/idempotent, the description adds rich behavioral context: account and paid plan requirements, latency ranges, gaps[], contradictions[], citation_uri availability policy, semantic excerpting, and a promise that it 'never invented' data. None of this contradicts the annotations, and it significantly exceeds the annotation baseline.

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 each sentence earns its place, covering account prerequisites, usage guidance, output format, depth semantics, and latency. It is front-loaded with critical info (account requirement, alternative tool) and organized in a logical flow. A small deduction for verbosity, but it is appropriately sized for such a complex tool.

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

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

The description thoroughly explains the return value (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), the gaps[] and contradictions[] fields, the excerpting behavior, and expected latency. Given the tool's complexity and lack of an output schema, this provides complete contextual guidance for an agent to set expectations.

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 beyond the raw enum values by explaining what each depth level does (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with iterative hop). It also clarifies that the 'question' parameter accepts broad/multi-part natural language, which adds meaning not evident from the schema alone.

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 ('research') and a clear resource ('Pipeworx's 1455 STRUCTURED data sources'), and it explicitly states what the tool does: decomposes questions into facets, routes to tools, and returns a findings packet. It also distinguishes itself from siblings by noting 'this is NOT open-web search' and directly contrasting with ask_pipeworx.

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 deep_research ('Best for broad/multi-part questions over structured data') and when not to use it ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also provides an alternative tool if the user is not signed in, satisfying the when/when-not/alternatives requirement fully.

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

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

Annotations already declare the tool safe (readOnlyHint, idempotentHint, destructiveHint=false). The description adds valuable behavioral context: it returns top-N tools with full schemas, no second lookup needed, and each result is directly callable. This goes beyond the annotations, though it doesn't cover rate limits or failure modes.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence earns its place. It includes scope, usage, return format, and a prioritized call-to-action without redundancy.

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

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

For a discovery tool with only query and limit parameters, the description fully covers what it does, when to use it, and what it returns (names, descriptions, schemas, direct-call readiness). No output schema exists, so the description appropriately explains the return value, making it 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 fully describes all parameters with high coverage (100%), including aliases for query and default/max for limit. The description adds a list of example domains and clarifies that the query is a natural language task description, but this is marginal value over the schema's own descriptions and examples.

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's purpose: finding tools by describing a data or task. It uses a specific verb ('Find') and resource ('tools'), and distinguishes itself from siblings by positioning as a meta-tool for discovery rather than a domain-specific search (e.g., deep_research, search_within). The list of domains (SEC filings, FDA drugs, FRED, etc.) further specifies the scope.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also provides a when-not ('not just one answer'), but it does not name specific alternative tools, so it falls short of the 5-level criterion.

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?

Even with annotations indicating read-only, idempotent, and non-destructive behavior, the description adds valuable behavioral details: it fans out across multiple sources, includes a soft-fail for the USPTO API sunset, uses a GDELT→GNews fallback for news, and performs the lookup in 'ONE parallel call.' These traits are not in the annotations and significantly inform agent 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 well-structured, starting with trigger examples, then purpose, usage guidance, return fields, and parameter notes. Every sentence adds value, though the opening example list is somewhat lengthy and could be trimmed without losing essential meaning.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so comprehensively: listing each returned field (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with details like URIs and sorting. It also covers limitations (names not supported) and fallback behaviors, making it sufficiently complete for complex 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 already covers 100% of parameters, including detailed descriptions for 'value' that match the description's guidance on tickers and CIKs. The description adds minimal additional semantics beyond the schema—mostly redundant examples—so it does not exceed the baseline 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?

The description clearly states the tool's purpose with specific verbs and resources: it produces a 'full cross-source profile of a US public company' with concrete examples of user queries. It distinguishes itself from siblings by explicitly preferring over chaining single-pack lookups, making the intent 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?

Provides explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and an alternative for when only a name is available ('use resolve_entity first'). This goes beyond general context by stating exclusions and fallback pathways.

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

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

Annotations already provide destructiveHint: true and idempotentHint: true. The description adds minimal extra behavioral context beyond the rationale of clearing sensitive data, but does not discuss irreversibility, missing keys, or side effects. This is adequate but not enhanced 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?

Two sentences, front-loaded with the core action and followed by usage scenarios. No filler or redundant content; every word 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 a simple one-parameter tool, full schema coverage, no output schema, and strong annotations, the description covers all necessary information 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?

Schema coverage is 100% with the 'key' parameter fully described as 'Memory key to delete'. The description merely restates 'by key' without adding further semantic detail, so it does not add value beyond the schema.

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

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

The description starts with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember and recall, and the action 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?

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with remember and recall, providing clear guidance on relationships with alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds process details (page fetching, extraction, markdown emission) and output characteristics ('single text blob'), enriching the agent's understanding beyond the structured hints.

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

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

Three sentences, each earning its place: the main action, the process, and the intended use cases. The description is front-loaded with the primary outcome and contains 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 two-parameter tool with comprehensive safety annotations and clear output description, the information is complete. No significant gaps remain that would hinder an agent from selecting or invoking 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?

The schema already provides 100% coverage with clear descriptions for both parameters. The description only indirectly references 'any URL' and 'key links', adding little semantic value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Generate'), resource ('llms.txt file'), and the process (fetches, extracts, emits). It differentiates from siblings by specifying the output format and targeted use cases, making it unmistakable what this tool does.

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?

Lists concrete scenarios where the tool is useful (client sites, own projects, competitor audits). It does not explicitly name alternatives or exclusion criteria, but the provided use cases give sufficient contextual guidance for when to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds value by enumerating the contained data (versions, sponsorships, related/companion bills, actions, votes), which is not in the schema or annotations. However, it doesn't disclose edge behavior like outcomes when no parameters are supplied, which matters given no required fields.

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

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

Two sentences, front-loaded with purpose, and no filler. Every phrase contributes to understanding what the tool does and how to invoke it.

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 output schema present and annotations covering safety, the description covers the essential purpose and both valid input modes. It lacks explicit error/edge-case guidance but is otherwise sufficient for this simple retrieval tool.

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

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

Schema coverage is 100% with each parameter individually described. The description adds grouping semantics by explaining the 'state/session/identifier triple' relationship and ranking openstates_id as preferred, which goes beyond the schema's isolated 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 uses the specific verb 'Fetch' and clearly identifies the resource ('a single bill') and the depth of detail ('full detail: versions, sponsorships, related/companion bills, actions, and votes'). This distinguishes it from sibling tools like search_bills, which searches rather than retrieves a single record.

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 two ways to call the tool: 'Pass the OpenStates ID ... or a state/session/identifier triple.' It communicates the preferred method ('OpenStates ID') and the alternative, but does not explicitly contrast with sibling tools or specify when to use one option over the other, leaving a minor gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds valuable context about the return payload (biographical info, current roles, prior offices, contact methods, sources) without repeating annotation data.

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, front-loaded sentence that states the action and the return contents. Every word earns its place, with zero 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?

This is a simple one-parameter tool with an output schema present. The description covers the purpose, input type, and return contents. Given the simplicity and annotations, there are no significant missing details.

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 description covers 100% of the parameter with format guidance (e.g., 'ocd-person/...'). The description merely reiterates 'OpenStates person ID' without adding new semantic detail, so it stays at the baseline 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?

The description clearly states 'Fetch a single legislator by OpenStates person ID' with a specific verb, singular resource, and input type. This distinguishes it from sibling tools like search_legislators, which imply broader search behavior.

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

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

The description implies usage when you have a person_id and need a single legislator's details. It does not explicitly name alternatives or exclusions, but the phrase 'a single legislator' provides clear context for when to use this tool versus searching.

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

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

Annotations already declare read-only/idempotent, and the description adds that it returns active subscriptions by default with specific fields, and that ids can be used for cancellation. 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?

Two sentences, no filler, with the purpose and usage 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?

For a simple single-parameter list tool, the description covers purpose, return fields, default behavior, and typical use case. No output schema is present but field list compensates.

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

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

Schema covers include_inactive with a description, so baseline is 3. The tool description doesn't add extra parameter semantics beyond saying 'active subscriptions', which aligns with the schema default.

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' with a specific verb and resource, and enumerates return fields. This distinguishes it from mutation siblings like subscribe/unsubscribe and from other query 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?

It explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', giving concrete scenarios. It doesn't name alternatives but the guidance is clear.

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

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

Beyond the annotations (which only indicate readOnlyHint=false, etc.), the description reveals rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow for checking status, and that the team reads digests daily. These are behavioral traits not present in annotations, adding real transparency.

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

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

The description is long (about 150 words) but front-loaded with the core action, and every sentence serves a purpose: what, when, exclusions, claim_token mechanics, rate limits. It could be tightened, but the organization is logical and no filler 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 4 parameters, no output schema, and nested objects, the description covers the essential usage scenarios, including the claim_token follow-up flow, which is a non-obvious behavior. It doesn't spell out the exact response structure, but since there is no output schema and the main response is implied (claim_token or status), the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the claim_token lifecycle ('Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed'), which adds semantic depth not captured in the parameter description. It also clarifies that claim_token should be used alone. A slight deduction for not elaborating on the 'type' parameter beyond the schema, but the schema already covers it.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by framing it as the sole feedback channel, and even enumerates feedback categories (bug, feature, data_gap, praise).

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is textbook usage guidance.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description reveals caching behavior ('Cached 5min-1h depending on window'), data provenance ('derived from CF analytics-engine'), and privacy ('no PII, just (pack, tool, count)'). It does not mention rate limits or failure modes, but it adds substantial behavioral context.

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

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

The description is front-loaded with the core purpose, followed by a concise 'Useful for' list and a transparency note. Each sentence adds value, and the overall length is appropriate for the tool's simplicity.

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

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

For a read-only tool with one optional enum parameter and no output schema, the description fully covers purpose, use cases, return contents, caching, and data privacy. The agent has enough information to select and invoke the tool correctly without requiring additional clarification.

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 only parameter, window, is already fully described in the input schema, including the default '24h' and the tradeoff between short and long windows ('Shorter windows surface what's hot right now'). The tool description repeats but does not add new semantic meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'What other AI agents are calling on Pipeworx right now' and clearly states it returns top tools, top packs, and total call volume over a selectable window. This distinguishes it from sibling tools like discover_tools or ask_pipeworx by focusing on aggregated agent-usage trends.

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 'Useful for' list explicitly enumerates when to use the tool: discovering hot data sources, confirming canonical tools, and checking alignment with agent demand. It lacks an explicit 'when not to use' or direct comparison to alternatives, 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?

The description discloses non-obvious behaviors beyond the readOnly annotations: it explains the >3pp deviation threshold for signal emission, the >20% placeholder fraction returning null, the skipped_low_similarity count, and the fill check caveat that realizable_edge_pp ≤ 0 means the edge only exists at last-trade. This adds substantial context that annotations alone do not provide.

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 bolded labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. However, it is somewhat verbose and could be tightened without losing key details, so it falls short of a perfect score.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers return values (opportunities[], partition_check, fill_check fields), edge cases (placeholders, low similarity), and limitations (book depth vs theoretical edge). It also references related tools for custom sizing, making it highly self-contained.

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?

Even though schema coverage is 100%, the description significantly enriches parameter meaning. It provides concrete examples of event slugs ('fed-decision-may-2026') and topic seeds ('Strait of Hormuz traffic returns to normal'), explains what each mode does internally (walks child markets, searches related events), and details the no-args trending_scan behavior not present in the schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no args, event, topic) and references sibling tools like polymarket_fill_risk, making the tool's unique role evident.

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 usage guidance is provided: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also states when each mode is recommended ('event (recommended for a specific market)', 'topic (for cross-event scanning)') and points to polymarket_fill_risk for custom sizing, offering a clear alternative.

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

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

Annotations already declare read-only/idempotent, but the description adds non-obvious behaviors: partition arbs always have parent kelly_fraction_half=0, results cached 1h keyed on all knobs, diagnostics reveal why segments are empty, and the 24h-move warning about edges already being priced in. This goes far beyond the structured hints.

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

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

The description is long but every sentence carries weight for a tool with 9 parameters and no output schema. It is front-loaded with the core purpose and organized into segment/knob/response sections. However, the single block of text could be better structured with line breaks or bullet-like formatting.

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

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

With no output schema, the description fully specifies the response: by_segment has three dicts, fed_candidates/fed_note is separate, and _diagnostics includes funnel counters and filter_skips. It also documents per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h warning). 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 has 100% coverage with detailed parameter descriptions (e.g., slippage_pp explains Polymarket fee structure and typical 20-50bp slippage). The description adds extra context by grouping knobs (tradeable-edge filters) and explaining min_partition_leg_kelly's interplay with parent-level Kelly, which is not in the schema.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is clearly distinguished from siblings by its focus on top markets and data-vs-price disagreement, with 'Built for "what should I bet on today"' reinforcing its niche.

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

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

It provides a clear use case ('agents discover opportunities without paging hundreds of markets') and detailed knob guidance (e.g., min_liquidity/max_spread_pp as tradeable-edge filters). It also flags the Fed segment as unreliable without paid data. However, it does not explicitly say when to prefer a sibling tool like polymarket_arbitrage over this one.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior; the description adds substantial non-obvious context beyond them: 60-day snapshot TTL, snapshot gaps due to cache-miss scanning, decay computed from daily closes (not intraday), and a detailed explanation of expired[] vs tracked[]. This far exceeds the baseline and enriches the agent's understanding of 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 long but well-structured with explicit RESPONSE and LIMITS sections, making it scannable. Every sentence contributes semantically (field meanings, TTL, gap causes). It earns a 4 rather than 5 because it could be tightened without losing critical detail, but it is far from bloated.

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

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

With no output schema, the description fully specifies return shapes: tracked[] with fields (edge_pp_net timeseries, first_seen, trend, decay_pp_per_day), expired[] with lifespan_days, and snapshot_dates[] with gap explanation. It also covers data limitations (TTL, snapshot start time) and computation basis. This is a complete and self-sufficient explanation for the agent.

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

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

Schema already documents both parameters with descriptions, including defaults and allowed values, so baseline is 3. The description repeats the defaults and adds only the phrase 'snapshot family' to frame window, but this is already in the schema. There is also a minor inconsistency: description says max 30 for days, while schema says clamp 2-30, which is a slight loss of precision.

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?

Uses a specific verb (tracker) and resource (polymarket edge snapshots) while clearly stating it measures edge persistence and decay. The phrase 'how long has this edge existed and is it shrinking?' crisply defines the tool's purpose and implicitly differentiates it from sibling polymarket_edges, which likely shows current edges.

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

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

Provides clear context: use when evaluating edge age/trend, and illustrates the difference between fresh vs. old edges ('a 3-week-old wide edge is wide for a reason nobody is willing to take'). However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of full disambiguation.

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 state readOnly and non-destructive, but the description adds critical behavioral context: it reveals the risk of partial basket fills converting arb into unhedged directional positions, names the 'forced_directional_risk' output, and clarifies that size_usd semantics differ between buy/sell and modes. This goes well 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?

Although long, the description is densely packed and structurally sound: it uses MODE headers, lists return fields, and separates guidance from parameter semantics. Every sentence serves a purpose—detailing modes, parameters, outputs, and usage warnings—making it an efficient reference for a complex tool.

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

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

For a tool with no output schema and two complex modes, the description fully compensates by enumerating all return fields (top_of_book, vwap_fill_price, per-leg fill detail, thin_legs, etc.), explaining edge cases, and providing risk warnings. It is complete enough for an agent to select and invoke the tool correctly without external documentation.

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

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

While schema coverage is 100%, the description significantly enriches parameter understanding: it explains that market vs event selects distinct modes, side defaults vary (buy_yes default in single, auto in basket), and size_usd means max spend on buys vs target proceeds on sells, or settlement notional in basket. This adds meaning beyond the schema's simple descriptions.

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

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

The description opens with a specific verb+resource phrase ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly defines two operational modes (single-market and basket). It distinguishes itself from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges, making its unique function evident.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable, partial fills create directional risk) and implies when not to use (small trades, no arb signal). This is exemplary guidance with clear alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral context beyond this: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the meaning of matched_pairs:0. It clearly explains what the tool does in edge cases and why spreads can be meaningless, which goes far beyond the annotations.

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

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

The description is long (about 200 words) but every sentence carries information that is not redundant with the schema or annotations. It is front-loaded with purpose, then modes, response, and safety fields. For a tool with this complexity and no output schema, the length is justified, though it could be tightened slightly.

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

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

Given that there is no output schema, the description thoroughly covers the return semantics: leg-by-leg prices, spread struct, compatibility_warning, temporal_alignment, and skip counters. It explains ambiguous failure modes (e.g., matched_pairs:0 with/without skipped_cross_type) and the significance of temporal misalignment. This is complete for the tool's complexity.

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

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

The schema descriptions already cover all three parameters (topic, kalshi_event_ticker, polymarket_event_slug) with examples and override semantics. The main description adds the meta-level mode logic, explaining how topic shortcuts auto-map to events and how explicit overrides work. Since schema coverage is 100%, the baseline is 3, but the added mode context 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 clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by focusing on cross-venue comparison, while tools like polymarket_arbitrage and polymarket_edges focus on within-venue signals. It also outlines two distinct modes, making its purpose concrete.

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

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

The description provides explicit usage guidance: it explains the two modes (topic shortcuts vs. explicit ticker/slug pairings) and warns that most pre-mapped topics return compatibility_warning today, implying when the tool should not be trusted. However, it does not explicitly compare against alternative sibling tools or state when to use another tool instead, so it falls just 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 indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful context about scoping (anonymous IP, BYO key hash, or account ID) and the omit-key behavior for listing all keys, going 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 three sentences, front-loaded with the action, and every sentence provides value—semantics, usage rationale, scope, and pairing with related tools. No redundant content.

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

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

For a simple 1-parameter tool with comprehensive annotations and full schema coverage, the description fully explains what the tool does, when to use it, and its scoping. The return behavior (value or list of keys) is implied and sufficient without an output schema.

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

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

The schema covers the 'key' parameter 100%, but the description adds crucial semantics: omitting the key lists all saved keys. This extra detail elevates it beyond the baseline 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?

The description clearly states the tool retrieves a previously saved value or lists all keys, with a specific verb and resource. It distinguishes itself from related tools by explicitly pairing with 'remember' and 'forget', making its role clear.

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

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

The description explains when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and references sibling tools for related operations. It doesn't explicitly state when not to use it, but the use case is well-defined.

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 that mark_read:true mutates read state, but the annotations declare readOnlyHint=true. This is a direct contradiction: the tool can have side effects (marking events read) despite being annotated as read-only. The description itself is transparent, but the annotation conflict makes it untrustworthy.

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 long, front-loaded with the primary purpose, and every sentence adds value: what is returned, how to filter, mark_read behavior, and an alternative endpoint. 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 the annotation conflict, the description provides sufficient operational context: response fields (source, citation_uri, raw payload), filtering options, polling suitability, and an alternative access URL. It lacks explicit pagination or error handling details, but for a read-style tool with 5 optional params, this is adequate.

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 usage semantics beyond the schema: explains that 'type' filters to a specific subscription type (e.g., 'sec_8k'), 'since' uses ISO timestamps, and 'mark_read' affects future calls. This helps the agent understand param interaction and intent.

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 combination: 'Pull fired events from your subscription feed.' It clearly distinguishes this tool from siblings like list_subscriptions, subscribe, and unsubscribe, and specifies the source (evaluator-written events) and return payload contents (source, citation_uri, raw event payload).

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

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

Provides clear context on when to use the tool: for polling, filtering by type/since, and marking read. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, which is useful context, though it doesn't explicitly exclude sibling 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. Description adds substantial context: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to PatentsView sunset, input formats, and return structure. 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 dense but every sentence provides necessary information: purpose, supported sources, fallback behavior, date formats, return shape, and alternative tool. It is well-structured with quotes for user intent and examples, earning its length.

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

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

No output schema exists, so description compensates by specifying return structure (changes[] grouped by source, total_changes count, citation URIs). It also covers source-specific behaviors, failure modes, and input constraints, making the tool fully understandable without additional docs.

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

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

Input schema has 100% coverage with useful descriptions, so baseline is 3. Description enhances this by giving examples (ISO vs relative shorthand), recommending '30d' or '1m' for typical monitoring, and explaining value can be ticker or zero-padded CIK. Adds practical guidance beyond schema.

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

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

Description clearly identifies the tool as a change feed for a company over a time window, with specific verb ('change feed') and resource ('company'). It includes natural language triggers and explicitly differentiates from sibling tool entity_profile by contrasting dynamic changes vs static profile.

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

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

Provides explicit when-to-use guidance with example queries and states the alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' Also explains parallel call benefit and fallback behavior between sources.

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 idempotency and non-destructiveness. The description adds valuable context: storage as key-value pairs scoped by the agent's identifier, and persistence details (permanent for authenticated users, 24 hours for anonymous). This goes beyond the annotations and informs the agent about data lifetime and scoping 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?

Four sentences, each earning its place: purpose, when to use, storage mechanics, retention policy, and pairing with related tools. Front-loaded with the primary action, no filler or redundant phrasing.

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

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

For a simple two-parameter tool with no output schema and annotations present, the description covers the essential aspects: purpose, usage triggers, storage format, scoping, persistence, and related tools. No significant 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?

The schema already fully describes both parameters (key and value) with examples, so baseline is 3. The description adds the crucial meaning that the key is scoped by the agent's identifier, which is not in the schema. This clarifies how the key parameter behaves in context, providing extra value beyond the schema.

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

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

The description clearly states the tool's purpose: saving data for reuse later across conversations/sessions. It uses a specific verb ('Save') and resource ('data'), and explicitly distinguishes itself from sibling tools recall and forget by naming them as the paired operations for retrieval and deletion.

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 usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also names the alternatives (recall to retrieve, forget to delete), making it clear when to use this tool vs. 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 indicate read-only, open-world, and idempotent behavior. The description adds rich behavioral context: identifiers are labelled with source, unresolved identifiers are explicitly listed under `unresolved`, and LEI/FIGI enrichment degrades gracefully without dropping EDGAR results. It also mentions internal cascading lookups, giving the agent a clear model of the tool's execution.

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 examples and clearly structured into supported types. It is long but each section provides essential details without fluff. The density of information justifies its length, though it could be slightly more concise by trimming some example 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 having no output schema, the description thoroughly explains return structure for both types, including source attribution, unresolved handling, and fallback behavior. It also clarifies internal cascading and the replacement of multiple lookups, making the tool's behavior fully understandable 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 descriptions cover both parameters fully (100% coverage). The description adds significant meaning beyond the schema by explaining the output fields for each type (e.g., CIK, ticker, company_name, LEI, FIGI for company; RxCUI, ingredient, brand for drug), and provides input examples. It thus helps the agent understand the semantics of `type` and `value` more deeply than schema alone.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples like 'what's the ticker for…' and a clear verb 'resolve'. It explicitly differentiates from siblings by saying 'Use FIRST whenever you have a name but need an ID' and details supported types (company, drug) with their outputs.

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

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

The description explicitly tells when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It provides example intents and explains that it replaces 2-3 manual lookups, guiding the agent to choose this tool for name-to-ID resolution. It also covers graceful degradation, informing the agent that partial results are still returned.

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

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

Annotations already declare readOnly/idempotent safety. The description adds process detail (probes each entity with ai_visibility_check, ranks by score) and output shape (ranked list with score, confidence, signal density), which are not in annotations.

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

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

Three sentences, front-loaded with the primary action. Includes a concrete example ('does Claude know about us as well as our competitors?') and the return format, all without redundancy or filler.

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

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

Covers purpose, process, use case, and return values (ranked list with score, confidence, signal density). Given the read-only safety annotations and fully documented schema, the description is complete 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?

Schema description coverage is 100% and already explains all parameters (entities, models, _apiKey, context), including the first-entity-is-subject convention. The description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic) by stating it probes each entity with a specific tool and ranks results.

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

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

Provides an explicit use case ('competitive AI-marketing audits') and an illustrative question. It implies this is for multi-entity comparison but does not explicitly state when to use an alternative (e.g., ai_visibility_check for single entity).

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?

Even though annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds significant behavioral detail: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out.' It also discloses the return structure, going well beyond the annotation hints.

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

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

The description is moderately long but every sentence carries value, front-loading the purpose and usage. The return format list is dense but justified by the tool's complexity; no fluff or repetition of schema details.

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

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

There is no output schema, so the description must explain return values; it does so thoroughly with the summary block fields, per-advisory details, links, and alternatives. It also covers limitations, latency, and failure behavior, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% (both package and version are documented). The description reinforces that package is an npm package and clarifies NPM-only scope, but it doesn't add substantive meaning beyond the schema fields. 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 specific verb ('check') and resource ('npm package'), and defines it as a composite check across deps.dev and bundlephobia. It includes concrete use cases ('is X safe / popular / small') and differentiates from siblings by focusing exclusively on npm dependency analysis.

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

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

Explicit when-to-use guidance is provided ('Use whenever an agent asks...'), along with a clear exclusion ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This tells the agent exactly when to choose this tool and what alternative to use.

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, establishing the safety profile. The description adds valuable behavioral context by specifying the required jurisdiction format and the output's purpose for use with get_bill, enhancing the agent's understanding 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 two sentences, front-loaded with the purpose, and includes essential execution guidance (jurisdiction format, return fields, workflow linkage). Every sentence contributes information without redundancy.

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

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

For a search tool with a rich input schema and an output schema available, the description covers the essential context: how to specify jurisdiction, what results include, and how they connect to get_bill. Pagination and filtering options are already documented in the schema, so no further detail is needed here.

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 each parameter already described. The description adds minor value by giving concrete examples of jurisdiction values ('CA', 'NY', 'TX') and noting that OpenStates IDs are returned, but it does not significantly deepen parameter understanding beyond the schema 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 begins with a specific verb-action ('Search') and clearly identifies the resource ('bills') and scope ('any US statehouse'). It explicitly states the jurisdiction input format and lists the return fields, distinguishing it from sibling tools like get_bill and search_legislators.

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

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

The description provides clear context for use: it is a search tool that returns OpenStates IDs 'for use with get_bill', establishing a complementary workflow. However, it does not explicitly state when not to use it or mention alternative tools for similar tasks (e.g., search_legislators), 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?

Annotations already declare readOnlyHint and destructiveHint=false, so the description is not the sole bearer of safety information. The description adds value by disclosing that results include current/prior roles and contact details, giving the agent a sense of the data scope and temporal coverage. No contradictory behavior is mentioned, and it correctly aligns with the read-only, idempotent nature.

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-loads the core purpose, and packs filter and return-field information efficiently. No filler or redundant content exists, making it easy to scan and process.

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 7 optional parameters, an output schema, and strong annotations (read-only, idempotent, open-world), the description covers the essential purpose, filtering capabilities, and result content. Pagination semantics are implied by the schema's page/per_page parameters, and the output schema handles return details. Minor omissions like implicit AND-filter behavior are not critical given the available structured data.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description restates the filter keys (jurisdiction, name, chamber, party, district) but adds little beyond what the schema provides, except clarifying the "chamber" term corresponds to org_classification. This meets the baseline for high schema coverage without substantially enriching 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 opens with "Find state legislators," a specific verb+resource combination that clearly identifies the tool's function. It further differentiates from siblings like get_legislator (single-record fetch) by listing filter dimensions (jurisdiction, name, chamber, party, district) and the returned fields (name, roles, party, contact details, IDs), making the search scope 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?

The description conveys clear search-and-filter context, and the mention of filter fields implies it is for exploratory lookups rather than point lookups. It does not explicitly name alternatives or when-not-to-use scenarios, but its clarity and the presence of sibling tools like get_legislator provide enough implicit guidance for an agent to select this tool appropriately.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description adds substantial behavioral detail: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, and has a 200K character cap with truncation flagged. This is transparency beyond annotations, not a 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 longer than two sentences but every sentence earns its place: purpose, use case, pairing, technical details, and limits. It is front-loaded with the core action and structured logically with dashes and a semicolon. Minor redundancy ('saves context' and 'returns only the passages that matter' convey similar ideas) prevents 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?

Despite lacking an output schema, the description explicitly covers return values (passages, offsets, scores), the max input cap and truncation behavior, and the integration pattern with a sibling tool. It fully compensates for the missing output schema and provides 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?

Schema coverage is 100%, so the baseline is 3. The description adds real-world context: examples of queries ('supply-chain risk', 'fiscal year 2024 revenue'), clarifies text as 'already pulled' content, and mentions output offsets. While the schema already defines parameters well, the description enriches meaning with practical examples, justifying 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+scope: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by naming ask_pipeworx_grounded and explaining the difference ('ground over the relevant passages instead of the whole document'). The purpose is unmistakable and context-rich.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides a pairing workflow with ask_pipeworx_grounded, which serves as both a when-to-use and a when-not-to-use alternative. This is exemplary 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?

The description discloses many behavioral traits beyond the annotations: requires a Pipeworx OAuth account, anonymous/BYO cannot persist, phone must be verified, SMS has a 10/day cap, and the feed is always on. These details significantly enrich the agent's understanding of side effects and constraints, and there is no contradiction with annotations.

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

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

The description is front-loaded with the purpose and then details requirements, types, and delivery channels in a structured but dense manner. Every sentence contributes unique information, though it could benefit from bullet points for readability given the number of options.

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

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

Given the tool's complexity (5 types, 3 delivery channels, nested params), the description is very complete: it names the supported types, explains key examples, notes the OAuth requirement, and indicates the return value. It omits webhook details and patent_grant/clinical_trial specifics, but those are covered in the schema, so the description is adequate 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 has 100% parameter description coverage, the tool description adds meaning by providing concrete examples and domain context, such as explaining that items:["5.02"] indicates an officer change for sec_8k and clarifying that polymarket_edge detects cross-venue mispricings. This goes beyond the schema's terse parameter descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It uses a specific verb+resource pattern and distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context for when to use the tool: to create persistent subscriptions with specific types and delivery channels. It mentions the OAuth account requirement and points to recent_alerts for pulling the feed, but does not explicitly contrast with list_subscriptions/unsubscribe or state 'when not to use'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it returns category-bucketed example questions from a live catalog, each with tool and argument shape, and explains how the optional topic parameter changes the result (full spread vs. focused). 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 every sentence earns its place. It front-loads the core purpose with example queries, then details return format, parameter behavior, and usage guidance. The structure uses em-dashes and lists effectively, making it scannable and complete without redundancy.

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

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

With no output schema, the description carries the burden of explaining return values, which it does (category-bucketed example questions with tool + argument shape). It also covers no-argument vs. topic usage and ties into the broader tool ecosystem. For a simple 1-parameter tool, this is complete.

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

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

Schema coverage is 100% and the optional 'topic' parameter already includes a description listing valid values and the omit behavior ('Omit for a cross-category spread'). The description adds example values (finance, pharma, betting) and reinforces the focus effect, but does not provide substantial meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool is the onboarding entry point for an agent that just connected, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like discover_tools and ask_pipeworx by explicitly positioning itself as the 'FIRST' step to learn what Pipeworx can do.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions it helps learn how to call meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.). This provides clear when-to-use context and names alternatives, satisfying the usage guidance dimension fully.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses two significant behaviors: ownership is enforced, and the operation performs a soft deactivation rather than a physical delete, which preserves historical data. This adds meaningful context about side effects and consequences that the annotations do not capture.

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

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

The description is three concise sentences, each serving a distinct purpose: the action, the ownership restriction, and the side-effect behavior. No filler or repetition of schema/annotation details. Properly front-loaded with the action verb.

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 cancellation tool, the description covers purpose, ownership, and the soft-delete behavior. It references recent_alerts for understanding the preservation of history. A return value is not described, but that is a minor gap for a straightforward cancellation operation; the tool is adequately contextualized.

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 a full description of the 'id' parameter ('Subscription id (uuid) returned by subscribe'), so schema coverage is 100%. The description adds an extra semantic constraint: the id must belong to the caller's own subscription, which is not stated in the schema. This elevates the parameter meaning beyond schema alone.

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 'Cancel a subscription by id,' a specific verb+resource+identifier statement. It clearly differentiates from sibling tools like subscribe and list_subscriptions by focusing on cancellation, and the additional detail about deactivation (not deletion) further distinguishes it from a hypothetical delete operation.

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?

Ownership enforcement ('you can only cancel your own subscriptions') provides a clear constraint on when the tool applies. The note that the row is deactivated rather than deleted, with historical events preserved via recent_alerts, implies the tool is appropriate when preserving history matters. However, no explicit alternative tool is named or 'when not to use' scenario is provided, so it doesn't fully meet the 'explicit alternatives' bar.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: two distinct execution paths (SEC EDGAR/XBRL vs. grounded), verdict semantics, and a critical warning that could_not_verify means the check did not happen and must not be treated as evidence. It also clarifies that unsupported means no source exists. This goes far beyond the annotation baseline.

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?

Although long, the description is front-loaded with trigger phrases and purpose, then systematically covers routing, return verdicts, and failure-mode interpretation. Every sentence contributes unique value—no filler or redundancy—making the length proportionate 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 fully explains when to use, what it returns (verdicts, actual value, citation, reasoning), and how to interpret failure modes (could_not_verify vs. unsupported). Given there is no output schema, the description carries the full burden for return semantics and does so comprehensively.

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

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

Schema description coverage is 100% and both parameters (claim, tolerance_pct) are thoroughly documented there. The description adds only general context (e.g., 'exact percent-delta math') without introducing new parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description opens with natural-language trigger phrases (e.g., 'Is it true that…', 'fact check') and clearly states its function as 'natural-language claim verification against authoritative sources.' It distinguishes this from sibling tools by framing it as yes/no fact-checking of user claims rather than general Q&A, and it explicitly mentions replacing 4–6 sequential calls, making the tool's unique purpose unmistakable.

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

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

Explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct' and provides internal routing rules for company-financial vs. other claims. It lacks an explicit 'when not to use' or named alternative sibling tool, but the strong contextual guidance (including the fallback pipeline) is sufficient for most callers.

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